@displayxr/inline3d 1.0.0 → 1.1.1

package/js/inline3d.js

@@ -24,6 +24,13 @@
 // { supported:false } and your page shows its normal 2D content — inline-3D is progressive
 // enhancement, never a hard dependency.
 
+// The document's single live manager. The browser's per-frame element-rect report is a
+// WHOLE-WIDGET setter — each live session pushes the complete list of rects to weave — so two
+// managers in one document overwrite each other frame by frame and neither one's tiles hold
+// still. Tracked here only to warn: sequential sessions (a route change that closes one
+// manager and opens the next) are legitimate and the common case, so nothing is refused.
+let liveManager = null;
+
 const hasWebXR = () => typeof navigator !== 'undefined' && !!navigator.xr;
 const hasLayer = () =>
   typeof window !== 'undefined' && typeof window.XRDisplayLayer === 'function';
@@ -34,6 +41,81 @@ const hasLayer = () =>
 // no-op — the page still works, the overlay just weaves like before.
 const hasExclusion = () =>
   hasLayer() && 'excludeElement' in window.XRDisplayLayer.prototype;
+// ── draw-order occlusion (browser Phase 2, browser patches 0063/0064) ─────────────────────
+//
+// The browser composites ANY 2D content over a woven tile per-pixel BY DRAW ORDER — headers,
+// badges, dropdowns, translucent scrims, even a full-tile plate — with nothing declared by the
+// page. Every exclusion mechanism in this file (auto-chrome, page-global overlays,
+// data-inline3d-overlay, handle.exclude) exists only to fake that on browsers without it, so
+// where it is on, all of it stands down.
+//
+// DETECTION IS A CAPABILITY READ, NEVER A VERSION. `excludeElement` is still fully present on a
+// Phase-2 browser (the browser change is viz-side; it touches no Blink file, and the declarations
+// are collected as before and simply have no effect downstream), so `hasExclusion()` cannot tell
+// the generations apart — and a UA/version gate is worthless for a page that pins an SDK for
+// years. The signal is a capability flag the browser exposes; ABSENT today, so this reads false
+// on everything currently shipping and the legacy path below runs unchanged.
+//
+// TWO THINGS THE FLAG'S SHAPE HAS TO RESPECT, both learned the hard way:
+//  1. NEVER read the value off `XRDisplayLayer.prototype`. A Blink IDL attribute getter throws
+//     `TypeError: Illegal invocation` when its receiver is the prototype instead of an instance,
+//     so the "obvious" probe `!!XRDisplayLayer.prototype.occlusionByDrawOrder` would THROW on
+//     precisely the browser it is meant to detect. `'x' in prototype` is safe (no getter call)
+//     but reports only presence.
+//  2. Presence is not the answer. The browser's split is switch-gated
+//     (`--inline-3d-occlusion`, off by default until it becomes the default), so a build that
+//     HAS the attribute can still legitimately report false, and the truth is process-wide
+//     rather than per-layer.
+// Hence the shape asked of the browser: a STATIC readonly boolean on the interface object,
+// `XRDisplayLayer.occlusionByDrawOrder` — process-wide like the switch it reflects, readable
+// with no session and no layer (a page decides its DOM before it ever creates one), and immune
+// to (1) because there is no prototype receiver involved. Should the flag instead land as a
+// per-instance attribute, sampleDrawOrderOcclusion() below picks it up off the first live layer.
+let drawOrderOcclusion = null; // null = not decided yet for this document
+function hasDrawOrderOcclusion() {
+  if (drawOrderOcclusion !== null) return drawOrderOcclusion;
+  if (!hasLayer()) return false;
+  try {
+    const v = window.XRDisplayLayer.occlusionByDrawOrder;
+    if (typeof v === 'boolean') return (drawOrderOcclusion = v); // static flag: authoritative
+  } catch {
+    /* a capability flag that throws is no capability — fall through to the instance path */
+  }
+  return false; // undecided reads as false: the legacy path is the safe default
+}
+
+/**
+ * Per-instance fallback: read the flag off a real layer, once, if that is the shape it landed
+ * in. Presence is probed on the prototype with `in` (safe) and the VALUE is read from the
+ * instance (the only legal receiver). Returns the decided value, or null if the browser exposes
+ * no flag at all — in which case nothing is cached and the legacy path stays on.
+ */
+function sampleDrawOrderOcclusion(layer) {
+  if (drawOrderOcclusion !== null) return drawOrderOcclusion;
+  if (!layer || !hasLayer()) return null;
+  if (!('occlusionByDrawOrder' in window.XRDisplayLayer.prototype)) return null;
+  try {
+    return (drawOrderOcclusion = !!layer.occlusionByDrawOrder);
+  } catch {
+    return null;
+  }
+}
+
+// The "you don't need this any more" notice, at most once per document: the legacy calls stay
+// live API (they must, so one page runs on both generations), so this is not a warning — it is
+// the one line that stops an author debugging an exclusion that is correctly doing nothing.
+let notedAutomaticOcclusion = false;
+function noteAutomaticOcclusion() {
+  if (notedAutomaticOcclusion) return;
+  notedAutomaticOcclusion = true;
+  console.info(
+    '[inline3d] This browser composites 2D over woven 3D automatically, per-pixel by draw ' +
+      'order — overlay exclusion is obsolete here, so exclude()/addGlobalOverlay()/' +
+      'data-inline3d-overlay/autoChrome are accepted and ignored. Your 2D chrome already ' +
+      'occludes the tiles correctly. The calls are harmless (keep them if you also ship to ' +
+      'older DisplayXR Browsers); gate on inline3dOcclusionByDrawOrder() to drop them.'
+  );
+}
 
 /**
  * Cheap, synchronous "can this browser even attempt inline-3D?" gate — true only in the
@@ -49,14 +131,43 @@ export function inline3DAvailable() {
 }
 
 /**
- * True when this browser supports 2D-overlay exclusion (browser#18) — putting a
- * 2D element ON a woven tile (hover plate, badge) so it composites as crisp 2D
- * over the woven 3D instead of being woven. Use it to choose the on-image
- * overlay path when available and a weave-safe fallback (e.g. a caption band
- * below the tile) otherwise. Implies inline3DAvailable(). Sync + cheap.
+ * True when 2D painted ON a woven tile (hover plate, badge, sticky header) composites as
+ * crisp 2D over the woven 3D instead of being woven — by declaration (browser#18 overlay
+ * exclusion) or, on a newer browser, automatically. Use it to choose the on-image overlay
+ * path when available and a weave-safe fallback (e.g. a caption band below the tile)
+ * otherwise. That question has the same answer on both generations, so this stays true on a
+ * draw-order-occlusion browser; ask inline3dOcclusionByDrawOrder() when you need to know
+ * WHICH mechanism you are on. Implies inline3DAvailable(). Sync + cheap.
  */
 export function inline3dOverlaySupported() {
-  return hasExclusion();
+  return hasExclusion() || hasDrawOrderOcclusion();
+}
+
+/**
+ * True when the browser occludes woven tiles with 2D content AUTOMATICALLY — any 2D that
+ * paints over a tile (header, badge, dropdown, translucent scrim) composites per-pixel by
+ * draw order, with nothing declared. When true, this SDK's exclusion machinery is off:
+ * `autoChrome` does not scan, `data-inline3d-overlay` is not watched, and
+ * `exclude()`/`addGlobalOverlay()` are accepted (so one page runs on both generations) but do
+ * nothing — including the `will-change` promotion they used to force on your elements.
+ *
+ * Pages need not branch on this at all: the legacy calls are harmless where it is true, and
+ * still required where it is false. Branch only to skip work of your own — a `data-` attribute
+ * you would otherwise maintain, a full-tile plate the legacy path has to refuse, or a
+ * near-solid background you only keep because a translucent bar used to be risky.
+ *
+ * Sync + cheap. Reads a readonly capability flag on `XRDisplayLayer`, never a version or UA
+ * string; false on every browser that has not exposed the flag, which is the safe answer (the
+ * SDK then runs the legacy exclusion path, which is what such a browser needs).
+ *
+ * One caveat if the flag lands as a per-layer attribute rather than the static one this SDK asks
+ * for: it can only be read once a layer exists, so a call made before the first window activates
+ * answers false and the same call answers true a frame later. Nothing in the SDK depends on the
+ * early answer, but a page that wants to branch its DOM up front should re-check (or just leave
+ * the legacy calls in — they are harmless).
+ */
+export function inline3dOcclusionByDrawOrder() {
+  return hasDrawOrderOcclusion();
 }
 
 /**
@@ -70,10 +181,18 @@ export function inline3dOverlaySupported() {
  * @param {string} [opts.rootMargin='50% 0px']  IntersectionObserver margin for lazy mode;
  *        the default pre-arms a window half a viewport early so a fast scroll never shows a
  *        raw (un-woven) frame.
+ * @param {boolean} [opts.autoChrome=true]  Auto-exclude page chrome: sticky/fixed elements
+ *        near the top of the DOM (headers, toolbars) are registered as page-global overlays
+ *        automatically — the bar itself plus its text/replaced descendants — so woven
+ *        windows scroll UNDER the chrome without any per-app wiring. Opt an element (and
+ *        its subtree) out with `data-inline3d-no-overlay`; set false to manage chrome
+ *        exclusively via addGlobalOverlay()/data-inline3d-overlay. Ignored (nothing is
+ *        scanned, no `will-change` is set on your DOM) on a browser with draw-order
+ *        occlusion, where chrome occludes tiles by itself.
  * @returns {Promise<Inline3D | {supported:false, error?:Error}>}
  */
 export async function createInline3D(opts = {}) {
-  const { referenceSpace = 'viewer', lazy = true, rootMargin = '50% 0px' } = opts;
+  const { referenceSpace = 'viewer', lazy = true, rootMargin = '50% 0px', autoChrome = true } = opts;
   if (!inline3DAvailable()) return { supported: false };
   let session;
   try {
@@ -89,7 +208,7 @@ export async function createInline3D(opts = {}) {
   } catch {
     /* rAF still fires without a ref space; views are just null (fine for image/video). */
   }
-  return new Inline3D(session, refSpace, { lazy, rootMargin });
+  return new Inline3D(session, refSpace, { lazy, rootMargin, autoChrome });
 }
 
 /**
@@ -110,8 +229,38 @@ export async function startInline3D(
   return { supported: true, wall, session: wall.session, close: () => wall.close() };
 }
 
+// Mutual rect-overlap fraction at which an overlay becomes indistinguishable from the canvas
+// it sits on — the same >=70% the browser's own layer matcher uses. See _isFullTileOverlay.
+const FULL_TILE_OVERLAP = 0.7;
+
+/**
+ * Elements inside `root` worth their own overlay plate: anything with a direct
+ * non-whitespace text node, plus replaced/painted elements (img, svg, video,
+ * canvas, form controls). See _scanChrome for why chrome text is plated
+ * per-element instead of relying on the bar's own raster (browser#83).
+ */
+const CHROME_REPLACED = new Set(['IMG', 'SVG', 'VIDEO', 'CANVAS', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA']);
+function chromeTextPlates(root) {
+  const plates = [];
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
+  for (let el = walker.nextNode(); el; el = walker.nextNode()) {
+    if (el.closest('[data-inline3d-no-overlay]')) continue;
+    if (CHROME_REPLACED.has(el.tagName.toUpperCase())) {
+      plates.push(el);
+      continue;
+    }
+    for (const child of el.childNodes) {
+      if (child.nodeType === Node.TEXT_NODE && child.nodeValue.trim()) {
+        plates.push(el);
+        break;
+      }
+    }
+  }
+  return plates;
+}
+
 class Inline3D {
-  constructor(session, refSpace, { lazy, rootMargin }) {
+  constructor(session, refSpace, { lazy, rootMargin, autoChrome = true }) {
     this.supported = true;
     this.session = session;
     this.refSpace = refSpace;
@@ -125,14 +274,46 @@ class Inline3D {
     // input and gets woven). Page-global overlays span many windows, so they are
     // exactly the case that breaks.
     this._isolatedBy = new WeakMap();
+    // Auto-chrome (sticky/fixed page furniture found by _scanChrome). Tracked apart
+    // from _globalOverlays so pruning disconnected chrome never touches overlays the
+    // app registered itself.
+    this._autoChrome = autoChrome;
+    this._autoChromeEls = new Set();
+    this._lastChromeScan = 0;
+    // Elements already reported as full-tile overlays, so the refusal is logged once per
+    // element instead of on every re-activate / overlay-scan sync.
+    this._fullTileWarned = new WeakSet();
+    // Set once the legacy occlusion machinery has been retired (draw-order browser whose
+    // capability flag could only be read from a live layer). See _standDownLegacyOcclusion.
+    this._stoodDown = false;
     this._running = true;
     this._lazy = lazy;
     this._observer =
       lazy && typeof IntersectionObserver === 'function'
         ? new IntersectionObserver((entries) => this._onIntersect(entries), { rootMargin })
         : null;
+    // Frame-loop bookkeeping: one loop, identified, so a restart can retire a stalled
+    // predecessor instead of running two (see _requestFrame / _watchForStalledFrames).
+    this._loopId = 0;
+    this._framePending = false;
+    this._frameCount = 0;
+    this._frameWatchdog = null;
+    this._suspended = null;
+    if (liveManager && liveManager._running && liveManager !== this) {
+      console.warn(
+        '[inline3d] A second inline-3D session is live in this document. The browser\'s ' +
+          'element-rect channel is a whole-widget setter, so both managers clobber each ' +
+          "other's rect list every frame — tiles may flicker, ghost, or weave at a stale " +
+          'rect. Use ONE createInline3D() per document and add every window to it; if you ' +
+          'are switching views, close() the previous manager first.'
+      );
+    }
+    liveManager = this;
     session.addEventListener('end', () => this._teardown());
-    session.requestAnimationFrame((t, f) => this._frame(t, f));
+    this._scanChrome(); // page chrome usually exists before the session does
+    this._bindLifecycle();
+    this._armDprWatch();
+    this._requestFrame();
   }
 
   /** Number of windows whose weave layer is currently live (on-screen in lazy mode). */
@@ -153,9 +334,18 @@ class Inline3D {
    * but the per-tile present can still seam page-global chrome that spans tile gaps during
    * scroll — the systematic fix is the DP-composited whole-window present (browser#22).
    * No-op on browsers without excludeElement (progressive enhancement).
+   *
+   * @deprecated on a browser with draw-order occlusion (inline3dOcclusionByDrawOrder()):
+   * page chrome occludes every tile there with nothing registered. The call is accepted and
+   * stored, does nothing, and stays required on older browsers — so keep it unless your page
+   * targets Phase-2 browsers only.
    */
   addGlobalOverlay(el) {
     if (!el || this._globalOverlays.has(el)) return;
+    // Store it even where occlusion is automatic: the registration is API, a page may read
+    // nothing back but must be able to run unchanged on both browser generations. The
+    // exclusion below is a no-op there (see _applyExclusion).
+    if (hasDrawOrderOcclusion()) noteAutomaticOcclusion();
     this._globalOverlays.add(el);
     for (const win of this._windows.values()) if (win.layer) this._applyExclusion(win, el);
   }
@@ -166,6 +356,85 @@ class Inline3D {
     for (const win of this._windows.values()) if (win.layer) this._dropExclusion(win, el);
   }
 
+  /**
+   * Auto-chrome scan: find sticky/fixed page furniture and register it as page-global
+   * overlays, no app wiring required. Runs at session start and again on every layer
+   * activation (throttled) so late-mounted chrome is picked up as tiles churn.
+   *
+   * Two deliberate choices:
+   *  - SHALLOW scan (top 3 DOM levels under <body>): page chrome lives there; a deep
+   *    sticky element (a table header inside a scroller) is content, not chrome.
+   *  - Besides the chrome element itself, its TEXT / replaced descendants are registered
+   *    individually (browser#83): the browser re-composites an excluded element by
+   *    geometrically matching its rect to a composited-layer quad (>=70% area overlap),
+   *    and a full-width bar can raster as several cc tile quads — each a fraction of the
+   *    bar's rect, so none match and the bar never stages. A near-solid bar hides that
+   *    failure everywhere except its text (a uniform color weaves to itself). The small
+   *    per-text plates each promote to their own layer and match ~1:1, closing the
+   *    visible failure regardless of how the bar rasters.
+   *
+   * Opt-out: `data-inline3d-no-overlay` on an element skips it and its whole subtree.
+   * Elements containing a woven window are never plated (that would hand the weave
+   * input back to the compositor as crisp 2D).
+   */
+  _scanChrome() {
+    // Draw-order occlusion makes this whole scan pointless work: the chrome already occludes
+    // every tile per-pixel. Bail BEFORE the DOM walk, so a Phase-2 page pays neither the
+    // querySelectorAll + getComputedStyle sweep (once a second, at every layer activation)
+    // nor the `will-change` promotions it would hand out across the page's furniture.
+    if (hasDrawOrderOcclusion()) return;
+    if (!this._autoChrome || !hasExclusion() || typeof document === 'undefined') return;
+    const now = Date.now();
+    if (now - this._lastChromeScan < 1000) return; // activations burst during scroll
+    this._lastChromeScan = now;
+    const body = document.body;
+    if (!body) return;
+    const found = new Set();
+    const candidates = body.querySelectorAll(':scope > *, :scope > * > *, :scope > * > * > *');
+    for (const el of candidates) {
+      if (el.closest('[data-inline3d-no-overlay]')) continue;
+      const pos = getComputedStyle(el).position;
+      if (pos !== 'fixed' && pos !== 'sticky') continue;
+      let containsWindow = false;
+      for (const canvas of this._windows.keys()) {
+        if (el === canvas || el.contains(canvas)) {
+          containsWindow = true;
+          break;
+        }
+      }
+      if (containsWindow) continue;
+      found.add(el);
+      for (const plate of chromeTextPlates(el)) found.add(plate);
+    }
+    // Prune auto-registrations that (a) left the document, or (b) NOW contain a woven
+    // window (windows register after the constructor's first scan — leaving such a
+    // wrapper plated would hand the tile back to the compositor as crisp 2D). Connected,
+    // window-free elements are left alone even when no longer detected: a still-connected
+    // element may also have been registered by the app, and _globalOverlays is one set —
+    // never yank something the app might be counting on.
+    for (const el of this._autoChromeEls) {
+      let containsWindow = false;
+      if (el.isConnected) {
+        for (const canvas of this._windows.keys()) {
+          if (el === canvas || el.contains(canvas)) {
+            containsWindow = true;
+            break;
+          }
+        }
+      }
+      if (!el.isConnected || containsWindow) {
+        this._autoChromeEls.delete(el);
+        this.removeGlobalOverlay(el);
+      }
+    }
+    for (const el of found) {
+      if (!this._globalOverlays.has(el)) {
+        this._autoChromeEls.add(el);
+        this.addGlobalOverlay(el);
+      }
+    }
+  }
+
   /**
    * Weave a still side-by-side 3D image into `canvas`.
    * @param {HTMLCanvasElement} canvas  a 2D canvas; the SDK owns its backing buffer.
@@ -240,12 +509,18 @@ class Inline3D {
    * like before — progressive enhancement, like the rest of this SDK). Prefer the
    * declarative `data-inline3d-overlay` attribute (see _startOverlayScan) unless you need
    * to exclude an element outside the window's container.
+   *
+   * On a browser with draw-order occlusion the overlay is already composited over the woven
+   * 3D per-pixel, so exclude()/unexclude() are stored-and-ignored (see _applyExclusion).
    */
   _handle(canvas, win) {
     return {
       remove: () => this._remove(canvas),
       exclude: (el) => {
         if (!el) return;
+        // Stored, not honoured, where occlusion is automatic — same reason as
+        // addGlobalOverlay: one page, both browser generations.
+        if (hasDrawOrderOcclusion()) noteAutomaticOcclusion();
         win.excluded.add(el);
         this._applyExclusion(win, el);
       },
@@ -253,6 +528,9 @@ class Inline3D {
         if (!el || !win.excluded.delete(el)) return;
         this._dropExclusion(win, el);
       },
+      // Read-only counters, for pages that want to see the load-induced mono fallback rather
+      // than wait for a bug report about "blinking". Scene windows only; 0/0 elsewhere.
+      stats: () => ({ frames: win.frames, monoFrames: win.monoFrames }),
     };
   }
 
@@ -296,6 +574,13 @@ class Inline3D {
       excluded: new Set(),
       autoExcluded: new Set(),
       overlayObserver: null,
+      // Box/dpr watch, live only while the window is (see _startSizeWatch).
+      sizeObserver: null,
+      resizePending: false,
+      // Scene diagnostics (web#12), read back through the handle's stats(). frames counts
+      // onFrame deliveries; monoFrames counts the ones that carried fewer than two views.
+      frames: 0,
+      monoFrames: 0,
     };
     this._windows.set(canvas, win);
     if (this._lazy && this._observer) {
@@ -332,6 +617,9 @@ class Inline3D {
 
   _activate(win) {
     if (win.layer) return;
+    // Pick up page chrome (incl. late-mounted) before the exclusion loop below —
+    // layers churn with scroll, so activations double as cheap rescan points.
+    this._scanChrome();
     try {
       // virtualDisplayHeight (display-rig m2v) tells the runtime what scale this
       // window's scene is authored at, so it returns render-ready scaled views.
@@ -342,6 +630,10 @@ class Inline3D {
       win.layer = null;
       return;
     }
+    // First real layer: if the occlusion capability is per-instance, this is the earliest point
+    // it can be read (see sampleDrawOrderOcclusion) — and if it says the browser occludes by
+    // draw order, retire whatever legacy machinery already started before we could know.
+    if (sampleDrawOrderOcclusion(win.layer) === true) this._standDownLegacyOcclusion();
     // Re-apply overlay exclusions (browser#18): the browser's layer-side set died with
     // the previous layer (lazy close), so a re-activated window must re-declare its own
     // explicit exclusions, the page-global overlays, and the attribute-scanned overlays,
@@ -353,10 +645,12 @@ class Inline3D {
       this._sizeBuffer(win, /*sbs*/ true);
       this._paint(win, null); // first SBS paint (video will refresh each frame)
     }
+    this._startSizeWatch(win);
   }
 
   _deactivate(win) {
     this._stopOverlayScan(win);
+    this._stopSizeWatch(win);
     if (win.layer) {
       try {
         win.layer.close();
@@ -374,8 +668,60 @@ class Inline3D {
 
   // ── overlay exclusion (browser#18) ─────────────────────────────────────────────────
 
+  /**
+   * Refuse a FULL-TILE overlay — an element whose rect is (near-)congruent with its own
+   * window's canvas.
+   *
+   * The browser re-composites an excluded element by geometrically matching its rect to a
+   * composited-layer quad (>=70% area overlap, see _scanChrome). A plate that covers the whole
+   * tile matches the tile's OWN canvas quad, so the CANVAS gets staged as the overlay: it
+   * leaves the weave input entirely and the tile presents its raw side-by-side buffer —
+   * squished halves, no 3D. That is a destroyed tile, not a degraded one, so skip the
+   * exclusion and say why instead of honouring it.
+   *
+   * The test is MUTUAL (>=70% of both rects) so page-global chrome stays legal: a sticky
+   * header may cover a small tile completely, but the tile is a small fraction of the header,
+   * so the header never looks congruent with any one canvas.
+   *
+   * Limit: it judges the rect it can measure now. A plate that is display:none at
+   * registration measures empty (and excluding it is harmless while hidden), so a plate that
+   * only becomes full-tile once shown slips through — the authoring rule stands on its own
+   * (docs/authoring-inline-3d.md § 2D overlays ON a 3D window).
+   */
+  _isFullTileOverlay(win, el) {
+    if (!el || typeof el.getBoundingClientRect !== 'function') return false;
+    const e = el.getBoundingClientRect();
+    const c = win.canvas.getBoundingClientRect();
+    const eArea = e.width * e.height;
+    const cArea = c.width * c.height;
+    if (eArea <= 0 || cArea <= 0) return false; // hidden / detached — nothing to judge
+    const iw = Math.min(e.right, c.right) - Math.max(e.left, c.left);
+    const ih = Math.min(e.bottom, c.bottom) - Math.max(e.top, c.top);
+    if (iw <= 0 || ih <= 0) return false;
+    const inter = iw * ih;
+    if (inter / eArea < FULL_TILE_OVERLAP || inter / cArea < FULL_TILE_OVERLAP) return false;
+    if (!this._fullTileWarned.has(el)) {
+      this._fullTileWarned.add(el);
+      console.warn(
+        '[inline3d] Refusing a full-tile overlay: this element covers its own woven canvas, ' +
+          "and the browser's geometric matcher cannot tell the two apart — it would stage " +
+          'the CANVAS as the overlay and the tile would show its raw side-by-side buffer ' +
+          'instead of 3D. Make the overlay a PARTIAL region of the tile (a caption band, a ' +
+          'badge, a corner plate), or move it outside the tile and register it with ' +
+          'addGlobalOverlay().',
+        el
+      );
+    }
+    return true;
+  }
+
   _applyExclusion(win, el) {
+    // Automatic occlusion: nothing to declare, and nothing to promote. Returning here (before
+    // the full-tile guard) is also why a full-tile plate is legal on such a browser — there is
+    // no geometric matcher to confuse, so there is no refusal and no warning.
+    if (hasDrawOrderOcclusion()) return;
     if (!win.layer || !hasExclusion()) return;
+    if (this._isFullTileOverlay(win, el)) return;
     // Force the overlay onto its OWN composited layer so the browser can grab it
     // as an isolated resource (the element rastered on transparency) and
     // composite it OVER the woven 3D — final = plate + (1−plate.a)·woven, true
@@ -405,14 +751,13 @@ class Inline3D {
   }
 
   _dropExclusion(win, el) {
+    // Nothing was ever excluded or promoted, so there is nothing to undo — and in particular
+    // this must not touch the element's `will-change`, which is the page's own here.
+    if (hasDrawOrderOcclusion()) return;
     const refs = this._isolatedBy.get(el);
     if (refs) refs.delete(win);
     // Only un-promote once NO window needs this element isolated any more.
-    if ((!refs || refs.size === 0) && el.dataset.inline3dIsolated) {
-      el.style.willChange = el.dataset.inline3dPriorWillChange || '';
-      delete el.dataset.inline3dPriorWillChange;
-      delete el.dataset.inline3dIsolated;
-    }
+    if (!refs || refs.size === 0) this._unpromote(el);
     if (!win.layer || !hasExclusion()) return;
     try {
       win.layer.unexcludeElement(el);
@@ -421,6 +766,53 @@ class Inline3D {
     }
   }
 
+  /**
+   * Undo the SDK's own compositing promotion on `el`, restoring the `will-change` the page had
+   * (which may be none). Only ever touches an element the SDK promoted — the marker dataset
+   * flag is what says so. Returns whether there was anything to undo.
+   */
+  _unpromote(el) {
+    if (!el || !el.dataset || !el.dataset.inline3dIsolated) return false;
+    el.style.willChange = el.dataset.inline3dPriorWillChange || '';
+    delete el.dataset.inline3dPriorWillChange;
+    delete el.dataset.inline3dIsolated;
+    return true;
+  }
+
+  /**
+   * Retire the legacy occlusion machinery, once, on learning the browser occludes by draw order.
+   *
+   * Only reachable when the capability could not be read until the first layer existed (the
+   * per-instance flag shape): by then one auto-chrome scan may have run and promoted page
+   * furniture. Where the flag is readable up front — the shape this SDK asks for — nothing has
+   * started and this finds nothing to do.
+   *
+   * Registrations the APP made are kept as API state (its `removeGlobalOverlay(el)` must still
+   * find `el` registered); only the SDK's own side effects on the page's DOM are reversed. The
+   * auto-chrome set is dropped entirely: it was never the app's, and nothing will re-add it.
+   */
+  _standDownLegacyOcclusion() {
+    if (this._stoodDown) return;
+    this._stoodDown = true;
+    let retired = false;
+    for (const win of this._windows.values()) {
+      if (win.overlayObserver) {
+        this._stopOverlayScan(win);
+        retired = true;
+      }
+      for (const el of win.excluded) if (this._unpromote(el)) retired = true;
+    }
+    for (const el of this._autoChromeEls) {
+      this._globalOverlays.delete(el);
+      this._unpromote(el);
+      retired = true;
+    }
+    this._autoChromeEls.clear();
+    for (const el of this._globalOverlays) if (this._unpromote(el)) retired = true;
+    this._isolatedBy = new WeakMap(); // every promotion is gone; the refcounts with them
+    if (retired) noteAutomaticOcclusion(); // only worth saying if work was actually thrown away
+  }
+
   // Declarative overlays: any element marked `data-inline3d-overlay` inside the window's
   // container (the canvas's parent — where an over-the-window plate must live to be
   // positioned over it) is auto-excluded while the window is live, and tracked through
@@ -430,6 +822,10 @@ class Inline3D {
   // with display, not opacity/visibility: those still report a full rect, so the weave
   // hole would stay punched under an invisible plate.)
   _startOverlayScan(win) {
+    // No observer at all where occlusion is automatic: `data-inline3d-overlay` needs no
+    // honouring, so a page keeps its attributes (harmless, portable) and pays no
+    // MutationObserver per live tile.
+    if (hasDrawOrderOcclusion()) return;
     if (!hasExclusion() || typeof MutationObserver !== 'function') return;
     const container = win.canvas.parentElement;
     if (!container) return;
@@ -468,10 +864,17 @@ class Inline3D {
     win.autoExcluded.clear();
   }
 
-  _sizeBuffer(win, sbs) {
+  /** The per-eye buffer size this window should have right now (explicit, or box × dpr). */
+  _eyeSize(win) {
     const dpr = Math.min(window.devicePixelRatio || 1, 2);
-    const boxW = win.reqW || Math.round((win.canvas.clientWidth || 256) * dpr);
-    const boxH = win.reqH || Math.round((win.canvas.clientHeight || 256) * dpr);
+    return {
+      w: win.reqW || Math.round((win.canvas.clientWidth || 256) * dpr),
+      h: win.reqH || Math.round((win.canvas.clientHeight || 256) * dpr),
+    };
+  }
+
+  _sizeBuffer(win, sbs) {
+    const { w: boxW, h: boxH } = this._eyeSize(win);
     win.eyeW = boxW;
     win.eyeH = boxH;
     win.canvas.width = sbs ? boxW * 2 : boxW; // SBS = two eye tiles wide
@@ -479,6 +882,92 @@ class Inline3D {
     win.sbs = sbs;
   }
 
+  // ── box / devicePixelRatio changes ──────────────────────────────────────────────────
+  //
+  // _sizeBuffer runs at activate and deactivate ONLY, so a live window whose CSS box or
+  // devicePixelRatio changes underneath it keeps its old backing store: the same SBS pixels
+  // are stretched onto a differently-shaped box and the two eyes come out mis-squeezed, with
+  // no error, until the tile happens to re-activate. A responsive reflow, a flex sibling
+  // appearing, a browser zoom or a drag to a different-scale monitor all do it. So: watch the
+  // box while the window is live, and re-derive the buffer when it actually moves.
+
+  _startSizeWatch(win) {
+    if (typeof ResizeObserver !== 'function') return;
+    if (win.sizeObserver) return;
+    // Scene canvases are the app's (ownsBuffer false) — never touch their width/height.
+    // An explicit {width, height} is box-independent by definition, so nothing to watch.
+    if (!win.ownsBuffer || (win.reqW && win.reqH)) return;
+    win.sizeObserver = new ResizeObserver(() => this._onBoxChange(win));
+    win.sizeObserver.observe(win.canvas);
+  }
+
+  _stopSizeWatch(win) {
+    if (win.sizeObserver) {
+      win.sizeObserver.disconnect();
+      win.sizeObserver = null;
+    }
+    win.resizePending = false;
+  }
+
+  /**
+   * Re-derive one live window's SBS buffer and repaint it. Debounced to one animation frame:
+   * ResizeObserver and a dpr flip both fire in bursts during a drag-resize or a zoom, and
+   * every resize reallocates the backing store and clears it.
+   */
+  _onBoxChange(win) {
+    if (!win.layer || !win.ownsBuffer || win.resizePending) return;
+    win.resizePending = true;
+    const run = () => {
+      if (!win.resizePending) return;
+      win.resizePending = false;
+      if (!win.layer || !win.ownsBuffer) return;
+      const { w, h } = this._eyeSize(win);
+      if (w === win.eyeW && h === win.eyeH) return; // observer fired, geometry didn't move
+      this._sizeBuffer(win, /*sbs*/ true);
+      this._paint(win, null); // repaint NOW: setting canvas.width cleared the buffer
+    };
+    if (typeof requestAnimationFrame === 'function') requestAnimationFrame(run);
+    else run();
+  }
+
+  /**
+   * devicePixelRatio is invisible to ResizeObserver — a browser zoom or a move to a
+   * different-scale monitor leaves the CSS box the same number of CSS px while the buffer
+   * that box deserves changes. A `(resolution: Ndppx)` query flips exactly when dpr leaves
+   * its current value, so arm one, and re-arm it on the new value each time.
+   */
+  _armDprWatch() {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return;
+    this._disarmDprWatch();
+    let q;
+    try {
+      q = window.matchMedia(`(resolution: ${window.devicePixelRatio || 1}dppx)`);
+    } catch {
+      return; // no resolution-query support: box changes are still covered
+    }
+    const onChange = () => {
+      if (!this._running) return;
+      this._armDprWatch(); // this query is stale the moment it fires
+      for (const win of this._windows.values()) if (win.layer) this._onBoxChange(win);
+    };
+    try {
+      q.addEventListener('change', onChange);
+    } catch {
+      return;
+    }
+    this._dprWatch = { q, onChange };
+  }
+
+  _disarmDprWatch() {
+    if (!this._dprWatch) return;
+    try {
+      this._dprWatch.q.removeEventListener('change', this._dprWatch.onChange);
+    } catch {
+      /* ignore */
+    }
+    this._dprWatch = null;
+  }
+
   _paint(win, _views) {
     if (win.kind === 'scene' || !win.ctx) return;
     const src = win.kind === 'video' ? win.video : win.img;
@@ -507,15 +996,63 @@ class Inline3D {
     }
   }
 
+  /**
+   * Arm the next session frame. `force` starts a NEW loop even though one is nominally
+   * pending: each loop carries an id and only the current id re-arms, so a stalled
+   * predecessor (a bfcache restore whose callback never fired) is retired rather than
+   * doubled if it ever does fire.
+   */
+  _requestFrame(force) {
+    if (!this._running) return;
+    if (this._framePending && !force) return;
+    const id = force ? ++this._loopId : this._loopId;
+    this._framePending = true;
+    try {
+      this.session.requestAnimationFrame((t, f) => {
+        if (id !== this._loopId) return; // superseded loop — let it die here
+        this._framePending = false;
+        this._frameCount++;
+        this._frame(t, f);
+      });
+    } catch {
+      this._framePending = false; // session going away; 'end' → _teardown handles it
+    }
+  }
+
   _frame(t, f) {
     if (!this._running) return;
-    this.session.requestAnimationFrame((t2, f2) => this._frame(t2, f2));
+    this._requestFrame();
     const pose = this.refSpace ? f.getViewerPose(this.refSpace) : null;
     const views = pose ? pose.views : null;
     for (const win of this._windows.values()) {
       if (!win.layer) continue;
       if (win.kind === 'scene') {
-        if (views && win.onFrame) win.onFrame(views, win.layer, f);
+        if (views && win.onFrame) {
+          // Count the SHORT view lists and hand them over unchanged. Under GPU load the session
+          // can report a single view (a per-frame mono fallback) where it normally reports two,
+          // and a renderer that clears before it validates turns that into a dark tile
+          // (web#12 — ./viewer now validates first and replays its last good frame instead).
+          //
+          // The core deliberately does NOT filter or synthesise: the contract is "here is what
+          // the frame reported", and a window that can do something sensible with one view
+          // (a mono preview, say) must be allowed to. What the core owes you is VISIBILITY —
+          // this is otherwise invisible from the page, since nothing throws and nothing logs.
+          win.frames++;
+          if (views.length < 2) {
+            win.monoFrames++;
+            // 1-in-300 so a sustained rate is reported without the log itself becoming the load;
+            // `% 300 === 1` also names the FIRST one immediately.
+            if (win.monoFrames % 300 === 1 && typeof console !== 'undefined' && console.debug) {
+              const pct = ((100 * win.monoFrames) / Math.max(1, win.frames)).toFixed(1);
+              console.debug(
+                `[inline3d] scene window: ${win.monoFrames} non-stereo view lists in ` +
+                  `${win.frames} frames (${pct}%). The viewer replays its last good stereo ` +
+                  'frame for these; a rising rate means the session is falling back under load.',
+              );
+            }
+          }
+          win.onFrame(views, win.layer, f);
+        }
       } else {
         // Repaint image AND video every frame. The weave reads each window's
         // composited canvas quad per frame; a canvas that isn't redrawn can have
@@ -527,12 +1064,116 @@ class Inline3D {
     }
   }
 
+  // ── page lifecycle: bfcache, freeze, restore (browser#87) ───────────────────────────
+  //
+  // A weaved window's rect reaches the compositor from the session's own rAF: every frame the
+  // live session pushes the full list of rects to weave, and the ONLY way to clear a rect is
+  // to push a list without it. So a page that simply stops running frames leaves its last
+  // list standing — the rects keep weaving over whatever is on screen now. Back/forward
+  // navigation does exactly that: bfcache freezes the page mid-loop, the woven tiles stay
+  // pinned where they were, and the next page inherits ghost 3D windows (browser#87).
+  //
+  // The fix is to make the LAST frames before suspension report an empty list: deactivate
+  // every live window while frames still run, remember which ones were live, and restore them
+  // on the way back. pagehide covers bfcache entry and unload; freeze covers a discarded
+  // background tab where pagehide does not fire.
+
+  _bindLifecycle() {
+    if (typeof window === 'undefined') return;
+    this._onPageHide = () => this._suspend();
+    this._onPageShow = (e) => this._resume(!!(e && e.persisted));
+    window.addEventListener('pagehide', this._onPageHide);
+    window.addEventListener('pageshow', this._onPageShow);
+    // Page Lifecycle API (Blink): a frozen tab never gets pagehide/pageshow.
+    if (typeof document !== 'undefined' && 'onfreeze' in document) {
+      this._onFreeze = () => this._suspend();
+      this._onResume = () => this._resume(true);
+      document.addEventListener('freeze', this._onFreeze);
+      document.addEventListener('resume', this._onResume);
+    }
+  }
+
+  _unbindLifecycle() {
+    if (typeof window === 'undefined') return;
+    if (this._onPageHide) window.removeEventListener('pagehide', this._onPageHide);
+    if (this._onPageShow) window.removeEventListener('pageshow', this._onPageShow);
+    if (this._onFreeze && typeof document !== 'undefined') {
+      document.removeEventListener('freeze', this._onFreeze);
+      document.removeEventListener('resume', this._onResume);
+    }
+    this._onPageHide = this._onPageShow = this._onFreeze = this._onResume = null;
+    if (this._frameWatchdog) {
+      clearTimeout(this._frameWatchdog);
+      this._frameWatchdog = null;
+    }
+  }
+
+  /** Close every live layer so the outgoing frames report an empty rect list. */
+  _suspend() {
+    if (!this._running || this._suspended) return;
+    const was = [];
+    for (const win of this._windows.values()) {
+      if (win.layer) {
+        was.push(win);
+        this._deactivate(win);
+      }
+    }
+    this._suspended = was;
+  }
+
+  /**
+   * Coming back: re-arm the windows that were live. In lazy mode the IntersectionObserver
+   * owns that decision, and re-observing re-delivers the CURRENT intersection state — so a
+   * tile the user scrolled away from before leaving stays dark, and only what is actually on
+   * screen re-weaves. Chrome is rescanned because a restored page may have remounted it.
+   */
+  _resume(persisted) {
+    if (!this._running) return;
+    const was = this._suspended;
+    this._suspended = null;
+    if (was) {
+      for (const win of was) {
+        if (!this._windows.has(win.canvas)) continue; // removed while we were away
+        if (this._lazy && this._observer) {
+          this._observer.unobserve(win.observeEl);
+          this._observer.observe(win.observeEl);
+        } else {
+          this._activate(win);
+        }
+      }
+    }
+    this._lastChromeScan = 0; // the 1 s throttle must not swallow the restore rescan
+    this._scanChrome();
+    this._armDprWatch(); // the restore may be on a different-scale display
+    if (persisted) this._watchForStalledFrames();
+  }
+
+  /**
+   * A bfcache restore can hand back a session whose pending animation frame never arrives —
+   * the loop was suspended between request and callback, and nothing re-issues it. The
+   * manager then looks alive (`_running`) while no window ever paints again. Give it a second
+   * to prove otherwise, then start a fresh loop (which retires the stalled one by id).
+   */
+  _watchForStalledFrames() {
+    if (this._frameWatchdog || typeof setTimeout !== 'function') return;
+    const before = this._frameCount;
+    this._frameWatchdog = setTimeout(() => {
+      this._frameWatchdog = null;
+      if (!this._running || this._frameCount !== before) return; // frames arrived
+      this._requestFrame(/*force*/ true);
+    }, 1000);
+  }
+
   _teardown() {
     if (!this._running) return;
     this._running = false;
+    if (liveManager === this) liveManager = null;
+    this._unbindLifecycle();
+    this._disarmDprWatch();
     if (this._observer) this._observer.disconnect();
     for (const win of this._windows.values()) {
       this._stopOverlayScan(win);
+      this._stopSizeWatch(win);
       if (win.layer) {
         try {
           win.layer.close();