@terraware/web-components 5.0.27-rc.0 → 5.0.27

package/components/VirtualWalkthrough/xr-gaze-dwell.js

@@ -1,120 +1,157 @@
-import { Entity, LAYERID_IMMEDIATE, MeshInstance, Quat, Script, Vec3, XRTYPE_VR } from "playcanvas";
-import { HOTSPOT_HALF_EXTENT, createAnnotationCandidateBuffer } from "./xr-annotation-candidates.js";
-import { nearestAnnotationHit } from "./xr-annotation-targeting.js";
-import { INITIAL_DWELL_STATE, advanceDwell } from "./xr-gaze-dwell-state.js";
-import { pieShaderProgress } from "./xr-progress-pie.js";
-import { createProgressPieMaterial, emptyMaskTexture, progressPieQuadMesh } from "./xr-progress-pie-material.js";
+import { Vec3, Script, Quat, XRTYPE_VR, MeshInstance, Entity, LAYERID_IMMEDIATE } from 'playcanvas';
+import { createAnnotationCandidateBuffer } from './xr-annotation-candidates.js';
+import { nearestAnnotationHit } from './xr-annotation-targeting.js';
+import { INITIAL_DWELL_STATE, advanceDwell } from './xr-gaze-dwell-state.js';
+import { pieShaderProgress } from './xr-progress-pie.js';
+import { emptyMaskTexture, createProgressPieMaterial, progressPieQuadMesh } from './xr-progress-pie-material.js';
+import { HOTSPOT_HALF_EXTENT } from './xr-annotation-candidate-buffer.js';
+
+/** Multiplier on the hotspot's world radius for gaze targeting. */
 const GAZE_HIT_RADIUS_PAD = 5;
+
+/** Seconds of continuous gaze required to open an annotation. */
 const DWELL_SECONDS = 1.25;
