@displayxr/inline3d 1.46.0 → 1.47.0

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

@@ -0,0 +1,49 @@
+# Depth and comfort on a 3D display
+
+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
+   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.
+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
+   on fast moves.
+4. **Worlds: keep convergence fixed, and keep near things away.** On a camera rig, set
+   `convergence` once for the scene, or change it slowly when the scene changes. Never set it from
+   where the user is looking: whatever they look at lands on the glass and goes flat. Never set it
+   to 0. Near geometry is where a world goes wrong: a window frame, a wall or a crossbar close to
+   the camera comes far out of the glass and ghosts. Keep the visitor's camera well clear of
+   walls and furniture, or lower `ipdFactor` while it is close.
+5. **Low contrast between the subject and what is behind it.** The display's crosstalk correction
+   works only within the range of the image, so a bright edge on black ghosts first. A light or
+   mid-tone, low-contrast background works best: a real texture or a soft gradient, not generated
+   noise. A dark grey is the minimum, and pure black is the worst case; keep the subject's darkest
+   faces above the background. Soften high-contrast detail far from the glass in the colours and
+   materials, not with fog, since camera-distance fog follows the viewer's head.
+6. **Text: flat HTML near the glass, at a readable size.** Text drawn in the 3D scene, especially
+   white on dark, ghosts. Put titles, labels and values in HTML, or keep in-scene labels close to
+   the glass, facing the viewer, and show them on hover. Never shrink text to hide ghosting.
+7. **No coplanar surfaces.** Z-fighting (two faces at the same depth flickering through each
+   other) is the most common defect seen on panels, and in 3D it reads as shimmer at one depth.
+   Offset decals, shadows, shelf faces and picture frames from the surface they sit on. Keep
+   geometry solid: no paper-thin or floating floors, no holes in rocks, nothing clipping through
+   glass.
+8. **No detail finer than a few pixels.** Thin lines, single-pixel stars and fine repeating
+   patterns alias and shimmer as the head moves. Draw them thicker, softer or as sprites, and size
+   textures to their surfaces instead of stretching them.
+9. **A cover over the canvas must always come off.** If you hide the canvas until `firstWoven`,
+   also remove the cover after a few seconds and if your setup throws. Otherwise a missed signal
+   leaves the page with its UI and no scene.
+
+The mechanics (one view per eye, CSS that breaks the weave, the 2D/3D switch) are in
+[woven-canvas-rules.md](woven-canvas-rules.md) and [authoring-inline-3d.md](authoring-inline-3d.md),
+which also gives the comfort zone in diopters and how the same content changes from a large
+monitor to a phone. The samples show how the API works, not how a page should look.

package/docs/woven-canvas-rules.md

