@displayxr/inline3d 1.50.0 → 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/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/half-sbs.js

@@ -45,14 +45,31 @@ export async function unsqueezeHalfSbs(source) {
   }
   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);
+}
 
-  const { width, height } = unsqueezedSize(st.width, st.height);
+/**
+ * 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(st.frameRate > 0 ? st.frameRate : 30);
+  const stream = canvas.captureStream(frameRate > 0 ? frameRate : 30);
   const track = stream.getVideoTracks()[0];
   const reader = new MediaStreamTrackProcessor({ track: source }).readable.getReader();
 
@@ -68,6 +85,15 @@ export async function unsqueezeHalfSbs(source) {
     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();
     }

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;

package/js/inline3d-splat-playcanvas.js

@@ -587,14 +587,22 @@ export function capturePose(rest, flipY) {
  * (epic #36, P4d); until then the anchors are regexes (the npm build re-indents chunks with
  * tabs) and a miss warns once and renders unpatched rather than failing.
  *
+ * PlayCanvas 2.23 fixed it upstream: its perspective branch takes the focal length per axis
+ * (`vec2 focal = viewport_size.xy * vec2(center.projMat00, center.projMat11)`). That chunk is
+ * returned untouched with `native: true` and counts as fixed — it is not a miss, and must not
+ * warn that splats will draw at half height.
+ *
  * The rewritten lines are adapted from PlayCanvas engine src/scene/shader-lib/glsl/chunks/gsplat/vert/
  * gsplatCorner.js (the `gsplatCornerVS` chunk) @ v2.22.3, MIT (THIRD_PARTY_NOTICES.md).
  *
- * @returns {{src:string, ok:boolean}}
+ * @returns {{src:string, ok:boolean, native?:boolean}}
  */
 export function patchGsplatFootprint(src) {
   if (typeof src !== 'string') return { src, ok: false };
   if (src.includes('dxrFocalY')) return { src, ok: true };
+  if (/vec2\s+focal\s*=\s*viewport_size\.xy\s*\*\s*vec2\s*\(\s*center\.projMat00\s*,\s*center\.projMat11\s*\)/.test(src)) {
+    return { src, ok: true, native: true };
+  }
   const r1 = /vec2\s+J2\s*=\s*-J1\s*\/\s*vp\.z\s*\*\s*vp\.xy\s*;/;
   const r2 = /0\.0\s*,\s*J1\s*,\s*J2\.y\s*,/;
   if (!r1.test(src) || !r2.test(src)) return { src, ok: false };
@@ -1542,7 +1550,7 @@ export class PlayCanvasSplatViewer {
     // handle.engine.root on a model tile gets the engine's stock footprint (documented).
     const chunks = patchSplats ? pc.ShaderChunks.get(device, pc.SHADERLANGUAGE_GLSL) : null;
     const corner = chunks ? patchGsplatFootprint(chunks.get('gsplatCornerVS')) : { ok: false, skipped: true };
-    if (corner.ok) chunks.set('gsplatCornerVS', corner.src);
+    if (corner.ok && !corner.native) chunks.set('gsplatCornerVS', corner.src);
     else if (!corner.skipped && !warnedFootprint) {
       warnedFootprint = true;
       console.warn(

package/llms.txt

@@ -4,8 +4,8 @@
 > canvas, the DisplayXR Browser weaves them for the panel; an ordinary browser shows the page in 2D.
 
 Read first: docs/making-3d-look-right.md — nine depth and comfort rules from real panels
-(keep the viewers' object placement and frame the first view, lay flat arrangements back into
-depth, keep moving things' forward swing small, fixed convergence and no near geometry in worlds,
+(the default depth is the glass: centre the subject on z = 0 and frame the first view; tilt flat
+arrangements about an axis through the glass, don't push them back; keep moving things' forward swing small, fixed convergence and no near geometry in worlds,
 low contrast behind the subject, text as HTML near the glass, no coplanar surfaces, no sub-pixel
 detail, a cover that always comes off). The SDK's defaults do the rest.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.50.0",
+  "version": "1.51.0",
   "description": "Turn any HTML <canvas> into a 3D window on a spatial display, inside an ordinary web page, for the DisplayXR Browser. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",