@displayxr/inline3d 1.43.1 → 1.44.0

package/js/camera/pair-cursor.js

@@ -15,7 +15,11 @@
 //    disparity is past the draw threshold (-0.005 baselines, and >= 0.5 px; cursorShouldDraw), the
 //    OS cursor hidden exactly then;
 //  - the same filter (fast rise, slow sink) and the same arrow (CURSOR_ARROW, tip = hotspot, the
-//    OS arrow's 19 CSS px).
+//    OS arrow's 19 CSS px);
+//  - the same crosstalk softening (Amendment 2 §B.7, cursorSoften): a lifted arrow is blurred by
+//    0.1 × its ghost offset (here: its disparity, the two halves being the two views) and faded
+//    toward 0.5, both zero on the glass. Rasterised into the buffer from the core's 13-tap kernel
+//    (cursorSoftArrowRaster) — inside the woven pixels, never a CSS filter or CSS opacity.
 // What is specific to a pair: it has no 3D views, so it works in tile PIXEL disparity — OUTPUT
 // pixels of one eye of the woven buffer, + = crossed (in front of the glass), the sign the rest of
 // camera/ uses — and converts to the core's eye-baseline units through the panel's pixel pitch:
@@ -30,7 +34,10 @@ import {
   cursorDefaultHeight,
   cursorFilterStep,
   cursorShouldDraw,
+  cursorSoften,
+  cursorSoftArrowRaster,
   cursorTarget,
+  resolveCursorSoften,
   CURSOR_ARROW,
   CURSOR_ARROW_CSS_PX,
   CURSOR_DEFAULT_TUNING,
@@ -251,6 +258,53 @@ export function drawPairArrow(g, outW, outH, u, v, disparityPx, sizePx) {
   }
 }
 