+
+/** Progress-pie quad radius as a multiple of the hotspot's rendered half-extent (covers the hotspot). */
 const PIE_RADIUS_SCALE = 1.25;
 const LOCAL_FORWARD = new Vec3(0, 0, -1);
 class XrGazeDwell extends Script {
-    static scriptName = 'xrGazeDwell';
-    activeIndex = -1;
-    _dwell = INITIAL_DWELL_STATE;
-    _candidates = createAnnotationCandidateBuffer();
-    _pieEntity;
-    _pieMaterial;
-    _pieMesh;
-    _pieMask;
-    _headPos = new Vec3();
-    _headRot = new Quat();
-    _viewOffset = new Vec3();
-    _forward = new Vec3();
-    _scratchScale = new Vec3();
-    _isVrActive = ()=>this.app.xr?.active === true && this.app.xr?.type === XRTYPE_VR;
-    _onXrStart = ()=>{
-        this._dwell = INITIAL_DWELL_STATE;
-        this._setPieEnabled(this._isVrActive());
-    };
-    _onXrEnd = ()=>{
-        this._dwell = INITIAL_DWELL_STATE;
-        this._pieMaterial?.setParameter('uProgress', 0);
-        this._setPieEnabled(false);
-    };
-    _setPieEnabled(enabled) {
-        if (this._pieEntity) this._pieEntity.enabled = enabled;
+  static scriptName = 'xrGazeDwell';
+
+  /** Index of the annotation whose panel is currently open, or -1. Excluded from gaze targets so
+   * dwell opens OTHER annotations while one is open (and never re-dwells the open one). */
+  activeIndex = -1;
+  _dwell = INITIAL_DWELL_STATE;
+  _candidates = createAnnotationCandidateBuffer();
+  _headPos = new Vec3();
+  _headRot = new Quat();
+  _viewOffset = new Vec3();
+  _forward = new Vec3();
+  _scratchScale = new Vec3();
+  _isVrActive = () => this.app.xr?.active === true && this.app.xr?.type === XRTYPE_VR;
+
+  /**
+   * A render component hands its mesh instances to a layer only when it flips from disabled to
+   * enabled, and hands over nothing if the layer cannot be resolved yet. The session events are the
+   * points where the layers are known to exist, so the pie flips there: start registers it, and end
+   * restores the transition for the next session.
+   */
+  _onXrStart = () => {
+    this._dwell = INITIAL_DWELL_STATE;
+    this._setPieEnabled(this._isVrActive());
+  };
+  _onXrEnd = () => {
+    this._dwell = INITIAL_DWELL_STATE;
+    this._pieMaterial?.setParameter('uProgress', 0);
+    this._setPieEnabled(false);
+  };
+  _setPieEnabled(enabled) {
+    if (this._pieEntity) {
+      this._pieEntity.enabled = enabled;
     }
-    initialize() {
-        this._pieMask = emptyMaskTexture(this.app.graphicsDevice);
-        this._pieMaterial = createProgressPieMaterial({
-            uniqueName: 'xr-gaze-dwell-pie',
-            maskMap: this._pieMask
-        });
-        this._pieMesh = progressPieQuadMesh(this.app.graphicsDevice, HOTSPOT_HALF_EXTENT);
-        const meshInstance = new MeshInstance(this._pieMesh, this._pieMaterial);
-        meshInstance.cull = false;
-        this._pieEntity = new Entity('xr-gaze-dwell-pie');
-        this._pieEntity.addComponent('render', {
-            meshInstances: [
-                meshInstance
-            ],
-            layers: [
-                LAYERID_IMMEDIATE
-            ]
-        });
-        this._pieEntity.enabled = false;
-        this.entity.addChild(this._pieEntity);
-        this._setPieEnabled(this._isVrActive());
-        this.app.xr?.on('start', this._onXrStart);
-        this.app.xr?.on('end', this._onXrEnd);
+  }
+  initialize() {
+    this._pieMask = emptyMaskTexture(this.app.graphicsDevice);
+    this._pieMaterial = createProgressPieMaterial({
+      uniqueName: 'xr-gaze-dwell-pie',
+      maskMap: this._pieMask
+    });
+    this._pieMesh = progressPieQuadMesh(this.app.graphicsDevice, HOTSPOT_HALF_EXTENT);
+    const meshInstance = new MeshInstance(this._pieMesh, this._pieMaterial);
+
+    // Never frustum-culled. The quad only takes a position once a sweep starts, and until then sits
+    // at the origin where culling would drop it from the render list - taking the shader compile it
+    // stays enabled for along with it. An always-submitted quad that discards every fragment costs
+    // less than that compile landing mid-gaze.
+    meshInstance.cull = false;
+    this._pieEntity = new Entity('xr-gaze-dwell-pie');
+    this._pieEntity.addComponent('render', {
+      meshInstances: [meshInstance],
+      layers: [LAYERID_IMMEDIATE]
+    });
+    this._pieEntity.enabled = false;
+    this.entity.addChild(this._pieEntity);
+
+    // Both orders happen: the walkthrough can mount into a session that has already started (as it
+    // does when VR is entered from outside the canvas), or mount first and wait for one.
+    this._setPieEnabled(this._isVrActive());
+    this.app.xr?.on('start', this._onXrStart);
+    this.app.xr?.on('end', this._onXrEnd);
+  }
+  update(dt) {
+    if (!this._pieEntity || !this._pieMaterial) {
+      return;
     }
-    update(dt) {
-        if (!this._pieEntity || !this._pieMaterial) return;
-        if (!this._isVrActive() || !this._trackHead()) {
-            this._dwell = INITIAL_DWELL_STATE;
-            this._pieMaterial.setParameter('uProgress', 0);
-            return;
-        }
-        const candidates = this._candidates.collect(this.app, GAZE_HIT_RADIUS_PAD, `annotation-${this.activeIndex}`);
-        this._headRot.transformVector(LOCAL_FORWARD, this._forward);
-        const target = nearestAnnotationHit(this._headPos, this._forward, candidates);
-        const result = advanceDwell(this._dwell, target, dt, DWELL_SECONDS);
-        this._dwell = result.state;
-        const progress = pieShaderProgress(result.progress);
-        this._pieMaterial.setParameter('uProgress', progress);
-        if (progress > 0 && null !== target) this._placePie(candidates[target].entity);
-        if (result.justOpened && null !== target) {
-            const { entity, script } = candidates[target];
-            const camera = this.app.root.findComponent('camera');
-            const screen = camera?.worldToScreen(entity.getPosition());
-            script.onVrOpenCallback(screen?.x ?? 0, screen?.y ?? 0);
-        }
+    if (!this._isVrActive() || !this._trackHead()) {
+      this._dwell = INITIAL_DWELL_STATE;
+      this._pieMaterial.setParameter('uProgress', 0);
+      return;
     }
-    _trackHead() {
-        const views = this.app.xr?.views?.list;
-        if (!views || 0 === views.length) return false;
-        this._headPos.set(0, 0, 0);
-        for (const view of views){
-            view.viewInvOffMat.getTranslation(this._viewOffset);
-            this._headPos.add(this._viewOffset);
-        }
-        this._headPos.mulScalar(1 / views.length);
-        this._headRot.setFromMat4(views[0].viewInvOffMat);
-        return true;
+    const candidates = this._candidates.collect(this.app, GAZE_HIT_RADIUS_PAD, `annotation-${this.activeIndex}`);
+    this._headRot.transformVector(LOCAL_FORWARD, this._forward);
+    const target = nearestAnnotationHit(this._headPos, this._forward, candidates);
+    const result = advanceDwell(this._dwell, target, dt, DWELL_SECONDS);
+    this._dwell = result.state;
+    const progress = pieShaderProgress(result.progress);
+    this._pieMaterial.setParameter('uProgress', progress);
+    if (progress > 0 && target !== null) {
+      this._placePie(candidates[target].entity);
     }
-    _placePie(entity) {
-        if (!this._pieEntity) return;
-        entity.getWorldTransform().getScale(this._scratchScale);
-        const scale = this._scratchScale.x * PIE_RADIUS_SCALE;
-        this._pieEntity.setLocalScale(scale, scale, scale);
-        this._pieEntity.setPosition(entity.getPosition());
-        this._pieEntity.setRotation(this._headRot);
+    if (result.justOpened && target !== null) {
+      const {
+        entity,
+        script
+      } = candidates[target];
+      const camera = this.app.root.findComponent('camera');
+      const screen = camera?.worldToScreen(entity.getPosition());
+      script.onVrOpenCallback(screen?.x ?? 0, screen?.y ?? 0);
     }
-    destroy() {
-        this.app.xr?.off('start', this._onXrStart);
-        this.app.xr?.off('end', this._onXrEnd);
-        if (this._pieEntity) {
-            if (this._pieEntity.render) this._pieEntity.render.meshInstances = [];
-            this._pieEntity.destroy();
-            this._pieEntity = void 0;
-        }
-        this._pieMesh?.destroy();
-        this._pieMaterial?.destroy();
-        this._pieMask?.destroy();
-        this._pieMesh = void 0;
-        this._pieMaterial = void 0;
-        this._pieMask = void 0;
+  }
+  _trackHead() {
+    const views = this.app.xr?.views?.list;
+    if (!views || views.length === 0) {
+      return false;
     }
+    this._headPos.set(0, 0, 0);
+    for (const view of views) {
+      view.viewInvOffMat.getTranslation(this._viewOffset);
+      this._headPos.add(this._viewOffset);
+    }
+    this._headPos.mulScalar(1 / views.length);
+    this._headRot.setFromMat4(views[0].viewInvOffMat);
+    return true;
+  }
+
+  /** Sits the pie on the hotspot, square to the head. */
+  _placePie(entity) {
+    if (!this._pieEntity) {
+      return;
+    }
+
+    // The unit quad has half-extent HOTSPOT_HALF_EXTENT, so scale it to reach the desired world size.
+    entity.getWorldTransform().getScale(this._scratchScale);
+    const scale = this._scratchScale.x * PIE_RADIUS_SCALE;
+    this._pieEntity.setLocalScale(scale, scale, scale);
+    this._pieEntity.setPosition(entity.getPosition());
+    this._pieEntity.setRotation(this._headRot);
+  }
+  destroy() {
+    this.app.xr?.off('start', this._onXrStart);
+    this.app.xr?.off('end', this._onXrEnd);
+    if (this._pieEntity) {
+      if (this._pieEntity.render) {
+        this._pieEntity.render.meshInstances = [];
+      }
+      this._pieEntity.destroy();
+      this._pieEntity = undefined;
+    }
+    this._pieMesh?.destroy();
+    this._pieMaterial?.destroy();
+    this._pieMask?.destroy();
+    this._pieMesh = undefined;
+    this._pieMaterial = undefined;
+    this._pieMask = undefined;
+  }
 }
+
 export { XrGazeDwell };

package/components/VirtualWalkthrough/xr-interactive-ui.js

@@ -1,15 +1,27 @@
-import { VrAnnotationPanel } from "./vr-annotation-panel.js";
-import { HIT_RADIUS_PAD, collectAnnotationHitCandidates } from "./xr-annotation-candidates.js";
-import { nearestAnnotationHit } from "./xr-annotation-targeting.js";
-import { XrExitButton } from "./xr-exit-button.js";
-const rayHitsAnnotationHotspot = (app, origin, direction)=>null !== nearestAnnotationHit(origin, direction, collectAnnotationHitCandidates(app, HIT_RADIUS_PAD));
-const rayHitsAnnotationPanel = (app, origin, direction)=>{
-    const script = app.root.findByName('vr-annotation-panel')?.script?.get(VrAnnotationPanel.scriptName);
-    return 'function' == typeof script?.rayHitsPanel && true === script.rayHitsPanel(origin, direction);
+import { VrAnnotationPanel } from './vr-annotation-panel.js';
+import { collectAnnotationHitCandidates, HIT_RADIUS_PAD } from './xr-annotation-candidates.js';
+import { nearestAnnotationHit } from './xr-annotation-targeting.js';
+import { XrExitButton } from './xr-exit-button.js';
+
+/** True when the ray points at an openable annotation hotspot. */
+const rayHitsAnnotationHotspot = (app, origin, direction) => nearestAnnotationHit(origin, direction, collectAnnotationHitCandidates(app, HIT_RADIUS_PAD)) !== null;
+
+/** True when the ray points at the open VR annotation panel. False when no panel is mounted. */
+const rayHitsAnnotationPanel = (app, origin, direction) => {
+  const script = app.root.findByName('vr-annotation-panel')?.script?.get(VrAnnotationPanel.scriptName);
+  return typeof script?.rayHitsPanel === 'function' && script.rayHitsPanel(origin, direction) === true;
 };
-const rayHitsExitButton = (app, origin, direction)=>{
-    const script = app.root.findByName('xr-exit-button')?.script?.get(XrExitButton.scriptName);
-    return 'function' == typeof script?.rayHitsButton && true === script.rayHitsButton(origin, direction);
+
+/** True when the ray points at the VR exit button. */
+const rayHitsExitButton = (app, origin, direction) => {
+  const script = app.root.findByName('xr-exit-button')?.script?.get(XrExitButton.scriptName);
+  return typeof script?.rayHitsButton === 'function' && script.rayHitsButton(origin, direction) === true;
 };
-const rayHitsInteractiveUi = (app, origin, direction)=>rayHitsAnnotationHotspot(app, origin, direction) || rayHitsAnnotationPanel(app, origin, direction) || rayHitsExitButton(app, origin, direction);
+
+/**
+ * True when the ray points at anything the trigger is meant to operate. Teleport consults this so a
+ * select that lands on UI doesn't also move the rig.
+ */
+const rayHitsInteractiveUi = (app, origin, direction) => rayHitsAnnotationHotspot(app, origin, direction) || rayHitsAnnotationPanel(app, origin, direction) || rayHitsExitButton(app, origin, direction);
+
 export { rayHitsAnnotationHotspot, rayHitsAnnotationPanel, rayHitsExitButton, rayHitsInteractiveUi };

package/components/VirtualWalkthrough/xr-pointer-ray.js

@@ -1,19 +1,26 @@
-import { Color, Script, Vec3 } from "playcanvas";
+import { Color, Script, Vec3 } from 'playcanvas';
+
+/** Length of the drawn pointer ray, in world meters. */
 const RAY_LENGTH = 5;
+
+/** Default ray colour (cyan) — bright enough to read against the scene. */
 const DEFAULT_RAY_COLOR = new Color(0.25, 0.8, 1);
 class XrPointerRay extends Script {
-    static scriptName = 'xrPointerRay';
-    color = DEFAULT_RAY_COLOR.clone();
-    _end = new Vec3();
-    update() {
-        if (this.app.xr?.active !== true) return;
-        const sources = this.app.xr?.input?.inputSources ?? [];
-        for (const source of sources){
-            const origin = source.getOrigin();
-            const direction = source.getDirection();
-            this._end.copy(direction).mulScalar(RAY_LENGTH).add(origin);
-            this.app.drawLine(origin, this._end, this.color, false);
-        }
+  static scriptName = 'xrPointerRay';
+  color = DEFAULT_RAY_COLOR.clone();
+  _end = new Vec3();
+  update() {
+    if (this.app.xr?.active !== true) {
+      return;
     }
+    const sources = this.app.xr?.input?.inputSources ?? [];
+    for (const source of sources) {
+      const origin = source.getOrigin();
+      const direction = source.getDirection();
+      this._end.copy(direction).mulScalar(RAY_LENGTH).add(origin);
+      this.app.drawLine(origin, this._end, this.color, false);
+    }
+  }
 }
+
 export { DEFAULT_RAY_COLOR, XrPointerRay };

package/components/VirtualWalkthrough/xr-progress-pie-material.js

@@ -1,6 +1,11 @@
-import { ADDRESS_CLAMP_TO_EDGE, BLEND_NORMAL, CULLFACE_NONE, FILTER_NEAREST, Mesh, PIXELFORMAT_RGBA8, SEMANTIC_POSITION, SEMANTIC_TEXCOORD0, ShaderMaterial, Texture } from "playcanvas";
+import { ShaderMaterial, SEMANTIC_TEXCOORD0, SEMANTIC_POSITION, BLEND_NORMAL, CULLFACE_NONE, Texture, ADDRESS_CLAMP_TO_EDGE, FILTER_NEAREST, PIXELFORMAT_RGBA8, Mesh } from 'playcanvas';
+
+/** Pie radius as a fraction of the quad's half-extent. */
 const PIE_RADIUS = 0.92;
-const pieVertexGLSL = `
+
+// GLSL only, for the same reason as BoundaryWallScript: @playcanvas/react's Application defaults to
+// deviceTypes [DEVICETYPE_WEBGL2], so WGSL variants would never be compiled here.
+const pieVertexGLSL = /* glsl */`
     attribute vec3 vertex_position;
     attribute vec2 aUv0;
 
@@ -14,7 +19,16 @@ const pieVertexGLSL = `
         gl_Position = matrix_viewProjection * matrix_model * vec4(vertex_position, 1.0);
     }
 `;
-const pieFragmentGLSL = `
+
+/**
+ * Draws the progress sweep analytically from `uProgress`, so animating it costs one uniform write
+ * per frame.
+ *
+ * `uMaskMap` carries whatever static artwork sits around the pie, baked once by the caller: red is
+ * a mask for a backing disc drawn under the sweep, green a mask for a glyph drawn over it. Callers
+ * with no such artwork bind a transparent pixel and get the bare pie.
+ */
+const pieFragmentGLSL = /* glsl */`
     uniform float uProgress;
     uniform vec3 uTrackColor;
     uniform float uTrackAlpha;
@@ -83,121 +97,78 @@ const pieFragmentGLSL = `
         gl_FragColor = color;
     }
 `;
-const progressPieQuadMesh = (device, halfExtent)=>{
-    const h = halfExtent;
-    const mesh = new Mesh(device);
-    mesh.setPositions([
-        -h,
-        -h,
-        0,
-        h,
-        -h,
-        0,
-        h,
-        h,
-        0,
-        -h,
-        h,
-        0
-    ]);
-    mesh.setNormals([
-        0,
-        0,
-        1,
-        0,
-        0,
-        1,
-        0,
-        0,
-        1,
-        0,
-        0,
-        1
-    ]);
-    mesh.setUvs(0, [
-        0,
-        1,
-        1,
-        1,
-        1,
-        0,
-        0,
-        0
-    ]);
-    mesh.setIndices([
-        0,
-        1,
-        2,
-        0,
-        2,
-        3
-    ]);
-    mesh.update();
-    return mesh;
+
+/** A camera-facing unit quad with y-down UVs, sized to `halfExtent` in local units. */
+const progressPieQuadMesh = (device, halfExtent) => {
+  const h = halfExtent;
+  const mesh = new Mesh(device);
+  mesh.setPositions([-h, -h, 0, h, -h, 0, h, h, 0, -h, h, 0]);
+  mesh.setNormals([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]);
+  mesh.setUvs(0, [0, 1, 1, 1, 1, 0, 0, 0]);
+  mesh.setIndices([0, 1, 2, 0, 2, 3]);
+  mesh.update();
+  return mesh;
 };
-const emptyMaskTexture = (device)=>{
-    const texture = new Texture(device, {
-        name: 'xr-progress-pie-empty-mask',
-        width: 1,
-        height: 1,
-        format: PIXELFORMAT_RGBA8,
-        mipmaps: false,
-        minFilter: FILTER_NEAREST,
-        magFilter: FILTER_NEAREST,
-        addressU: ADDRESS_CLAMP_TO_EDGE,
-        addressV: ADDRESS_CLAMP_TO_EDGE
-    });
-    const pixels = texture.lock();
-    pixels.set([
-        0,
-        0,
-        0,
-        0
-    ]);
-    texture.unlock();
-    return texture;
+
+/**
+ * A single transparent texel, for pies that carry no static artwork of their own.
+ *
+ * The filters are set explicitly because the default minification filter samples a mipmap chain,
+ * which a single-level texture does not have. That combination is incomplete in WebGL, and what a
+ * shader reads from an incomplete texture is not something to rely on.
+ */
+const emptyMaskTexture = device => {
+  const texture = new Texture(device, {
+    name: 'xr-progress-pie-empty-mask',
+    width: 1,
+    height: 1,
+    format: PIXELFORMAT_RGBA8,
+    mipmaps: false,
+    minFilter: FILTER_NEAREST,
+    magFilter: FILTER_NEAREST,
+    addressU: ADDRESS_CLAMP_TO_EDGE,
+    addressV: ADDRESS_CLAMP_TO_EDGE
+  });
+  const pixels = texture.lock();
+  pixels.set([0, 0, 0, 0]);
+  texture.unlock();
+  return texture;
 };
-const createProgressPieMaterial = ({ uniqueName, maskMap, discColor = [
-    0.08,
-    0.08,
-    0.08
-], discAlpha = 0 })=>{
-    const material = new ShaderMaterial({
-        uniqueName,
-        vertexGLSL: pieVertexGLSL,
-        fragmentGLSL: pieFragmentGLSL,
-        attributes: {
-            vertex_position: SEMANTIC_POSITION,
-            aUv0: SEMANTIC_TEXCOORD0
-        }
-    });
-    material.blendType = BLEND_NORMAL;
-    material.cull = CULLFACE_NONE;
-    material.depthTest = false;
-    material.depthWrite = false;
-    material.setParameter('uProgress', 0);
-    material.setParameter('uTrackColor', [
-        1,
-        1,
-        1
-    ]);
-    material.setParameter('uTrackAlpha', 0.18);
-    material.setParameter('uWedgeColor', [
-        64 / 255,
-        200 / 255,
-        1
-    ]);
-    material.setParameter('uWedgeAlpha', 0.85);
-    material.setParameter('uDiscColor', discColor);
-    material.setParameter('uDiscAlpha', discAlpha);
-    material.setParameter('uGlyphColor', [
-        1,
-        1,
-        1
-    ]);
-    material.setParameter('uOpacity', 1);
-    material.setParameter('uMaskMap', maskMap);
-    material.update();
-    return material;
+/**
+ * Material for a progress pie. Everything that animates rides on the `uProgress` uniform, so a
+ * running sweep costs one uniform write per frame and no texture work at all.
+ */
+const createProgressPieMaterial = ({
+  uniqueName,
+  maskMap,
+  discColor = [0.08, 0.08, 0.08],
+  discAlpha = 0
+}) => {
+  const material = new ShaderMaterial({
+    uniqueName,
+    vertexGLSL: pieVertexGLSL,
+    fragmentGLSL: pieFragmentGLSL,
+    attributes: {
+      vertex_position: SEMANTIC_POSITION,
+      aUv0: SEMANTIC_TEXCOORD0
+    }
+  });
+  material.blendType = BLEND_NORMAL;
+  material.cull = CULLFACE_NONE;
+  material.depthTest = false;
+  material.depthWrite = false;
+  material.setParameter('uProgress', 0);
+  material.setParameter('uTrackColor', [1, 1, 1]);
+  material.setParameter('uTrackAlpha', 0.18);
+  material.setParameter('uWedgeColor', [64 / 255, 200 / 255, 1]);
+  material.setParameter('uWedgeAlpha', 0.85);
+  material.setParameter('uDiscColor', discColor);
+  material.setParameter('uDiscAlpha', discAlpha);
+  material.setParameter('uGlyphColor', [1, 1, 1]);
+  material.setParameter('uOpacity', 1);
+  material.setParameter('uMaskMap', maskMap);
+  material.update();
+  return material;
 };
+
 export { createProgressPieMaterial, emptyMaskTexture, progressPieQuadMesh };

package/components/VirtualWalkthrough/xr-progress-pie.js

@@ -1,2 +1,11 @@
-const pieShaderProgress = (progress)=>progress > 0 && progress < 1 ? progress : 0;
+/**
+ * Progress to hand the pie shader, where 0 draws nothing at all: an untouched target wears no faint
+ * track, and a completed one has already opened its annotation or ended the session.
+ *
+ * Visibility rides on this value so the quad can stay enabled for the whole session. A mesh
+ * instance compiles its shader variant the first time it is drawn, and that compile has to land
+ * somewhere other than the frame a pie first appears.
+ */
+const pieShaderProgress = progress => progress > 0 && progress < 1 ? progress : 0;
+
 export { pieShaderProgress };

package/components/VirtualWalkthrough/xr-ray-quad.js

@@ -1,18 +1,32 @@
-import { Vec3 } from "playcanvas";
-const rayQuadHit = (origin, direction, center, right, up, halfWidth, halfHeight)=>{
-    const dir = direction.clone().normalize();
-    const normal = new Vec3().cross(right, up);
-    const denom = dir.dot(normal);
-    if (Math.abs(denom) < 1e-6) return null;
-    const t = new Vec3().sub2(center, origin).dot(normal) / denom;
-    if (t < 0) return null;
-    const offset = new Vec3().copy(dir).mulScalar(t).add(origin).sub(center);
-    const u = offset.dot(right) / halfWidth;
-    const v = offset.dot(up) / halfHeight;
-    if (u < -1 || u > 1 || v < -1 || v > 1) return null;
-    return {
-        u,
-        v
-    };
+import { Vec3 } from 'playcanvas';
+
+/**
+ * Intersects the ray with the rectangle centred at `center` and spanned by unit axes `right`/`up`,
+ * returning the hit in normalized quad coordinates (u,v in [-1,1]) or null. `u`/`v` divide the
+ * in-plane offset by `halfWidth`/`halfHeight`. Null when the ray is parallel to the plane, the
+ * plane is behind the origin, or the hit lands outside the rectangle.
+ */
+const rayQuadHit = (origin, direction, center, right, up, halfWidth, halfHeight) => {
+  const dir = direction.clone().normalize();
+  const normal = new Vec3().cross(right, up);
+  const denom = dir.dot(normal);
+  if (Math.abs(denom) < 1e-6) {
+    return null;
+  }
+  const t = new Vec3().sub2(center, origin).dot(normal) / denom;
+  if (t < 0) {
+    return null;
+  }
+  const offset = new Vec3().copy(dir).mulScalar(t).add(origin).sub(center);
+  const u = offset.dot(right) / halfWidth;
+  const v = offset.dot(up) / halfHeight;
+  if (u < -1 || u > 1 || v < -1 || v > 1) {
+    return null;
+  }
+  return {
+    u,
+    v
+  };
 };
+
 export { rayQuadHit };