@@ -0,0 +1,378 @@
+# Woven canvas rules: never show a raw side-by-side frame
+
+Companion to [`authoring-inline-3d.md`](authoring-inline-3d.md). That page explains what a woven
+window is. This one covers the failure that shows up on the first real deployment: for a moment,
+sometimes a full second, a 3D tile shows **two squeezed halves side by side** instead of 3D. It
+happens most often right after a navigation.
+
+The rules below come from a production kiosk that chased this symptom for a week. They were then
+checked against the DisplayXR Browser's compositor source. Every rule gives the reason for it
+and the SDK call that satisfies it.
+
+---
+
+## 1. What the page is actually seeing
+
+A woven window's backing buffer holds side-by-side (SBS) stereo ([the one
+contract](authoring-inline-3d.md#the-one-contract-you-must-understand)). The browser weaves that
+buffer onto the display **only once its compositor has *joined* the canvas**: it has matched the
+rect your layer reports to the quad the canvas actually drew in this frame. Until the match
+lands, the browser **withholds** the rect. The weave does not touch it, and what reaches the
+screen is the page's own raster of the canvas, which is the raw SBS pair squeezed into the box.
+That is the flash.
+
+Four facts about the join matter to a page:
+
+- **Constructing the layer is not the join.** `new XRDisplayLayer()` (what `addImage` /
+  `addVideo` / `addScene` do for you) registers the canvas. The browser's compositor joins it
+  later, on its own schedule.
+- **A canvas that is fresh to the compositor takes longest.** The browser measured the window at
+  **0.4–1.2 s** on a same-document navigation, where the outgoing screen's canvas dies in the same
+  frame the incoming one is born. In the frames captured during that window, the incoming
+  canvas had **not yet committed a real frame**: its backing store was still the default
+  `300×150`. The compositor's view of the page was also still half the previous screen, so
+  nothing in the frame *was* the new tile. No browser-side fallback can draw a frame it does not
+  have. The page owns this case.
+- **Nothing tells the page when the join lands.** Session frames, views and layer methods all
+  look the same before and after the join. Views come from the runtime's eye locate, which knows
+  nothing about the compositor. See [the browser ask](proposals/layer-joined-signal.md).
+- **Your content arriving fast makes it worse.** The flash can only happen when real SBS pixels
+  are already in the canvas while the join is still missing. A cached asset lands in tens of
+  milliseconds, well inside the window. A slow asset usually lands after it. This is why the
+  flash tends to affect one screen and not another screen built the same way.
+
+So the page cannot make the join land sooner. What it controls is **whether stereo pixels are
+on screen while the join is missing**.
+
+## 2. The rules
+
+### 1. One inline-3D session per document
+
+The browser's element-rect channel is one whole-widget list. Two live managers overwrite each
+other's list every frame, and a tile that is missing from the list is never joined. Call
+`createInline3D()` **once** and add every window to it. The SDK warns if a second one goes live.
+Between routes, `close()` the old manager before you open the next one, or better, keep one
+manager for the life of the document.
+
+### 2. Never remount a woven canvas inside a screen
+
+A new `<canvas>` element brings a new WebGL context, and a new subject for the compositor to join.
+Remounting on a state change (a React key change, or a Strict Mode double mount) re-creates the
+window from §1 on purpose, every time. It can also hand the second renderer a context the first
+one already disposed of, which freezes silently. Hold the canvas in a ref your framework never
+re-renders over, and change what is **in** it:
+
+- **Images and video:** register once and redraw the source. `addImage(canvas, sourceCanvas)`
+  repaints from a canvas you own every frame
+  ([motion, §1](authoring-motion-and-effects.md#what-to-do-instead)).
+- **Scenes:** swap the content inside your `onFrame`, never the canvas.
+- **Splats on the PlayCanvas backend:** `handle.setSource(src, { fadeMs, resetPose })`.
+
+Calling `add*()` again on the same canvas is not a content swap. It closes the window's layer and
+builds a new one (a fresh identity gap), and on `./splat` / `./model` it puts a second renderer on
+the context. Since 1.38 the SDK warns about it, once per canvas, while the first registration is
+live (not `remove()`d), then proceeds as before. To re-register on purpose, `remove()` first.
+
+### 3. Prefer one persistent canvas for the whole app
+
+A canvas that survives every route change is fresh to the compositor exactly once, at boot. The
+window from §1 then exists once instead of on every navigation. This is the only rule that
+*removes* the race instead of shortening it. The cost is architectural: a shared "stage" in the
+root layout that each screen attaches content to, instead of each screen owning a canvas. If you
+can pay it, rules 4 and 5 become boot-time concerns only.
+
+### 4. If a canvas must be created after a navigation, commit it before you register it
+
+The measured flash frames had the new canvas at its default size, with no real frame committed.
+Give the compositor a settled canvas before you ask it to join one:
+
+1. Put the canvas in the DOM with its final CSS box and **`will-change: transform` from its first
+   paint**, in your stylesheet. The SDK sets `will-change: transform; transform: translateZ(0)`
+   at registration, which is one frame too late for a canvas's first appearance.
+2. For `addScene`, **size the backing store yourself first**: 2× the box's aspect ratio, as the
+   buffer will be while woven. The SDK never sizes a scene canvas. `addImage` / `addVideo` size
+   theirs on activation.
+3. Wait **at least two animation frames**, then call `add*()`.
+
+This **shortens** the window. It does not close it: a page that deferred registration by four
+frames still produced withheld frames on the browser's test rig. Rule 5 is the one that
+guarantees the result.
+
+### 5. Keep the canvas covered until `handle.firstWoven` resolves
+
+Never let stereo pixels reach the screen before the first woven frame. Stack a cover over the
+canvas: the poster, or an opaque block of the page background.
+
+- **On top of the canvas, never behind it.** A canvas with opaque pixels hides whatever sits
+  underneath, whatever that layer's own opacity.
+- **A hard cut, never a fade.** A congruent sibling fading over the tile is its own version of
+  the flash: a partial-opacity plate the size of the tile is exactly what rule 7 forbids.
+- **Released on `handle.firstWoven`, not on first paint, and not on your own timer.**
+
+```js
+const handle = wall.addScene(canvas, onFrame);        // or addImage / addVideo / addSplat / addModel
+await Promise.all([contentReady, handle.firstWoven]); // your load + the SDK's woven signal
+poster.remove();                                       // cut, never fade
+```
+
+`handle.firstWoven` resolves **once and never rejects** with `{ woven, confirmed, reason, ms }`:
+
+| result | meaning | what to do |
+|---|---|---|
+| `woven: true`, `reason: 'woven'`, `confirmed: true` | the browser reported the layer woven (`XRDisplayLayer.wovenState`), after a real stereo frame | drop the cover |
+| `woven: true`, `reason: 'hold-elapsed'` | a browser without that report: the window has drawn a real stereo frame on a layer that has existed for `firstWovenHoldMs` (default **1200**, the browser's measured worst case) | drop the cover |
+| `woven: false`, `confirmed: true`, `reason` a withheld token (or `'pending'`) | the browser kept reporting the layer withheld for the whole safety cap (four holds, at least 4.8 s). The canvas is not taken flat | drop the cover, then read the token in §3: it names the page fix |
+| `woven: false`, `reason: 'layer-failed'` / `'session-ended'` / `'removed'` | this window will not weave. An image or video canvas has already been painted flat, and a scene's `onLayerLost` has already run | drop the cover onto the 2D fallback |
+| `woven: false`, `reason: 'unsupported'` (`addSplat` / `addModel` only) | no inline-3D session: the viewer is on its mono path | same |
+
+**`confirmed` says which of the two you got.** A DisplayXR Browser build with the join report
+(`XRDisplayLayer.wovenState`, Windows, behind a flag; detected with `'wovenState' in
+XRDisplayLayer.prototype`) settles `firstWoven` on the report: `confirmed: true`, no hold. On
+every other browser `firstWoven` is the documented worst case, measured by the SDK so that each
+page does not measure it separately (`confirmed: false`). **The page code is the same on both**,
+which is the reason to code against it rather than keep a local `setTimeout`. To see the report
+yourself, read `handle.wovenState` (`'pending'`, `'woven'`, `'withheld'`, or `null` where absent)
+and `handle.withheldReason`. Background: [`proposals/layer-joined-signal.md`](proposals/layer-joined-signal.md).
+
+What counts as a "real stereo frame": for a scene, an `onFrame` that received two or more views
+and did not throw. A frame with a short view list is the load fallback, and a frame that threw
+drew nothing. For an image, an SBS paint of a loaded image. For a video, an SBS paint of a
+`<video>` that has a current frame. A lazy tile that scrolls away before settling starts the
+hold again on its next layer. `onFirstWoven(cb)` is the callback form.
+
+Lower `firstWovenHoldMs` only for a canvas you know is not fresh to the compositor, for example
+the persistent stage from rule 3 after its first ever reveal. `0` means "the first stereo frame".
+
+**On a browser without draw-order occlusion** ([`inline3dOcclusionByDrawOrder()`](authoring-inline-3d.md#asking-which-mechanism-you-are-on)
+is `false`), a cover over a *joined* tile is woven along with it. There, the cover looks
+lens-scrambled from the moment the join lands until it is released. Do not mark a full-tile cover
+`data-inline3d-overlay`: the SDK refuses a full-tile overlay with a warning on those browsers
+(rule 8), and ignores it on draw-order browsers.
+
+### 6. Hard-cut between screens: never have two woven canvases crossfading
+
+A transition that blends the outgoing screen's canvas into the incoming one, by animating
+`opacity` on either canvas or on their wrappers, breaks rule 7 on **both** canvases for the whole
+fade. It also creates a case the compositor refuses outright. A canvas inside a render surface
+can only be matched by shape, as the one 2:1 resource covering its rect. Two such candidates in
+one region are **refused as ambiguous**, and neither is drawn from. Cut between screens. To blend
+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.
+
+### 7. No CSS effects on a woven canvas or on any of its ancestors
+
+`filter`, `opacity < 1`, `mask`, `clip-path`, `mix-blend-mode`, `backdrop-filter`: any property
+that makes the browser give an element **its own render surface**. When the canvas or one of its
+ancestors has one, the canvas is drawn into that surface instead of the page's root pass. Its
+identity does not survive that, so the direct join misses. The best the browser can then do is
+draw the tile **flat** (one eye, no 3D) in place, and sometimes it cannot find the tile at all.
+The same goes for `border-radius`, `box-shadow` and `border` on the canvas: they are woven with
+the packed pair and come out lopsided after the eye split. Use the SDK's options instead:
+
+- rounded corners: `cornerRadius` on `addImage` / `addVideo`, or clip each viewport in a scene
+  ([rounded corners](authoring-inline-3d.md#rounded-corners));
+- a soft edge: `feather`;
+- anything else: draw it into the canvas, per eye.
+
+Scrolling and a *static* ancestor translate are fine. Animating the tile's geometry is a separate
+rule ([motion, §1](authoring-motion-and-effects.md#1-why-a-woven-tile-must-not-move)).
+
+### 8. Chrome over a woven canvas is a partial region
+
+A caption band, a badge, a menu: on a browser with draw-order occlusion these need nothing
+([2D over 3D](authoring-inline-3d.md#2d-over-3d--draw-order-occlusion)). On an older browser, mark
+them `data-inline3d-overlay` (or call `handle.exclude(el)`), and keep them **smaller than the
+tile**. An overlay congruent with the tile matches the canvas's own quad, so the SDK refuses it
+with a warning rather than destroy the tile. Hide an overlay with `display: none`, never
+`opacity: 0`. The declaration costs nothing on a draw-order browser, so one page works on both
+generations.
+
+### 9. Nothing with a background sits above the woven canvas; black goes under it
+
+A section, wrapper or later sibling with an opaque background, painted over the canvas, hides the
+tile while its content keeps running (for a video: sound, no picture). To put black around a
+tile, give it to an element **behind** the canvas. A cover you mean to hide the tile with (rule 5,
+rule 11) is the one deliberate exception, and it comes off on a signal.
+
+### 10. No `backdrop-filter` on anything drawn over the weave
+
+Rule 7 covers the canvas and its ancestors. This one covers the **siblings on top of it**: a
+control bar, a caption, a badge, a menu. `backdrop-filter` is defined as a function of what is
+behind the element, and behind it is the interlaced weave. A blur reads the interlaced pixels
+and smears them, and the 3D image is disturbed across the element's **whole box**, not only
+where the element is opaque (seen on the panel, 24 September). Use a plain translucent tint
+(`background: rgba(0, 0, 0, 0.55)`) instead. The SDK's own player chrome follows this rule.
+
+### 11. Treat a resize as a fresh-canvas moment
+
+Resizing a woven canvas's rect re-registers it with the compositor, and the new rect can go
+through the same **0.4–1.2 s** identity gap as a new canvas (§1): until the join lands, the
+screen may show the page's own raster, which is the squeezed side-by-side pair (the panel A/B
+below did not see one, so treat the cover as insurance, not a certainty). Entering or leaving
+fullscreen, a responsive reflow that changes the tile's size, and a layout that swaps a small
+tile for a large one all do this. Cover the canvas across the change exactly as in rule 5 (on
+top, hard cut), and release on **`handle.rewoven()`**:
+
+```js
+cover.hidden = false;                 // before the rect changes
+await el.requestFullscreen();
+await handle.rewoven();               // a stereo frame on the moved rect, plus the hold
+cover.hidden = true;                  // cut, never fade
+```
+
+`rewoven()` is `firstWoven` measured from the call, with the same result shape. A change of the
+canvas's CSS size, devicePixelRatio or page position while it is pending restarts the hold
+(checked every frame, for every window kind), so a resize or a move that settles over several
+frames is covered until the last one. Position is measured in page coordinates, so scrolling the
+document is not a move (since 1.38; before, a move without a resize was not detected at all). So
+that a size that never stops animating cannot hold the cover up for good, it settles anyway
+(`reason: 'hold-capped'`) four holds after the call. Before the first join it is `firstWoven`
+itself. The SDK's player (`addPlayer`) does this for its own fullscreen button with
+`fullscreenCover: true`.
+
+**The SDK covers rect changes for you on `./splat` and `./model`** (1.38, `rectCover: 'auto'` by
+default there). After the first join, a move or resize of the canvas raises a cover over it on
+the frame the change is seen: a solid color with the last frame's left eye, cover-fit. The cover
+comes down when `rewoven()` settles. Pass `rectCover: 'off'` if the page runs its own cover. On
+core windows (`addScene` / `addImage` / `addVideo`) the same primitive is opt-in: pass
+`rectCover: 'auto'` (or `{ color, snapshot }`), or keep your own cover and release it on
+`handle.rewoven()`. A move is seen at the next session frame, so a move your page makes after that
+frame's callback can show for one frame. Move the canvas from an event handler or before the frame,
+not from a later animation callback.
+
+**Measured on the Leia panel (26 September, browser test build with patch 0195, blind A/B, one
+observer):** entering and leaving the player's fullscreen showed **no** raw side-by-side pair,
+with or without the cover. Without it, leaving fullscreen showed the picture at once and then a
+flash of the **whole browser viewport** about a second later. With it, the picture was hidden for
+~1.2 s and the flash was still there. The flash is browser-side and wider than any tile, so no
+page cover can hide it. That is why the player's cover is opt-in. Keep the rule for a page whose
+resize does show the pair.
+
+A scroll is not a resize. The canvas keeps its size and its identity, and nothing needs covering.
+
+### Two rules that keep a joined canvas joined
+
+- **Redraw every frame.** A canvas that is not redrawn can drop out of the frame the compositor
+  aggregates. The weave then reads a stale sub-rect and the tile smears. The SDK repaints
+  `addImage` / `addVideo` windows every frame, including a buffering video (it re-commits the
+  last frame). A scene must draw in every `onFrame`, and on a frame it cannot draw it must
+  **replay the last good one** rather than skip ([validate before you
+  clear](authoring-inline-3d.md#3-live-scene-threejs--webgl--addscenecanvas-onframe-opts)).
+  `./viewer`, `./splat` and `./model` already do this, and since 1.38 they also draw on the frames
+  before the first good one: the mono camera into both halves, the subject if it is loaded, or a
+  cleared frame if it is not. The only undrawn frames left are the ones before the engine has
+  created its context. The SDK cannot enforce this for an `addScene` window your page draws: draw
+  something on every `onFrame`, even with no content yet. When you keep the last good frame,
+  copy the viewport's and view's fields **by name**: `XRViewport` and `XRView` fields are
+  prototype getters, so `Object.assign` and spread copy nothing and the replay draws into a 0×0
+  viewport, which weaves black ([details](authoring-inline-3d.md#3-live-scene-threejs--webgl--addscenecanvas-onframe-opts)).
+  - **Known limitation: a transparent canvas weaves black.** A cleared (fully transparent) woven
+    frame comes out black on the panel, not see-through: a browser bug (browser-pvt #255), not
+    the SDK's. Until it is fixed, a frame with nothing to show is drawn but dark. If the page
+    behind the tile is not black, cover the tile until its content is in (rule 5).
+- **Large scene canvases: consider `preserveDrawingBuffer: true`.** On older DisplayXR Browser
+  builds, the weave's zero-copy read of a full-window WebGL canvas can race the page's next
+  write, and the frame is dropped. Keep the SBS buffer no wider than the panel, and try
+  `preserveDrawingBuffer` on the renderer (`addSplat(…, { engine: 'playcanvas',
+  preserveDrawingBuffer: true })` on the PlayCanvas backend). See
+  [porting pitfall 26](porting-three-js-apps.md#9-pitfalls-register).
+
+## 3. Verifying a new screen on hardware
+
+A 2D browser can check your call order (the tests in this repo drive a stubbed `XRDisplayLayer`
+for exactly that reason). It cannot check the join. On a DisplayXR display:
+
+1. **Stereo is arriving.** `handle.stats()` reports `{ frames, monoFrames }` per scene window. A
+   high `monoFrames` share means the session is falling back under load.
+2. **When the page thinks it is safe.** Log `(await handle.firstWoven).ms` and the time you
+   registered. Log per-frame canvas size for the first two seconds as well, to see when the
+   backing store actually became 2:1.
+3. **What the browser actually did.** Launch the DisplayXR Browser with `--enable-logging` (add
+   `--v=1` for the render-surface lines below), reproduce, and read `chrome_debug.log` in the
+   browser's user-data directory:
+
+   ```
+   [DisplayXR] inline-3D withheld N of M weave rects: … ids=[<token>=<why>@<rect> …]
+   ```
+
+   The line is **throttled**: the first three occurrences, then one in every 300. A missing line
+   on a given frame proves nothing. Visible tiles are named, up to 16, and off-viewport tiles are
+   reduced to `+N offscreen`. What `<why>` means:
+
+   | `why` | what it means | whose fix |
+   |---|---|---|
+   | `no-identity` | the canvas's rect reached the browser without the identity the join needs. This is the raw-pair flash from §1: the page's own pixels are on screen | page: rules 3–5 |
+   | `no-quad` | the canvas drew nothing the compositor can see: it is not drawing, or it is occluded, or it is inside a render surface the browser could not trace | page: rule 7, or check that the canvas is drawing |
+   | `cross-pass:mono`, `cross-pass:mono(cover,2:1)` | the canvas is inside a render surface (rule 7). The browser found it and draws it **flat in place**: no raw pair, but no 3D either | page: remove the ancestor effect |
+   | `no-join` | nothing joined this rect. Seen at `@0,0 0x0` for lazy tiles pre-armed off screen, where it is harmless | page, if the rect is on screen |
+   | `resolve-dropped` | the canvas joined, but its GPU resource could not be resolved this frame | browser |
+
+   With `--v=1`, a separate `inline-3D cross-pass COVER … REFUSED ambiguous` line means rule 6:
+   two 2:1 candidates in one render-surface region. Remove one of them.
+4. **Which browser build has which fix: read the device, not a version string.** A version
+   number does not tell you which compositor changes a build carries. The `why` token on the
+   unit tells you what that build did. Browser release notes that list such changes are tracked
+   separately.
+
+## 4. What stays browser-owned
+
+- **The join window itself.** Its 0.4–1.2 s length on a fresh canvas is compositor state that no
+  page-side sequencing controls. Rules 3–5 exist *because* of it. A browser-side mono fallback
+  for this exact case was built and measured, and it did not ship: in the measured frames nothing
+  in the compositor's frame was the incoming canvas, so there was nothing to draw flat from.
+- **Reporting the join.** Only the browser knows when a canvas has been joined. Until it reports
+  that, `handle.firstWoven` is a timer with a stable contract. The request, and the shape it
+  asks for, is [`proposals/layer-joined-signal.md`](proposals/layer-joined-signal.md).
+
+## 5. Pitfalls from production (September 2026)
+
+Found on hardware in a production photo app after the rules above were written. Each one looked
+like a runtime or browser bug on the panel and turned out to be the page.
+
+- **No `backdrop-filter` on chrome that sits over the weave.** Rule 7 covers effects on the canvas
+  and its ancestors. A frosted bar or button placed *over* a woven tile is a different element, but
+  on a lenticular laptop panel it visibly disturbs the 3D image across that element's whole rect.
+  Use a plain translucent tint instead (a solid `rgba()` background). Keep an A/B switch for the
+  blurred variant if the design wants it back, and judge it on the panel, not on a 2D monitor.
+- **Nothing opaque above the woven canvas.** Stacking order still applies: an element with an
+  opaque background painted *above* the canvas hides it, and on a draw-order browser that is
+  exactly what you get. The classic case is a full-bleed video plane under a page `<main>` with
+  `background: #000`: the sound plays and the picture is black. Dark or blurred backdrops go
+  *under* the canvas, as their own element.
+- **Don't mount the woven canvas on 2D-only routes.** A route with no 3D content (an upload page, a
+  settings screen) should not host the stage at all. Where the woven canvas has to stay mounted
+  (one session, never remount: rules 1–3), request the 1-view mode for the flat screen instead:
+  `wall.setStereoEnabled(false)`, then `true` again before the next stereo content appears. The
+  1-view mode is real full-resolution 2D, not a flattened weave: the panel's 3D optics switch off,
+  nothing is woven, and DOM text is native-resolution. Confirm with
+  `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.
+- **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,
+  which reads on a tracked panel as "head tracking stops": no frames, so the image cannot follow
+  the head. SDK 1.22.0 made pick bursts cheap (a pick index), but the rule stands: defer or spread
+  work after a swap, and gate diagnostics behind a flag. `?dxrdiag=1` names what is on the main
+  thread per transition phase (`picks`, `gl`, `afterSettleTaskMs`, `longFrames`), so check it
+  before blaming the SDK or the browser.
+- **Don't hold or blend rigs yourself around a transition.** Since SDK 1.24.0 each photo in a
+  two-splat transition is drawn through its own camera rig for the whole transition, including the
+  frame or two before the runtime delivers views for a newly declared rig. Declare each photo's rig
+  (or let the SOG camera block do it) and let `setSource` handle the swap: holding the old rig or
+  easing between the two moves one of the photos.
+- **Don't assume `canvas.width` is the buffer.** A WebGL canvas larger than the device's limit is
+  clamped by the browser with no error: `canvas.width` keeps the value you set while
+  `gl.drawingBufferWidth` is smaller. An Android 3D tablet (Adreno 740) reports `MAX_TEXTURE_SIZE`
+  4096 where desktops report 16384 (the Chromium driver workaround tracked in browser-pvt#187), so a
+  full-screen SBS canvas at 5120 wide came out 4096 wide. `XRDisplayLayer.getViewport()` splits
+  `canvas.width`, so the eye boundary landed at 62.5% of the buffer while the weave split it at 50%:
+  a large double image. `./viewer`, `./splat`, `./model` and `addImage` / `addVideo` clamp the store
+  before sizing it (both axes by one factor) and warn once; `handle.renderScale` then reports the
+  scale in force. An `addScene` page sizes its own canvas: keep 2 × eye width and the height within
+  min(`MAX_TEXTURE_SIZE`, `MAX_RENDERBUFFER_SIZE`, `MAX_VIEWPORT_DIMS`), and draw into
+  `gl.drawingBufferWidth/Height` rather than `canvas.width/2`. The SDK warns once if it sees the
+  browser clamp a scene canvas. Test a large tile on Chrome with
+  `--webgl_or_caps_max_texture_size_limit_4096` to reproduce the tablet's limit on a desktop.

package/index.d.ts

@@ -125,8 +125,13 @@ export interface FirstWovenResult {
  *   `verticalFov`, offsets the eyes, and skews each frustum so `convergenceDiopters` lands on
  *   the zero-disparity plane.
  *
- * Every field is optional; the runtime **clamps** an out-of-range value (once, with a warning)
- * rather than rejecting the rig. A descriptor applies per-locate, so animating one means sending
+ * Every field is optional; the runtime **clamps** a value outside a field's sanity range (once,
+ * with a warning — e.g. `convergenceDiopters` to `[0, 20]`, `verticalFov` to `[0.01, 3.13]` rad,
+ * `perspectiveFactor` to `[0.1, 10]`, ipd/parallax to `[0, 10000]`) rather than rejecting the rig.
+ * It does **not** enforce comfort: a camera rig's gain and a display rig's factors above 1 are
+ * applied as given. `handle.setViewRig` logs a one-time console warning for the usual mistakes
+ * (a camera rig converged at infinity, a `verticalFov` that looks like degrees, display-rig
+ * factors above 1) and still sends the rig unchanged. A descriptor applies per-locate, so animating one means sending
  * new values each frame — see {@link TileHandle.setViewRig} for the one-frame latency that
  * implies. Build one with `cameraRigFromCamera` / `displayRig` from
  * `@displayxr/inline3d/three`, or by hand.
@@ -140,7 +145,7 @@ export interface XRViewRigInit {
   orientation?: DOMPointInit;
   /** **Display rig.** Metres of virtual display; `m2v = this / the element's physical height`. */
   virtualDisplayHeight?: number;
-  /** Eye separation — display rig: relative `[0,1]`; camera rig: absolute `>= 0`. */
+  /** Eye separation — display rig: relative, 1 = correct, `[0,1]` a comfort dial (above 1 exaggerates); camera rig: absolute `>= 0`. */
   ipdFactor?: number;
   /** Head-tracking response — display rig: `[0,1]`; camera rig: absolute `>= 0`. */
   parallaxFactor?: number;
@@ -204,6 +209,20 @@ export interface DisplayMetrics {
 }
 
 /** What {@link TileHandle.displayMetrics} fills in when the display cannot say. */
+// The depth budget (also `@displayxr/inline3d/depth`): pure measurements, see depth.d.ts.
+export {
+  DEPTH_EYE_SEPARATION_M,
+  DEPTH_DEFAULT_VIEWER_M,
+  disparityPct,
+  cameraRigDisparityPct,
+  depthBudgetFromBounds,
+  comfortZone,
+  comfortDepthFactor,
+  cameraRigComfortFactor,
+  withheldReasonHint,
+} from './depth.js';
+export type { DepthReport, DepthReportBasis, ComfortZoneName, ComfortZoneReport } from './depth.js';
+
 export const DISPLAY_METRICS_DEFAULTS: Readonly<{
   displaySizeM: readonly [number, number];
   displayPixels: readonly [number, number];