+// A scratch 2D canvas for the softened arrow (drawImage blends and honours the clip; putImageData
+// would do neither). Null where no canvas can be made — then the crisp arrow is drawn.
+let _scratch = null;
+function scratchCanvas(w, h) {
+  if (!_scratch || (typeof OffscreenCanvas === 'function' && !(_scratch instanceof OffscreenCanvas))) {
+    try {
+      if (typeof OffscreenCanvas === 'function') _scratch = new OffscreenCanvas(1, 1);
+      else if (globalThis.document && document.createElement) _scratch = document.createElement('canvas');
+    } catch {
+      _scratch = null;
+    }
+  }
+  if (!_scratch || typeof _scratch.getContext !== 'function') return null;
+  if (_scratch.width < w) _scratch.width = w;
+  if (_scratch.height < h) _scratch.height = h;
+  return _scratch.getContext('2d');
+}
+
+/**
+ * The SOFTENED arrow into both halves (ADR-046 Amendment 2 §B.7): as drawPairArrow — same
+ * placement, same tip, same clip to each half — but rasterised from the core's 13-tap blur of the
+ * arrow with `radius` (arrow heights) and `alpha` (opacity). Returns false (nothing drawn) when no
+ * scratch canvas is available, so the caller can fall back to the crisp arrow.
+ */
+export function drawPairArrowSoft(g, outW, outH, u, v, disparityPx, sizePx, radius, alpha) {
+  const cy = v * outH;
+  const fill = arrowFill(sizePx);
+  const polys = [CURSOR_ARROW, fill];
+  const rasters = [0, 1].map((eye) => {
+    const cx = eye * outW + u * outW + (eye === 0 ? disparityPx / 2 : -disparityPx / 2);
+    return cursorSoftArrowRaster(cx, cy, sizePx, radius, alpha, [1, 1, 1, 1], [0, 0, 0, 1], polys);
+  });
+  const sg = scratchCanvas(Math.max(rasters[0].width, rasters[1].width), Math.max(rasters[0].height, rasters[1].height));
+  if (!sg || typeof sg.putImageData !== 'function' || typeof ImageData !== 'function') return false;
+  for (const eye of [0, 1]) {
+    const r = rasters[eye];
+    sg.putImageData(new ImageData(r.data, r.width, r.height), 0, 0);
+    g.save();
+    g.beginPath();
+    g.rect(eye * outW, 0, outW, outH);
+    g.clip();
+    g.drawImage(sg.canvas, 0, 0, r.width, r.height, r.x0, r.y0, r.width, r.height);
+    g.restore();
+  }
+  return true;
+}
+
 /**
  * One cursor over one woven pair. The owner calls `draw()` after painting the pair each frame
  * (`idle()` on any frame it does not paint a woven pair), and hands it the latest grayscale copy
@@ -258,8 +312,10 @@ export function drawPairArrow(g, outW, outH, u, v, disparityPx, sizePx) {
  */
 export class PairCursor {
   /** @param {HTMLElement} canvas  the tile — the pointer counts over its box */
-  constructor(canvas, { height, pointerScope = 'window' } = {}) {
+  constructor(canvas, { height, pointerScope = 'window', soften } = {}) {
     this.pointer = new CursorPointer(canvas, { scope: pointerScope });
+    /** Crosstalk softening parameters (resolveCursorSoften). */
+    this.soften = resolveCursorSoften(soften, '@displayxr/inline3d pair cursor');
     // A fraction of the tile height when given; by default the OS arrow's size (CSS px → tile).
     this.height = height > 0 ? height : null;
     this.filter = {};
@@ -271,7 +327,7 @@ export class PairCursor {
     this.metersPerCssPx = null;
     /** The eye separation (metres) the baseline units convert with: displayMetrics' (a default today). */
     this.eyeSeparationM = DISPLAY_METRICS_DEFAULTS.eyeSeparationM;
-    /** The last frame's placement, for diagnostics: `{ contentPx, targetPx, disparityPx, filteredPx, drawn, pxPerBaseline }` (output px, + = in front) or null. */
+    /** The last frame's placement, for diagnostics: `{ contentPx, targetPx, disparityPx, filteredPx, drawn, pxPerBaseline, soften }` (output px, + = in front) or null. */
     this.last = null;
   }
 
@@ -308,9 +364,22 @@ export class PairCursor {
     const d = cursorFilterStep(this.filter, CURSOR_DEFAULT_TUNING, target, nowSec);
     const drawn = cursorShouldDraw(d, pxPerBaseline);
     const disparity = -d * pxPerBaseline; // output px, + = in front
-    if (drawn) drawPairArrow(g, geo.outW, geo.outH, u, v, disparity, hf * geo.outH);
+    let soften = null;
+    if (drawn) {
+      // Softening in PANEL px: one output px of an eye spans (tile CSS width × dpr) / outW of them.
+      // The ghost offset of a pair IS its disparity (the two halves are the two views).
+      const sizePx = hf * geo.outH;
+      const dpr = globalThis.devicePixelRatio > 0 ? globalThis.devicePixelRatio : 1;
+      const k = r && r.width > 0 ? (r.width * dpr) / geo.outW : 1;
+      const spritePx = r && r.height > 0 ? hf * r.height * dpr : sizePx;
+      const s = cursorSoften(d, disparity * k, spritePx, this.soften);
+      soften = { blurPx: s.blurPx, alpha: s.alpha, ghostPx: Math.abs(disparity * k), spritePx, radius: spritePx > 0 ? s.blurPx / spritePx : 0, soft: s.blurPx > 0 || s.alpha < 1 };
+      if (!soften.soft || !drawPairArrowSoft(g, geo.outW, geo.outH, u, v, disparity, sizePx, soften.radius, s.alpha)) {
+        drawPairArrow(g, geo.outW, geo.outH, u, v, disparity, sizePx);
+      }
+    }
     this.pointer.hideCss(drawn); // the OS arrow IS the cursor on the plane
-    this.last = { contentPx: this._content, targetPx: -target * pxPerBaseline || 0, disparityPx: drawn ? disparity : 0, filteredPx: disparity || 0, drawn, pxPerBaseline };
+    this.last = { contentPx: this._content, targetPx: -target * pxPerBaseline || 0, disparityPx: drawn ? disparity : 0, filteredPx: disparity || 0, drawn, pxPerBaseline, soften };
     return this.last;
   }
 

package/js/inline3d-cursor-bvh.js

@@ -0,0 +1,147 @@
+// inline3d-cursor-bvh.js — the depth cursor's pick, BVH-accelerated, for three.js scenes.
+//
+// Loaded ONLY when a page opts into `cursor: 'depth'` (./model imports it dynamically on opt-in;
+// ADR-046 §0: zero cost, no download otherwise). It brings the vendored MeshBVH slice of
+// three-mesh-bvh (js/vendor/three-mesh-bvh.js, MIT), which imports the page's own `three`.
+//
+// Same answer as three's Raycaster.intersectObjects(targets, true)[0] — the nearest hit, the same
+// layer test, the same traversal (an object's raycast returning false stops its subtree) — but each
+// plain Mesh is tested against a bounds tree instead of every triangle. Nothing on the page is
+// touched: no prototype patching, no `geometry.boundsTree`, no index reordering (`indirect: true`);
+// the trees live in a WeakMap keyed by geometry.
+//
+//  - Built lazily, the first time a ray reaches a mesh's bounding sphere, within a small time
+//    budget a frame (one big mesh may exceed it once; it cannot be split). A mesh not built yet is
+//    raycast the plain way meanwhile, so the answer never waits for a build.
+//  - CPU-animated vertices (the position attribute's version moves): the tree is refitted.
+//    A replaced attribute, a changed vertex count or index: rebuilt.
+//  - Skinned, morphing, instanced or batched meshes, a partial drawRange, and anything that is not
+//    a Mesh (points, lines, sprites, a splat's own raycast): three's own raycast, as before —
+//    its answer follows the deformation; a static tree would not.
+
+import { MeshBVH } from './vendor/three-mesh-bvh.js';
+
+/** Build time allowed per ~frame (ms) before further builds wait for the next one. */
+const BUILD_BUDGET_MS = 4;
+const FRAME_MS = 16;
+
+/**
+ * A hit test for ./three's DepthCursor over `targets` (searched recursively): the nearest hit along
+ * a WORLD ray, as a world point, or null.
+ * @param {object} THREE  the page's three.js namespace.
+ * @param {object[]} targets  Object3Ds that count as content.
+ * @returns {((origin: number[], direction: number[]) => number[]|null) & {info: () => object}}
+ */
+export function bvhHitTest(THREE, targets, { now = () => (globalThis.performance ? globalThis.performance.now() : Date.now()) } = {}) {
+  const raycaster = new THREE.Raycaster();
+  raycaster.firstHitOnly = true; // MeshBVH.raycastObject3D: the nearest hit only
+  const o = new THREE.Vector3();
+  const d = new THREE.Vector3();
+  const sphere = new THREE.Sphere();
+  const trees = new WeakMap(); // geometry → { bvh, pos, idx, count, posVersion, idxVersion } | false (cannot)
+  const hits = [];
+  const info = { mode: 'bvh', built: 0, refits: 0, failed: 0, buildMs: 0, plainCasts: 0 };
+  let windowStart = -Infinity;
+  let spent = 0;
+  const best = [0, 0, 0];
+  let bestDist = Infinity;
+
+  function treeFor(mesh) {
+    if (mesh.isSkinnedMesh || mesh.isInstancedMesh || mesh.isBatchedMesh) return null;
+    const g = mesh.geometry;
+    if (!g || !g.attributes) return null;
+    const pos = g.attributes.position;
+    if (!pos) return null;
+    if (g.morphAttributes && g.morphAttributes.position && g.morphAttributes.position.length) return null;
+    const idx = g.index;
+    const full = idx ? idx.count : pos.count;
+    const dr = g.drawRange;
+    if (dr && (dr.start > 0 || (dr.count !== Infinity && dr.count < full))) return null;
+    let t = trees.get(g);
+    if (t === false) return null;
+    if (t) {
+      if (t.pos !== pos || t.idx !== idx || t.count !== pos.count || (idx && idx.version !== t.idxVersion)) {
+        trees.delete(g); // replaced or resized: rebuild below
+        t = undefined;
+      } else {
+        if (pos.version !== t.posVersion) {
+          t.bvh.refit(); // vertices animated on the CPU
+          t.posVersion = pos.version;
+          info.refits++;
+        }
+        return t;
+      }
+    }
+    const t0 = now();
+    if (t0 - windowStart >= FRAME_MS) {
+      windowStart = t0;
+      spent = 0;
+    }
+    if (spent >= BUILD_BUDGET_MS) return null; // plain raycast this time; built on a later frame
+    try {
+      const bvh = new MeshBVH(g, { indirect: true, setBoundingBox: false, verbose: false });
+      t = { bvh, pos, idx, count: pos.count, posVersion: pos.version, idxVersion: idx ? idx.version : 0 };
+      trees.set(g, t);
+      info.built++;
+    } catch (err) {
+      trees.set(g, false); // e.g. a three.js older than the slice supports: plain raycast for good
+      info.failed++;
+      t = null;
+    }
+    const dt = now() - t0;
+    spent += dt;
+    info.buildMs += dt;
+    return t;
+  }
+
+  function castOne(obj) {
+    hits.length = 0;
+    let result;
+    const t = obj.isMesh ? treeFor(obj) : null;
+    if (t) {
+      const g = obj.geometry;
+      if (g.boundingSphere === null) g.computeBoundingSphere(); // as Mesh.raycast does
+      sphere.copy(g.boundingSphere).applyMatrix4(obj.matrixWorld);
+      if (!raycaster.ray.intersectsSphere(sphere)) return undefined;
+      t.bvh.raycastObject3D(obj, raycaster, hits);
+    } else {
+      if (obj.isMesh || obj.isPoints || obj.isLine || obj.isSprite) info.plainCasts++; // drawables only, not groups
+      result = obj.raycast(raycaster, hits);
+    }
+    for (let i = 0; i < hits.length; i++) {
+      const h = hits[i];
+      if (h.distance < bestDist) {
+        bestDist = h.distance;
+        best[0] = h.point.x;
+        best[1] = h.point.y;
+        best[2] = h.point.z;
+      }
+    }
+    return result;
+  }
+
+  // Raycaster.intersectObject's traversal: the layer test, and `false` from raycast stops the subtree.
+  function visit(obj) {
+    let propagate = true;
+    if (obj.layers.test(raycaster.layers)) {
+      if (castOne(obj) === false) propagate = false;
+    }
+    if (propagate) {
+      const c = obj.children;
+      for (let i = 0; i < c.length; i++) visit(c[i]);
+    }
+  }
+
+  const hitTest = (origin, direction) => {
+    o.set(origin[0], origin[1], origin[2]);
+    d.set(direction[0], direction[1], direction[2]).normalize();
+    raycaster.set(o, d);
+    bestDist = Infinity;
+    for (let i = 0; i < targets.length; i++) visit(targets[i]);
+    hits.length = 0;
+    return bestDist < Infinity ? [best[0], best[1], best[2]] : null;
+  };
+  /** Diagnostics: `{ mode: 'bvh', built, refits, failed, buildMs, plainCasts }` (cumulative). */
+  hitTest.info = () => ({ ...info });
+  return hitTest;
+}

package/js/inline3d-cursor-depth-playcanvas.js

@@ -19,7 +19,9 @@
 // glass — as the classic arrow (the shared cursorArrowMesh: dark outline, white fill, tip on the
 // hotspot) in the UI layer with depth test off, so every eye camera draws it last and nothing
 // occludes it; the picker skips the UI layer, so the cursor never picks itself. On the plane
-// nothing is drawn and the CSS cursor is the cursor.
+// nothing is drawn and the CSS cursor is the cursor. A LIFTED arrow is softened against crosstalk
+// (ADR-046 Amendment 2 §B.7): the mesh instance swaps to a quad whose shader blurs and fades the
+// arrow (cursorSoftArrowGLSL); a (0 px, 1.0) frame draws the crisp mesh exactly as before.
 
 import {
   CursorDepthPlacer,
@@ -28,7 +30,13 @@ import {
   cursorArrowMesh,
   cursorArrowFootprint,
   cursorDefaultHeight,
+  cursorPlacementSoften,
+  cursorSoftArrowBox,
+  cursorSoftArrowGLSL,
   cursorViewRay,
+  resolveCursorSoften,
+  CURSOR_FILL_COLOR,
+  CURSOR_OUTLINE_COLOR,
 } from './inline3d-cursor-depth.js';
 
 /** Pick-buffer width in pixels (height follows the eye's aspect). */
@@ -42,9 +50,9 @@ export class PlayCanvasDepthCursor {
   /**
    * @param {object} pc  the PlayCanvas namespace the adapter renders with.
    * @param {object} viewer  the PlayCanvasSplatViewer (app, rigNode, eye are read lazily).
-   * @param {{canvas: HTMLElement, height?: number, margin?: number, anchor?: string, pointerScope?: string}} opts
+   * @param {{canvas: HTMLElement, height?: number, margin?: number, anchor?: string, pointerScope?: string, soften?: string|object}} opts
    */
-  constructor(pc, viewer, { canvas, height, margin, anchor = 'hybrid', pointerScope = 'canvas' }) {
+  constructor(pc, viewer, { canvas, height, margin, anchor = 'hybrid', pointerScope = 'canvas', soften }) {
     this.pc = pc;
     this.viewer = viewer;
     /** Sprite height (canvas heights) when set; null = the OS arrow's size, from the canvas's on-page height. */
@@ -54,6 +62,10 @@ export class PlayCanvasDepthCursor {
     this.placer = new CursorDepthPlacer(tuning, { anchor });
     /** The last placement (diagnostics). */
     this.placement = { active: false };
+    /** Crosstalk softening parameters (resolveCursorSoften). */
+    this.soften = resolveCursorSoften(soften, '@displayxr/inline3d cursor');
+    /** The last frame's softening (diagnostics), null while nothing is drawn. */
+    this.softening = null;
     /** The last picked world point under the footprint, or null (nothing under it). */
     this.hit = null;
     this._picker = null;
@@ -99,9 +111,12 @@ export class PlayCanvasDepthCursor {
     this.placement = p;
     this.pointer.hideCss(!!p.active);
     const sprite = this._sprite || (p.active ? this._makeSprite(app) : null);
+    this.softening = null;
     if (!sprite) return;
     sprite.mi.visible = !!p.active;
     if (!p.active) return;
+    const [pw, ph] = this.pointer.panelSize();
+    this._useSoft(app, sprite, (this.softening = cursorPlacementSoften(p, views, pw, ph, h, this.soften)));
     // The unit arrow in the sprite's XY plane, tip at its origin: basis (rotation), height (scale), position = the hotspot.
     const { x, y, z } = p.basis;
     const q = quatFromMatrix([x[0], x[1], x[2], 0, y[0], y[1], y[2], 0, z[0], z[1], z[2], 0, 0, 0, 0, 1]);
@@ -113,6 +128,7 @@ export class PlayCanvasDepthCursor {
   /** Mono / no pointer / no views: no sprite, the CSS cursor back. */
   inactive() {
     if (this.placement.active) this.placement = { active: false };
+    this.softening = null;
     this.placer.update(null); // forget the hybrid anchor
     if (this._sprite) this._sprite.mi.visible = false;
     this.pointer.hideCss(false);
@@ -161,10 +177,74 @@ export class PlayCanvasDepthCursor {
     mi.pick = false;
     mi.drawOrder = 1e9;
     app.scene.layers.getLayerById(pc.LAYERID_UI).addMeshInstances([mi]);
-    this._sprite = { mi, node, mat };
+    this._sprite = { mi, node, mat, mesh, soft: null };
     return this._sprite;
   }
 
+  // Crisp: the arrow mesh and material as built above. Softened: a quad over the padded arrow box,
+  // its shader the runtime's 13-tap blur of the arrow, times the opacity.
+  _useSoft(app, sprite, s) {
+    const mi = sprite.mi;
+    if (!s.soft) {
+      if (mi.mesh !== sprite.mesh) mi.mesh = sprite.mesh;
+      if (mi.material !== sprite.mat) mi.material = sprite.mat;
+      return;
+    }
+    const soft = sprite.soft || (sprite.soft = this._makeSoft(app));
+    soft.mat.setParameter('inline3dCursorBox', cursorSoftArrowBox(s.radius, s.aa));
+    soft.mat.setParameter('inline3dCursorSoft', [s.radius, s.alpha, s.aa, 0]);
+    if (mi.mesh !== soft.mesh) mi.mesh = soft.mesh;
+    if (mi.material !== soft.mat) mi.material = soft.mat;
+  }
+
+  _makeSoft(app) {
+    const pc = this.pc;
+    const mesh = new pc.Mesh(app.graphicsDevice);
+    // A unit quad; the vertex shader spreads it over the padded arrow box (arrow units, y down).
+    mesh.setPositions(new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0]));
+    mesh.update();
+    const mat = new pc.ShaderMaterial({
+      uniqueName: 'inline3dDepthCursorSoft',
+      attributes: { vertex_position: pc.SEMANTIC_POSITION },
+      vertexGLSL: `
+        attribute vec3 vertex_position;
+        uniform mat4 matrix_model;
+        uniform mat4 matrix_viewProjection;
+        uniform vec4 inline3dCursorBox;
+        varying vec2 vArrow;
+        void main() {
+          vArrow = vec2(mix(inline3dCursorBox.x, inline3dCursorBox.z, vertex_position.x), mix(inline3dCursorBox.y, inline3dCursorBox.w, vertex_position.y));
+          gl_Position = matrix_viewProjection * matrix_model * vec4(vArrow.x, -vArrow.y, 0.0, 1.0);
+        }`,
+      fragmentGLSL: `
+        uniform vec4 inline3dCursorSoft; // radius, opacity, aa (arrow units)
+        uniform vec3 inline3dCursorFill;
+        uniform vec3 inline3dCursorOutline;
+        varying vec2 vArrow;
+        ${cursorSoftArrowGLSL()}
+        void main() {
+          vec4 c = inline3dSoftArrow(vArrow, inline3dCursorSoft.x, inline3dCursorSoft.z, inline3dCursorFill, inline3dCursorOutline);
+          gl_FragColor = vec4(c.rgb, c.a * inline3dCursorSoft.y);
+        }`,
+    });
+    mat.setParameter('inline3dCursorFill', CURSOR_FILL_COLOR.slice(0, 3));
+    mat.setParameter('inline3dCursorOutline', CURSOR_OUTLINE_COLOR.slice(0, 3));
+    mat.blendState = new pc.BlendState(
+      true,
+      pc.BLENDEQUATION_ADD,
+      pc.BLENDMODE_SRC_ALPHA,
+      pc.BLENDMODE_ONE_MINUS_SRC_ALPHA,
+      pc.BLENDEQUATION_ADD,
+      pc.BLENDMODE_ONE,
+      pc.BLENDMODE_ONE_MINUS_SRC_ALPHA,
+    );
+    mat.depthTest = false;
+    mat.depthWrite = false;
+    mat.cull = pc.CULLFACE_NONE;
+    mat.update();
+    return { mesh, mat };
+  }
+
   dispose() {
     this._disposed = true;
     this.pointer.dispose();
@@ -172,6 +252,8 @@ export class PlayCanvasDepthCursor {
       if (this._sprite) {
         this.viewer.app?.scene?.layers?.getLayerById(this.pc.LAYERID_UI)?.removeMeshInstances?.([this._sprite.mi]);
         this._sprite.node.destroy?.();
+        this._sprite.soft?.mat.destroy?.();
+        this._sprite.soft?.mesh.destroy?.();
       }
       this._picker?.destroy?.();
       this._pickCam?.destroy?.();
@@ -222,6 +304,13 @@ export class PlayCanvasDepthCursor {
 
     const picker = this._picker;
     picker.resize(W, H);
+    // The depth picker draws into TWO colour targets (pick id + pick depth). The engine's lit and
+    // gsplat shaders write both under DEPTH_PICK_PASS; an app's own pc.ShaderMaterial usually
+    // writes only the first, and WebGL rejects every such draw with GL_INVALID_OPERATION ("Active
+    // draw buffers with missing fragment shader outputs") — one per mesh per pick, so a page with
+    // a custom-shader backdrop logged hundreds a second. Those draws never reached the pick buffer
+    // anyway: leave them out of the pass, exactly as if they were not pickable.
+    const muted = muteDepthlessPicks(pc, layers, app.graphicsDevice);
     try {
       // Enabled only for the synchronous pick pass: a disabled camera is not in its layers'
       // camera lists, so the picker would render nothing; enabled outside it, the camera would
@@ -234,6 +323,7 @@ export class PlayCanvasDepthCursor {
       return;
     } finally {
       cam.camera.enabled = false;
+      for (const mi of muted) mi.pick = true;
     }
     // The picker stores LINEAR depth: (viewDist - near) / (far - near), viewDist = 1/gl_FragCoord.w.
     // Rebuild the point ourselves along the exact off-axis ray (getWorldPointAsync would unproject
@@ -282,6 +372,62 @@ export class PlayCanvasDepthCursor {
 }
 
 /** A copy of a column-major transform with unit rotation columns (scale removed). */
+// Does this material's pick shader write the depth-pick output (the second colour target)? Engine
+// materials do; a pc.ShaderMaterial does when its fragment code, with its #includes followed
+// through the material's and the engine's chunk maps, handles DEPTH_PICK_PASS — the engine's own
+// gsplat material is a ShaderMaterial whose whole fragment is `#include "gsplatPS"`.
+const writesPickDepth = new WeakMap();
+const PICK_DEPTH_RE = /DEPTH_PICK_PASS|pcFragColor1/;
+function materialWritesPickDepth(pc, mat, device) {
+  if (!mat || !pc.ShaderMaterial || !(mat instanceof pc.ShaderMaterial)) return true;
+  let v = writesPickDepth.get(mat);
+  if (v !== undefined) return v;
+  v = true; // can't tell: leave it in the pass, as before
+  try {
+    const wgsl = !!device?.isWebGPU;
+    const d = mat.shaderDesc || {};
+    const root = wgsl ? d.fragmentWGSL : d.fragmentGLSL ?? d.fragmentCode;
+    if (typeof root === 'string') {
+      const lang = wgsl ? pc.SHADERLANGUAGE_WGSL : pc.SHADERLANGUAGE_GLSL;
+      const own = mat.hasShaderChunks ? (wgsl ? mat.shaderChunks.wgsl : mat.shaderChunks.glsl) : null;
+      const engine = pc.ShaderChunks?.get ? pc.ShaderChunks.get(device, lang) : null;
+      const chunk = (name) => own?.get?.(name) ?? engine?.get?.(name);
+      const seen = new Set();
+      const scan = (code, depth) => {
+        if (PICK_DEPTH_RE.test(code)) return true;
+        if (depth > 8) return false;
+        for (const [, name] of code.matchAll(/#include\s+"(\w+)"/g)) {
+          if (seen.has(name)) continue;
+          seen.add(name);
+          const c = chunk(name);
+          if (typeof c === 'string' && scan(c, depth + 1)) return true;
+        }
+        return false;
+      };
+      v = scan(root, 0);
+    }
+  } catch {
+    v = true;
+  }
+  writesPickDepth.set(mat, v);
+  return v;
+}
+
+// Clear `pick` on the layers' mesh instances whose shader cannot write pick depth; returns them so
+// the caller restores the flag right after the (synchronous) pick pass.
+function muteDepthlessPicks(pc, layers, device) {
+  const muted = [];
+  for (const layer of layers) {
+    for (const mi of layer.meshInstances || []) {
+      if (mi.pick && !materialWritesPickDepth(pc, mi.material, device)) {
+        mi.pick = false;
+        muted.push(mi);
+      }
+    }
+  }
+  return muted;
+}
+
 function unscaled(m) {
   const o = Array.from(m);
   for (const c of [0, 4, 8]) {