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

package/components/VirtualWalkthrough/xr-annotation-candidate-buffer.js

@@ -1,47 +1,88 @@
-import { Vec3 } from "playcanvas";
+import { Vec3 } from 'playcanvas';
+
+/** Local half-extent of the unit-plane hotspot quad. */
 const HOTSPOT_HALF_EXTENT = 0.5;
+
+/** Pulls the stock annotation script off a hotspot entity, or undefined if it carries none. */
+
 const scratchScale = new Vec3();
-const isInScene = (node, sceneRoot)=>{
-    for(let current = node; current; current = current.parent)if (current === sceneRoot) return true;
-    return false;
+
+/**
+ * Whether `node` still hangs beneath `sceneRoot`. An entity that has been removed from the scene
+ * keeps its own `children` array - a destroyed one keeps it as an empty array - so only a walk back
+ * up the parent chain tells a live root apart from a detached one.
+ */
+const isInScene = (node, sceneRoot) => {
+  for (let current = node; current; current = current.parent) {
+    if (current === sceneRoot) {
+      return true;
+    }
+  }
+  return false;
 };
+
+/**
+ * Collects world-space hit candidates for the openable annotation hotspots into a buffer it owns and
+ * reuses, so a caller running every frame allocates nothing. The returned array and the candidate
+ * objects inside it are overwritten by the next `collect`, which is why each caller holds its own
+ * buffer rather than sharing one.
+ *
+ * Positions and radii are re-read on every call, so hotspots that move or resize stay targetable.
+ * That read is cheap; it is the allocation around it that a per-frame caller cannot afford.
+ */
 class AnnotationCandidateBuffer {
-    _getScript;
-    _candidates = [];
-    _root = null;
-    constructor(_getScript){
-        this._getScript = _getScript;
+  _candidates = [];
+  _root = null;
+  constructor(_getScript) {
+    this._getScript = _getScript;
+  }
+
+  /**
+   * Hit candidates for every openable hotspot except `excludeName`, with hit spheres derived from
+   * each hotspot's rendered world size and padded by `radiusPad` for easier aiming.
+   */
+  collect(app, radiusPad, excludeName) {
+    // The root is looked up by a walk of the whole scene graph, so it is held onto between frames.
+    // It is re-resolved whenever it leaves the scene: annotations mount after the scene does, and
+    // the root is torn down and built afresh every time the annotation list empties and refills.
+    if (!isInScene(this._root, app.root)) {
+      this._root = app.root.findByName('annotations-root');
+    }
+    const children = this._root?.children;
+    if (!children) {
+      this._candidates.length = 0;
+      return this._candidates;
     }
-    collect(app, radiusPad, excludeName) {
-        if (!isInScene(this._root, app.root)) this._root = app.root.findByName('annotations-root');
-        const children = this._root?.children;
-        if (!children) {
-            this._candidates.length = 0;
-            return this._candidates;
-        }
-        let count = 0;
-        for (const entity of children){
-            if (void 0 !== excludeName && entity.name === excludeName) continue;
-            const script = this._getScript(entity);
-            if (!script || false === script.enabled || 'function' != typeof script.onVrOpenCallback) continue;
-            entity.getWorldTransform().getScale(scratchScale);
-            const radius = HOTSPOT_HALF_EXTENT * scratchScale.x * radiusPad;
-            const existing = this._candidates[count];
-            if (existing) {
-                existing.entity = entity;
-                existing.script = script;
-                existing.position = entity.getPosition();
-                existing.radius = radius;
-            } else this._candidates.push({
-                entity,
-                script,
-                position: entity.getPosition(),
-                radius
-            });
-            count++;
-        }
-        this._candidates.length = count;
-        return this._candidates;
+    let count = 0;
+    for (const entity of children) {
+      if (excludeName !== undefined && entity.name === excludeName) {
+        continue;
+      }
+      const script = this._getScript(entity);
+      if (!script || script.enabled === false || typeof script.onVrOpenCallback !== 'function') {
+        continue;
+      }
+      entity.getWorldTransform().getScale(scratchScale);
+      const radius = HOTSPOT_HALF_EXTENT * scratchScale.x * radiusPad;
+      const existing = this._candidates[count];
+      if (existing) {
+        existing.entity = entity;
+        existing.script = script;
+        existing.position = entity.getPosition();
+        existing.radius = radius;
+      } else {
+        this._candidates.push({
+          entity,
+          script,
+          position: entity.getPosition(),
+          radius
+        });
+      }
+      count++;
     }
+    this._candidates.length = count;
+    return this._candidates;
+  }
 }
+
 export { AnnotationCandidateBuffer, HOTSPOT_HALF_EXTENT };

package/components/VirtualWalkthrough/xr-annotation-candidates.js

@@ -1,7 +1,19 @@
-import { Annotation } from "playcanvas/scripts/esm/annotations.mjs";
-import { AnnotationCandidateBuffer, HOTSPOT_HALF_EXTENT } from "./xr-annotation-candidate-buffer.js";
+import { Annotation } from 'playcanvas/scripts/esm/annotations.mjs';
+import { AnnotationCandidateBuffer } from './xr-annotation-candidate-buffer.js';
+export { HOTSPOT_HALF_EXTENT } from './xr-annotation-candidate-buffer.js';
+
+/** Multiplier on the hotspot's world radius to make controller targeting forgiving. */
 const HIT_RADIUS_PAD = 2.5;
-const annotationScriptOf = (entity)=>entity.script?.get(Annotation.scriptName);
-const createAnnotationCandidateBuffer = ()=>new AnnotationCandidateBuffer(annotationScriptOf);
-const collectAnnotationHitCandidates = (app, radiusPad)=>createAnnotationCandidateBuffer().collect(app, radiusPad);
-export { HIT_RADIUS_PAD, HOTSPOT_HALF_EXTENT, collectAnnotationHitCandidates, createAnnotationCandidateBuffer };
+const annotationScriptOf = entity => entity.script?.get(Annotation.scriptName);
+
+/** A buffer wired to the stock annotation script. Callers that collect every frame hold one of
+ * these; its results are overwritten on the next collect, so one buffer cannot be shared. */
+const createAnnotationCandidateBuffer = () => new AnnotationCandidateBuffer(annotationScriptOf);
+
+/**
+ * One-shot collection for callers that run on an input event rather than every frame, and so have no
+ * reason to hold a buffer of their own.
+ */
+const collectAnnotationHitCandidates = (app, radiusPad) => createAnnotationCandidateBuffer().collect(app, radiusPad);
+
+export { HIT_RADIUS_PAD, collectAnnotationHitCandidates, createAnnotationCandidateBuffer };

package/components/VirtualWalkthrough/xr-annotation-interaction.js

@@ -1,37 +1,62 @@
-import { Script, XRTYPE_VR } from "playcanvas";
-import { HIT_RADIUS_PAD, collectAnnotationHitCandidates } from "./xr-annotation-candidates.js";
-import { nearestAnnotationHit } from "./xr-annotation-targeting.js";
-import { FaceButtonPressTracker } from "./xr-face-buttons.js";
-import { rayHitsAnnotationPanel } from "./xr-interactive-ui.js";
+import { Script, XRTYPE_VR } from 'playcanvas';
+import { collectAnnotationHitCandidates, HIT_RADIUS_PAD } from './xr-annotation-candidates.js';
+import { nearestAnnotationHit } from './xr-annotation-targeting.js';
+import { FaceButtonPressTracker } from './xr-face-buttons.js';
+import { rayHitsAnnotationPanel } from './xr-interactive-ui.js';
+
 class XrAnnotationInteraction extends Script {
-    static scriptName = 'xrAnnotationInteraction';
-    onDismissCallback;
-    _faceButtons = new FaceButtonPressTracker();
-    _isVrActive = ()=>this.app.xr?.active === true && this.app.xr?.type === XRTYPE_VR;
-    _dismiss = ()=>{
-        if ('function' == typeof this.onDismissCallback) this.onDismissCallback();
-    };
-    _onSelect = (inputSource)=>{
-        if (!this._isVrActive()) return;
-        this._openAnnotationUnderRay(inputSource.getOrigin(), inputSource.getDirection());
-    };
-    _openAnnotationUnderRay(origin, direction) {
-        if (rayHitsAnnotationPanel(this.app, origin, direction)) return;
-        const candidates = collectAnnotationHitCandidates(this.app, HIT_RADIUS_PAD);
-        const index = nearestAnnotationHit(origin, direction, candidates);
-        if (null === index) return void this._dismiss();
-        const { entity, script } = candidates[index];
-        const camera = this.app.root.findComponent('camera');
-        const screen = camera?.worldToScreen(entity.getPosition());
-        script.onVrOpenCallback(screen?.x ?? 0, screen?.y ?? 0);
+  static scriptName = 'xrAnnotationInteraction';
+  _faceButtons = new FaceButtonPressTracker();
+  _isVrActive = () => this.app.xr?.active === true && this.app.xr?.type === XRTYPE_VR;
+  _dismiss = () => {
+    if (typeof this.onDismissCallback === 'function') {
+      this.onDismissCallback();
     }
-    initialize() {
-        this.app.xr?.input?.on('select', this._onSelect);
-        this.once('destroy', ()=>this.app.xr?.input?.off('select', this._onSelect));
+  };
+  _onSelect = inputSource => {
+    if (!this._isVrActive()) {
+      return;
     }
-    update() {
-        if (!this._isVrActive()) return;
-        for (const inputSource of this.app.xr?.input?.inputSources ?? [])if (this._faceButtons.justPressed(inputSource)) return void this._dismiss();
+    this._openAnnotationUnderRay(inputSource.getOrigin(), inputSource.getDirection());
+  };
+  _openAnnotationUnderRay(origin, direction) {
+    // Checked before the hotspots so aiming at the panel (e.g. its carousel arrows) neither
+    // dismisses it nor opens an annotation whose padded hit sphere sits behind it.
+    if (rayHitsAnnotationPanel(this.app, origin, direction)) {
+      return;
     }
+    const candidates = collectAnnotationHitCandidates(this.app, HIT_RADIUS_PAD);
+    const index = nearestAnnotationHit(origin, direction, candidates);
+    if (index === null) {
+      this._dismiss();
+      return;
+    }
+    const {
+      entity,
+      script
+    } = candidates[index];
+    const camera = this.app.root.findComponent('camera');
+    const screen = camera?.worldToScreen(entity.getPosition());
+    script.onVrOpenCallback(screen?.x ?? 0, screen?.y ?? 0);
+  }
+  initialize() {
+    this.app.xr?.input?.on('select', this._onSelect);
+    this.once('destroy', () => this.app.xr?.input?.off('select', this._onSelect));
+  }
+  update() {
+    if (!this._isVrActive()) {
+      return;
+    }
+
+    // A face button dismisses from any aim direction, unlike the click-out select. Harmless when
+    // nothing is open: the React close handler re-sets state it already holds.
+    for (const inputSource of this.app.xr?.input?.inputSources ?? []) {
+      if (this._faceButtons.justPressed(inputSource)) {
+        this._dismiss();
+        return;
+      }
+    }
+  }
 }
+
 export { XrAnnotationInteraction };

package/components/VirtualWalkthrough/xr-annotation-targeting.js

@@ -1,28 +1,44 @@
-import { Vec3 } from "playcanvas";
+import { Vec3 } from 'playcanvas';
+
+// Reused across calls: this runs per candidate per frame, where fresh vectors would be steady GC churn.
 const scratchDir = new Vec3();
 const scratchToCenter = new Vec3();
-const raySphereEntryDistance = (origin, dir, center, radius)=>{
-    const m = scratchToCenter.sub2(origin, center);
-    const b = m.dot(dir);
-    const c = m.dot(m) - radius * radius;
-    if (c > 0 && b > 0) return null;
-    const disc = b * b - c;
-    if (disc < 0) return null;
-    const t = -b - Math.sqrt(disc);
-    return t < 0 ? 0 : t;
+
+/**
+ * Distance along a (normalized) ray to where it first enters the sphere, or null if it never does.
+ * A ray starting inside the sphere returns 0.
+ */
+const raySphereEntryDistance = (origin, dir, center, radius) => {
+  const m = scratchToCenter.sub2(origin, center);
+  const b = m.dot(dir);
+  const c = m.dot(m) - radius * radius;
+  if (c > 0 && b > 0) {
+    return null;
+  }
+  const disc = b * b - c;
+  if (disc < 0) {
+    return null;
+  }
+  const t = -b - Math.sqrt(disc);
+  return t < 0 ? 0 : t;
 };
-const nearestAnnotationHit = (origin, direction, candidates)=>{
-    const dir = scratchDir.copy(direction).normalize();
-    let bestIndex = null;
-    let bestDistance = 1 / 0;
-    for(let index = 0; index < candidates.length; index++){
-        const candidate = candidates[index];
-        const distance = raySphereEntryDistance(origin, dir, candidate.position, candidate.radius);
-        if (null !== distance && distance < bestDistance) {
-            bestDistance = distance;
-            bestIndex = index;
-        }
+
+/**
+ * Index of the closest candidate sphere the ray enters, or null if it hits none.
+ */
+const nearestAnnotationHit = (origin, direction, candidates) => {
+  const dir = scratchDir.copy(direction).normalize();
+  let bestIndex = null;
+  let bestDistance = Infinity;
+  for (let index = 0; index < candidates.length; index++) {
+    const candidate = candidates[index];
+    const distance = raySphereEntryDistance(origin, dir, candidate.position, candidate.radius);
+    if (distance !== null && distance < bestDistance) {
+      bestDistance = distance;
+      bestIndex = index;
     }
-    return bestIndex;
+  }
+  return bestIndex;
 };
+
 export { nearestAnnotationHit };

package/components/VirtualWalkthrough/xr-button-arming.js

@@ -1,11 +1,21 @@
+/**
+ * Latches per input source whether a press may count toward a hold. A source arms itself the
+ * moment it is seen released, and stays armed from then on - so a button already down when
+ * tracking starts is ignored until it is released once, and one controller held down can't stop
+ * another from arming and counting. Callers must poll every frame for every source they care
+ * about; a press and release between polls is missed.
+ */
 class ButtonArmingLatch {
-    _armed = new WeakSet();
-    trackPress(inputSource, pressed) {
-        if (!pressed) {
-            this._armed.add(inputSource);
-            return false;
-        }
-        return this._armed.has(inputSource);
+  _armed = new WeakSet();
+
+  /** Records one frame for `inputSource` and returns whether its current press may count. */
+  trackPress(inputSource, pressed) {
+    if (!pressed) {
+      this._armed.add(inputSource);
+      return false;
     }
+    return this._armed.has(inputSource);
+  }
 }
+
 export { ButtonArmingLatch };

package/components/VirtualWalkthrough/xr-button-hold.js

@@ -1,31 +1,45 @@
 const INITIAL_HOLD_STATE = {
-    elapsed: 0,
-    armed: false
+  elapsed: 0,
+  armed: false
 };
 const RELEASED_STATE = {
-    elapsed: 0,
-    armed: true
+  elapsed: 0,
+  armed: true
 };
-const advanceHold = (prev, held, dt, threshold)=>{
-    if (!held) return {
-        state: RELEASED_STATE,
-        progress: 0,
-        justFired: false
-    };
-    if (!prev.armed) return {
-        state: prev,
-        progress: 0,
-        justFired: false
+
+/**
+ * Advances a press-and-hold timer by one frame. `held` is whether the button is down right now.
+ *
+ * A hold only counts once a release has been seen, so a button that is already down when tracking
+ * starts does nothing until the user lets go - otherwise entering a session with a thumb on the
+ * button would fire `threshold` seconds later. `justFired` is true only on the frame elapsed first
+ * reaches `threshold`, so continuing to hold fires once.
+ */
+const advanceHold = (prev, held, dt, threshold) => {
+  if (!held) {
+    return {
+      state: RELEASED_STATE,
+      progress: 0,
+      justFired: false
     };
-    const elapsed = Math.min(prev.elapsed + dt, threshold);
-    const justFired = prev.elapsed < threshold && elapsed >= threshold;
+  }
+  if (!prev.armed) {
     return {
-        state: {
-            elapsed,
-            armed: true
-        },
-        progress: elapsed / threshold,
-        justFired
+      state: prev,
+      progress: 0,
+      justFired: false
     };
+  }
+  const elapsed = Math.min(prev.elapsed + dt, threshold);
+  const justFired = prev.elapsed < threshold && elapsed >= threshold;
+  return {
+    state: {
+      elapsed,
+      armed: true
+    },
+    progress: elapsed / threshold,
+    justFired
+  };
 };
+
 export { INITIAL_HOLD_STATE, advanceHold };

package/components/VirtualWalkthrough/xr-exit-button-mask.js

@@ -1,27 +1,41 @@
+/** Backing disc radius as a fraction of the button's half-size. Matches the shader's pie radius. */
 const DISC_RADIUS = 0.92;
+
+/** Glyph arm reach and stroke width, as fractions of the drawn size. */
 const GLYPH_ARM = 0.24;
 const GLYPH_WIDTH = 0.09;
-const drawExitButtonMask = (ctx, size)=>{
-    const c = size / 2;
-    ctx.save();
-    ctx.globalCompositeOperation = 'source-over';
-    ctx.fillStyle = '#000000';
-    ctx.fillRect(0, 0, size, size);
-    ctx.globalCompositeOperation = 'lighter';
-    ctx.fillStyle = '#ff0000';
-    ctx.beginPath();
-    ctx.arc(c, c, c * DISC_RADIUS, 0, 2 * Math.PI);
-    ctx.fill();
-    const arm = size * GLYPH_ARM;
-    ctx.strokeStyle = '#00ff00';
-    ctx.lineWidth = size * GLYPH_WIDTH;
-    ctx.lineCap = 'round';
-    ctx.beginPath();
-    ctx.moveTo(c - arm, c - arm);
-    ctx.lineTo(c + arm, c + arm);
-    ctx.moveTo(c + arm, c - arm);
-    ctx.lineTo(c - arm, c + arm);
-    ctx.stroke();
-    ctx.restore();
+
+/**
+ * Bakes the exit button's static artwork into a two-channel mask: red covers the backing disc, green
+ * the X glyph. The shader composites the progress sweep between the two, which is what keeps the
+ * glyph legible over the fill.
+ *
+ * The channels have to stay independent, so the glyph is drawn additively rather than over the disc,
+ * and an opaque base goes down first. Uniform full alpha means the mask survives the texture upload
+ * whether or not alpha ends up premultiplied, and antialiased edges keep their coverage.
+ */
+const drawExitButtonMask = (ctx, size) => {
+  const c = size / 2;
+  ctx.save();
+  ctx.globalCompositeOperation = 'source-over';
+  ctx.fillStyle = '#000000';
+  ctx.fillRect(0, 0, size, size);
+  ctx.globalCompositeOperation = 'lighter';
+  ctx.fillStyle = '#ff0000';
+  ctx.beginPath();
+  ctx.arc(c, c, c * DISC_RADIUS, 0, Math.PI * 2);
+  ctx.fill();
+  const arm = size * GLYPH_ARM;
+  ctx.strokeStyle = '#00ff00';
+  ctx.lineWidth = size * GLYPH_WIDTH;
+  ctx.lineCap = 'round';
+  ctx.beginPath();
+  ctx.moveTo(c - arm, c - arm);
+  ctx.lineTo(c + arm, c + arm);
+  ctx.moveTo(c + arm, c - arm);
+  ctx.lineTo(c - arm, c + arm);
+  ctx.stroke();
+  ctx.restore();
 };
+
 export { drawExitButtonMask };