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

package/components/VirtualWalkthrough/xr-face-buttons.d.ts

@@ -0,0 +1,15 @@
+import { XrInputSource } from 'playcanvas';
+/** True while either face button is held. False for hand-tracked sources, which have no gamepad. */
+export declare const faceButtonPressed: (inputSource: XrInputSource) => boolean;
+/** True while B or Y is held, regardless of which hand holds the controller. */
+export declare const secondaryFaceButtonPressed: (inputSource: XrInputSource) => boolean;
+/**
+ * Edge-detects face-button presses per input source so one press fires once. Callers must poll every
+ * frame for every source they care about; a press and release between polls is missed.
+ */
+export declare class FaceButtonPressTracker {
+    private _down;
+    /** True only on the poll where a face button goes from released to pressed. */
+    justPressed(inputSource: XrInputSource): boolean;
+}
+//# sourceMappingURL=xr-face-buttons.d.ts.map

package/components/VirtualWalkthrough/xr-face-buttons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-face-buttons.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-face-buttons.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAc3C,oGAAoG;AACpG,eAAO,MAAM,iBAAiB,GAAI,aAAa,aAAa,KAAG,OACX,CAAC;AAErD,gFAAgF;AAChF,eAAO,MAAM,0BAA0B,GAAI,aAAa,aAAa,KAAG,OACV,CAAC;AAE/D;;;GAGG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,KAAK,CAAyC;IAEtD,+EAA+E;IAC/E,WAAW,CAAC,WAAW,EAAE,aAAa,GAAG,OAAO;CAOjD"}

package/components/VirtualWalkthrough/xr-face-buttons.js

@@ -0,0 +1,31 @@
+/** xr-standard gamepad button indices for the face buttons: A/X (4) and B/Y (5). */
+const FACE_BUTTON_INDICES = [4, 5];
+
+/** xr-standard gamepad button indices for the secondary face button: B on the right hand, Y on the left. */
+const SECONDARY_FACE_BUTTON_INDICES = [5];
+const anyButtonPressed = (inputSource, indices) => {
+  const buttons = inputSource.gamepad?.buttons;
+  return buttons ? indices.some(index => buttons[index]?.pressed === true) : false;
+};
+
+/** True while either face button is held. False for hand-tracked sources, which have no gamepad. */
+export const faceButtonPressed = inputSource => anyButtonPressed(inputSource, FACE_BUTTON_INDICES);
+
+/** True while B or Y is held, regardless of which hand holds the controller. */
+export const secondaryFaceButtonPressed = inputSource => anyButtonPressed(inputSource, SECONDARY_FACE_BUTTON_INDICES);
+
+/**
+ * Edge-detects face-button presses per input source so one press fires once. Callers must poll every
+ * frame for every source they care about; a press and release between polls is missed.
+ */
+export class FaceButtonPressTracker {
+  _down = new WeakMap();
+
+  /** True only on the poll where a face button goes from released to pressed. */
+  justPressed(inputSource) {
+    const pressed = faceButtonPressed(inputSource);
+    const wasPressed = this._down.get(inputSource) ?? false;
+    this._down.set(inputSource, pressed);
+    return pressed && !wasPressed;
+  }
+}

package/components/VirtualWalkthrough/xr-face-buttons.test.js

@@ -0,0 +1,82 @@
+import { FaceButtonPressTracker, faceButtonPressed, secondaryFaceButtonPressed } from './xr-face-buttons';
+
+/** Fake input source whose gamepad reports `pressedIndices` as held. */
+const source = (pressedIndices, buttonCount = 6) => ({
+  gamepad: {
+    buttons: Array.from({
+      length: buttonCount
+    }, (_, index) => ({
+      pressed: pressedIndices.includes(index)
+    }))
+  }
+});
+const handTrackedSource = () => ({});
+describe('faceButtonPressed', () => {
+  it('is false for an input source with no gamepad', () => {
+    expect(faceButtonPressed(handTrackedSource())).toBe(false);
+  });
+  it('is false when the gamepad has fewer buttons than the face buttons', () => {
+    expect(faceButtonPressed(source([0], 2))).toBe(false);
+  });
+  it('is true when A/X is pressed', () => {
+    expect(faceButtonPressed(source([4]))).toBe(true);
+  });
+  it('is true when B/Y is pressed', () => {
+    expect(faceButtonPressed(source([5]))).toBe(true);
+  });
+  it('is false when only the trigger and grip are pressed', () => {
+    expect(faceButtonPressed(source([0, 1]))).toBe(false);
+  });
+  it('is false when nothing is pressed', () => {
+    expect(faceButtonPressed(source([]))).toBe(false);
+  });
+});
+describe('secondaryFaceButtonPressed', () => {
+  it('is true when B/Y is pressed', () => {
+    expect(secondaryFaceButtonPressed(source([5]))).toBe(true);
+  });
+  it('is false when only A/X is pressed', () => {
+    expect(secondaryFaceButtonPressed(source([4]))).toBe(false);
+  });
+  it('is false for an input source with no gamepad', () => {
+    expect(secondaryFaceButtonPressed(handTrackedSource())).toBe(false);
+  });
+  it('is false when the gamepad has fewer buttons than the face buttons', () => {
+    expect(secondaryFaceButtonPressed(source([0], 2))).toBe(false);
+  });
+});
+describe('FaceButtonPressTracker', () => {
+  it('fires once for a held press and re-arms after release', () => {
+    const tracker = new FaceButtonPressTracker();
+    // One persistent source whose button state mutates, as a real XrInputSource does across frames.
+    const buttons = Array.from({
+      length: 6
+    }, () => ({
+      pressed: false
+    }));
+    const controller = {
+      gamepad: {
+        buttons
+      }
+    };
+    const holdFaceButton = pressed => {
+      buttons[4].pressed = pressed;
+    };
+    expect(tracker.justPressed(controller)).toBe(false);
+    holdFaceButton(true);
+    expect(tracker.justPressed(controller)).toBe(true);
+    expect(tracker.justPressed(controller)).toBe(false);
+    holdFaceButton(false);
+    expect(tracker.justPressed(controller)).toBe(false);
+    holdFaceButton(true);
+    expect(tracker.justPressed(controller)).toBe(true);
+  });
+  it('tracks each input source independently', () => {
+    const tracker = new FaceButtonPressTracker();
+    const left = source([4]);
+    const right = source([]);
+    expect(tracker.justPressed(left)).toBe(true);
+    expect(tracker.justPressed(right)).toBe(false);
+    expect(tracker.justPressed(left)).toBe(false);
+  });
+});

package/components/VirtualWalkthrough/xr-gaze-dwell-state.d.ts

@@ -0,0 +1,17 @@
+export interface DwellState {
+    targetIndex: number | null;
+    elapsed: number;
+}
+export interface DwellUpdate {
+    state: DwellState;
+    progress: number;
+    justOpened: boolean;
+}
+export declare const INITIAL_DWELL_STATE: DwellState;
+/**
+ * Advances gaze-dwell timing for one frame. `target` is the annotation index currently under the
+ * gaze ray, or null. Dwell time accumulates while the same target is held and resets when it
+ * changes or is lost. `justOpened` is true only on the frame the dwell first reaches `threshold`.
+ */
+export declare const advanceDwell: (prev: DwellState, target: number | null, dt: number, threshold: number) => DwellUpdate;
+//# sourceMappingURL=xr-gaze-dwell-state.d.ts.map

package/components/VirtualWalkthrough/xr-gaze-dwell-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-gaze-dwell-state.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-gaze-dwell-state.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,eAAO,MAAM,mBAAmB,EAAE,UAA8C,CAAC;AAEjF;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,UAAU,EAAE,QAAQ,MAAM,GAAG,IAAI,EAAE,IAAI,MAAM,EAAE,WAAW,MAAM,KAAG,WAYrG,CAAC"}

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

@@ -0,0 +1,39 @@
+export const INITIAL_DWELL_STATE = {
+  targetIndex: null,
+  elapsed: 0
+};
+
+/**
+ * Advances gaze-dwell timing for one frame. `target` is the annotation index currently under the
+ * gaze ray, or null. Dwell time accumulates while the same target is held and resets when it
+ * changes or is lost. `justOpened` is true only on the frame the dwell first reaches `threshold`.
+ */
+export const advanceDwell = (prev, target, dt, threshold) => {
+  if (target === null) {
+    return {
+      state: INITIAL_DWELL_STATE,
+      progress: 0,
+      justOpened: false
+    };
+  }
+  if (target !== prev.targetIndex) {
+    return {
+      state: {
+        targetIndex: target,
+        elapsed: 0
+      },
+      progress: 0,
+      justOpened: false
+    };
+  }
+  const elapsed = Math.min(prev.elapsed + dt, threshold);
+  const justOpened = prev.elapsed < threshold && elapsed >= threshold;
+  return {
+    state: {
+      targetIndex: target,
+      elapsed
+    },
+    progress: elapsed / threshold,
+    justOpened
+  };
+};

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

@@ -0,0 +1,61 @@
+import { INITIAL_DWELL_STATE, advanceDwell } from './xr-gaze-dwell-state';
+const THRESHOLD = 1.5;
+describe('advanceDwell', () => {
+  it('stays reset when there is no gaze target', () => {
+    const r = advanceDwell({
+      targetIndex: 2,
+      elapsed: 1.0
+    }, null, 0.1, THRESHOLD);
+    expect(r.state).toEqual(INITIAL_DWELL_STATE);
+    expect(r.progress).toBe(0);
+    expect(r.justOpened).toBe(false);
+  });
+  it('resets to zero when the target changes', () => {
+    const r = advanceDwell({
+      targetIndex: 0,
+      elapsed: 1.0
+    }, 1, 0.1, THRESHOLD);
+    expect(r.state).toEqual({
+      targetIndex: 1,
+      elapsed: 0
+    });
+    expect(r.progress).toBe(0);
+    expect(r.justOpened).toBe(false);
+  });
+  it('accumulates dwell time while the same target is held', () => {
+    const r = advanceDwell({
+      targetIndex: 3,
+      elapsed: 0.5
+    }, 3, 0.25, THRESHOLD);
+    expect(r.state).toEqual({
+      targetIndex: 3,
+      elapsed: 0.75
+    });
+    expect(r.progress).toBeCloseTo(0.5, 5);
+    expect(r.justOpened).toBe(false);
+  });
+  it('fires justOpened once when crossing the threshold and clamps elapsed', () => {
+    const r = advanceDwell({
+      targetIndex: 3,
+      elapsed: 1.4
+    }, 3, 0.5, THRESHOLD);
+    expect(r.justOpened).toBe(true);
+    expect(r.progress).toBe(1);
+    expect(r.state).toEqual({
+      targetIndex: 3,
+      elapsed: THRESHOLD
+    });
+  });
+  it('does not re-fire while the target stays held past the threshold', () => {
+    const r = advanceDwell({
+      targetIndex: 3,
+      elapsed: THRESHOLD
+    }, 3, 0.5, THRESHOLD);
+    expect(r.justOpened).toBe(false);
+    expect(r.progress).toBe(1);
+    expect(r.state).toEqual({
+      targetIndex: 3,
+      elapsed: THRESHOLD
+    });
+  });
+});

package/components/VirtualWalkthrough/xr-gaze-dwell.d.ts

@@ -0,0 +1,30 @@
+import { Script } from 'playcanvas';
+export declare class XrGazeDwell extends Script {
+    static scriptName: string;
+    /** 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: number;
+    private _dwell;
+    private _pieEntity?;
+    private _pieCanvas?;
+    private _pieTexture?;
+    private _pieMaterial?;
+    private _pieMesh?;
+    private _drawnProgress;
+    private _headPos;
+    private _headRot;
+    private _viewOffset;
+    private _forward;
+    private _scratchScale;
+    private _isVrActive;
+    initialize(): void;
+    private _createQuad;
+    /** Redraws the pie fill for the given dwell progress (0..1) onto the texture canvas. */
+    private _drawPie;
+    private _trackHead;
+    update(dt: number): void;
+    private _showPie;
+    private _hidePie;
+    destroy(): void;
+}
+//# sourceMappingURL=xr-gaze-dwell.d.ts.map

package/components/VirtualWalkthrough/xr-gaze-dwell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-gaze-dwell.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-gaze-dwell.ts"],"names":[],"mappings":"AAAA,OAAO,EAWL,MAAM,EAKP,MAAM,YAAY,CAAC;AAqBpB,qBAAa,WAAY,SAAQ,MAAM;IACrC,MAAM,CAAC,UAAU,SAAiB;IAElC;6FACyF;IACzF,WAAW,SAAM;IAEjB,OAAO,CAAC,MAAM,CAAmC;IAEjD,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAC,CAAoB;IACvC,OAAO,CAAC,WAAW,CAAC,CAAU;IAC9B,OAAO,CAAC,YAAY,CAAC,CAAmB;IACxC,OAAO,CAAC,QAAQ,CAAC,CAAO;IACxB,OAAO,CAAC,cAAc,CAAM;IAE5B,OAAO,CAAC,QAAQ,CAAc;IAC9B,OAAO,CAAC,QAAQ,CAAc;IAC9B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,QAAQ,CAAc;IAC9B,OAAO,CAAC,aAAa,CAAc;IAEnC,OAAO,CAAC,WAAW,CAAyE;IAE5F,UAAU;IAuCV,OAAO,CAAC,WAAW;IAYnB,wFAAwF;IACxF,OAAO,CAAC,QAAQ;IAWhB,OAAO,CAAC,UAAU;IAgBlB,MAAM,CAAC,EAAE,EAAE,MAAM;IAmCjB,OAAO,CAAC,QAAQ;IAmBhB,OAAO,CAAC,QAAQ;IAOhB,OAAO;CAeR"}

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

@@ -0,0 +1,173 @@
+import { ADDRESS_CLAMP_TO_EDGE, BLEND_NORMAL, CULLFACE_NONE, Color, Entity, FILTER_LINEAR, LAYERID_IMMEDIATE, Mesh, MeshInstance, Quat, Script, StandardMaterial, Texture, Vec3, XRTYPE_VR } from 'playcanvas';
+import { HOTSPOT_HALF_EXTENT, collectAnnotationHitCandidates } from './xr-annotation-candidates';
+import { nearestAnnotationHit } from './xr-annotation-targeting';
+import { INITIAL_DWELL_STATE, advanceDwell } from './xr-gaze-dwell-state';
+import { drawProgressPie } from './xr-progress-pie';
+
+/** 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;
+
+/** Progress-pie texture resolution. */
+const PIE_TEXTURE_SIZE = 128;
+const LOCAL_FORWARD = new Vec3(0, 0, -1);
+export class XrGazeDwell extends Script {
+  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;
+  _drawnProgress = -1;
+  _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;
+  initialize() {
+    this._pieCanvas = document.createElement('canvas');
+    this._pieCanvas.width = PIE_TEXTURE_SIZE;
+    this._pieCanvas.height = PIE_TEXTURE_SIZE;
+    this._pieTexture = new Texture(this.app.graphicsDevice, {
+      name: 'xr-gaze-dwell-pie',
+      width: PIE_TEXTURE_SIZE,
+      height: PIE_TEXTURE_SIZE,
+      addressU: ADDRESS_CLAMP_TO_EDGE,
+      addressV: ADDRESS_CLAMP_TO_EDGE,
+      minFilter: FILTER_LINEAR,
+      magFilter: FILTER_LINEAR,
+      mipmaps: true
+    });
+    this._pieTexture.setSource(this._pieCanvas);
+    const material = new StandardMaterial();
+    material.useLighting = false;
+    material.emissive = new Color(1, 1, 1);
+    material.emissiveMap = this._pieTexture;
+    material.opacityMap = this._pieTexture;
+    material.opacityMapChannel = 'a';
+    material.blendType = BLEND_NORMAL;
+    material.depthTest = false;
+    material.depthWrite = false;
+    material.cull = CULLFACE_NONE;
+    material.update();
+    this._pieMaterial = material;
+    this._pieMesh = this._createQuad();
+    const meshInstance = new MeshInstance(this._pieMesh, material);
+    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);
+  }
+  _createQuad() {
+    const h = HOTSPOT_HALF_EXTENT;
+    const mesh = new Mesh(this.app.graphicsDevice);
+    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;
+  }
+
+  /** Redraws the pie fill for the given dwell progress (0..1) onto the texture canvas. */
+  _drawPie(progress) {
+    const ctx = this._pieCanvas?.getContext('2d');
+    if (!ctx) {
+      return;
+    }
+    ctx.clearRect(0, 0, PIE_TEXTURE_SIZE, PIE_TEXTURE_SIZE);
+    drawProgressPie(ctx, PIE_TEXTURE_SIZE, progress);
+    this._pieTexture?.upload();
+  }
+  _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;
+  }
+  update(dt) {
+    if (!this._pieEntity) {
+      return;
+    }
+    if (!this._isVrActive() || !this._trackHead()) {
+      this._dwell = INITIAL_DWELL_STATE;
+      this._hidePie();
+      return;
+    }
+    const activeName = `annotation-${this.activeIndex}`;
+    const candidates = collectAnnotationHitCandidates(this.app, GAZE_HIT_RADIUS_PAD).filter(candidate => candidate.entity.name !== activeName);
+    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;
+    if (target !== null && result.progress > 0 && result.progress < 1) {
+      this._showPie(candidates[target].entity, result.progress);
+    } else {
+      this._hidePie();
+    }
+    if (result.justOpened && target !== null) {
+      const {
+        entity,
+        script
+      } = candidates[target];
+      const camera = this.app.root.findByName('camera');
+      const screen = camera?.camera?.worldToScreen(entity.getPosition());
+      script.onVrOpenCallback(screen?.x ?? 0, screen?.y ?? 0);
+    }
+  }
+  _showPie(entity, progress) {
+    if (!this._pieEntity) {
+      return;
+    }
+    if (Math.abs(progress - this._drawnProgress) > 0.001) {
+      this._drawnProgress = progress;
+      this._drawPie(progress);
+    }
+
+    // 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.enabled = true;
+    this._pieEntity.setLocalScale(scale, scale, scale);
+    this._pieEntity.setPosition(entity.getPosition());
+    this._pieEntity.setRotation(this._headRot);
+  }
+  _hidePie() {
+    if (this._pieEntity && this._pieEntity.enabled) {
+      this._pieEntity.enabled = false;
+      this._drawnProgress = -1;
+    }
+  }
+  destroy() {
+    if (this._pieEntity) {
+      if (this._pieEntity.render) {
+        this._pieEntity.render.meshInstances = [];
+      }
+      this._pieEntity.destroy();
+      this._pieEntity = undefined;
+    }
+    this._pieMesh?.destroy();
+    this._pieMaterial?.destroy();
+    this._pieTexture?.destroy();
+    this._pieMesh = undefined;
+    this._pieMaterial = undefined;
+    this._pieTexture = undefined;
+  }
+}

package/components/VirtualWalkthrough/xr-interactive-ui.d.ts

@@ -0,0 +1,13 @@
+import { Vec3 } from 'playcanvas';
+/** True when the ray points at an openable annotation hotspot. */
+export declare const rayHitsAnnotationHotspot: (app: any, origin: Vec3, direction: Vec3) => boolean;
+/** True when the ray points at the open VR annotation panel. False when no panel is mounted. */
+export declare const rayHitsAnnotationPanel: (app: any, origin: Vec3, direction: Vec3) => boolean;
+/** True when the ray points at the VR exit button. */
+export declare const rayHitsExitButton: (app: any, origin: Vec3, direction: Vec3) => boolean;
+/**
+ * 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.
+ */
+export declare const rayHitsInteractiveUi: (app: any, origin: Vec3, direction: Vec3) => boolean;
+//# sourceMappingURL=xr-interactive-ui.d.ts.map

package/components/VirtualWalkthrough/xr-interactive-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-interactive-ui.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-interactive-ui.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAOlC,kEAAkE;AAClE,eAAO,MAAM,wBAAwB,GAAI,KAAK,GAAG,EAAE,QAAQ,IAAI,EAAE,WAAW,IAAI,KAAG,OACoB,CAAC;AAExG,gGAAgG;AAChG,eAAO,MAAM,sBAAsB,GAAI,KAAK,GAAG,EAAE,QAAQ,IAAI,EAAE,WAAW,IAAI,KAAG,OAIhF,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,iBAAiB,GAAI,KAAK,GAAG,EAAE,QAAQ,IAAI,EAAE,WAAW,IAAI,KAAG,OAI3E,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,GAAG,EAAE,QAAQ,IAAI,EAAE,WAAW,IAAI,KAAG,OAGpC,CAAC"}

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

@@ -0,0 +1,25 @@
+import { VrAnnotationPanel } from './vr-annotation-panel';
+import { HIT_RADIUS_PAD, collectAnnotationHitCandidates } from './xr-annotation-candidates';
+import { nearestAnnotationHit } from './xr-annotation-targeting';
+import { XrExitButton } from './xr-exit-button';
+
+/** True when the ray points at an openable annotation hotspot. */
+export 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. */
+export 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;
+};
+
+/** True when the ray points at the VR exit button. */
+export 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;
+};
+
+/**
+ * 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.
+ */
+export const rayHitsInteractiveUi = (app, origin, direction) => rayHitsAnnotationHotspot(app, origin, direction) || rayHitsAnnotationPanel(app, origin, direction) || rayHitsExitButton(app, origin, direction);

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

@@ -0,0 +1,165 @@
+import { Vec3 } from 'playcanvas';
+import { VrAnnotationPanel } from './vr-annotation-panel';
+import { XrExitButton } from './xr-exit-button';
+import { rayHitsAnnotationHotspot, rayHitsAnnotationPanel, rayHitsExitButton, rayHitsInteractiveUi } from './xr-interactive-ui';
+
+// Jest cannot parse the PlayCanvas ESM scripts that xr-annotation-candidates imports.
+jest.mock('playcanvas/scripts/esm/annotations.mjs', () => ({
+  Annotation: {
+    scriptName: 'annotation'
+  }
+}));
+const ORIGIN = new Vec3(0, 0, 5);
+const FORWARD = new Vec3(0, 0, -1);
+
+/** Fake annotation hotspot entity: unit quad at `position`, scale 1, with the stock open callback. */
+const hotspot = position => ({
+  getPosition: () => position,
+  getWorldTransform: () => ({
+    getScale: out => out.set(1, 1, 1)
+  }),
+  script: {
+    get: () => ({
+      onVrOpenCallback: () => undefined
+    })
+  }
+});
+/**
+ * Fake app whose `findByName` serves only the entities the helpers look up. Each script stub returns
+ * its fake only for the matching `scriptName`, so a lookup by the wrong name misses - the way a real
+ * `Script#get` would - instead of silently succeeding.
+ */
+const fakeApp = ({
+  hotspots,
+  panelHit,
+  panelHasScript = true,
+  exitHit
+}) => ({
+  root: {
+    findByName: name => {
+      if (name === 'annotations-root') {
+        return hotspots ? {
+          children: hotspots
+        } : null;
+      }
+      if (name === 'vr-annotation-panel') {
+        if (panelHit === undefined) {
+          return null;
+        }
+        return {
+          script: {
+            get: scriptName => scriptName === VrAnnotationPanel.scriptName ? panelHasScript ? {
+              rayHitsPanel: () => panelHit
+            } : {} : undefined
+          }
+        };
+      }
+      if (name === 'xr-exit-button') {
+        return exitHit === undefined ? null : {
+          script: {
+            get: scriptName => scriptName === XrExitButton.scriptName ? {
+              rayHitsButton: () => exitHit
+            } : undefined
+          }
+        };
+      }
+      return null;
+    }
+  }
+});
+describe('rayHitsAnnotationHotspot', () => {
+  it('is true when the ray enters a hotspot sphere', () => {
+    const app = fakeApp({
+      hotspots: [hotspot(new Vec3(0, 0, 0))]
+    });
+    expect(rayHitsAnnotationHotspot(app, ORIGIN, FORWARD)).toBe(true);
+  });
+  it('is false when the ray misses every hotspot', () => {
+    const app = fakeApp({
+      hotspots: [hotspot(new Vec3(0, 8, 0))]
+    });
+    expect(rayHitsAnnotationHotspot(app, ORIGIN, FORWARD)).toBe(false);
+  });
+  it('is false when there is no annotations root', () => {
+    expect(rayHitsAnnotationHotspot(fakeApp({}), ORIGIN, FORWARD)).toBe(false);
+  });
+
+  // Pins the derived radius (HOTSPOT_HALF_EXTENT 0.5 * scale 1 * HIT_RADIUS_PAD 2.5 = 1.25) against
+  // drift: a hotspot at (0,0,0) or (0,8,0) would pass the two tests above for nearly any radius.
+  it('is true just inside the derived hit radius', () => {
+    const app = fakeApp({
+      hotspots: [hotspot(new Vec3(0, 1.2, 0))]
+    });
+    expect(rayHitsAnnotationHotspot(app, ORIGIN, FORWARD)).toBe(true);
+  });
+  it('is false just outside the derived hit radius', () => {
+    const app = fakeApp({
+      hotspots: [hotspot(new Vec3(0, 1.3, 0))]
+    });
+    expect(rayHitsAnnotationHotspot(app, ORIGIN, FORWARD)).toBe(false);
+  });
+});
+describe('rayHitsAnnotationPanel', () => {
+  it('delegates to the panel script', () => {
+    expect(rayHitsAnnotationPanel(fakeApp({
+      panelHit: true
+    }), ORIGIN, FORWARD)).toBe(true);
+    expect(rayHitsAnnotationPanel(fakeApp({
+      panelHit: false
+    }), ORIGIN, FORWARD)).toBe(false);
+  });
+  it('is false when no panel is mounted', () => {
+    expect(rayHitsAnnotationPanel(fakeApp({}), ORIGIN, FORWARD)).toBe(false);
+  });
+  it('is false when the panel entity has no hit-test method', () => {
+    const app = fakeApp({
+      panelHit: true,
+      panelHasScript: false
+    });
+    expect(rayHitsAnnotationPanel(app, ORIGIN, FORWARD)).toBe(false);
+  });
+});
+describe('rayHitsExitButton', () => {
+  it('delegates to the exit button script', () => {
+    expect(rayHitsExitButton(fakeApp({
+      exitHit: true
+    }), ORIGIN, FORWARD)).toBe(true);
+    expect(rayHitsExitButton(fakeApp({
+      exitHit: false
+    }), ORIGIN, FORWARD)).toBe(false);
+  });
+  it('is false when no exit button is mounted', () => {
+    expect(rayHitsExitButton(fakeApp({}), ORIGIN, FORWARD)).toBe(false);
+  });
+});
+describe('rayHitsInteractiveUi', () => {
+  it('is false when the ray hits nothing interactive', () => {
+    const app = fakeApp({
+      hotspots: [hotspot(new Vec3(0, 8, 0))],
+      panelHit: false,
+      exitHit: false
+    });
+    expect(rayHitsInteractiveUi(app, ORIGIN, FORWARD)).toBe(false);
+  });
+  it('is true for a hotspot hit', () => {
+    const app = fakeApp({
+      hotspots: [hotspot(new Vec3(0, 0, 0))],
+      panelHit: false,
+      exitHit: false
+    });
+    expect(rayHitsInteractiveUi(app, ORIGIN, FORWARD)).toBe(true);
+  });
+  it('is true for a panel hit', () => {
+    expect(rayHitsInteractiveUi(fakeApp({
+      panelHit: true
+    }), ORIGIN, FORWARD)).toBe(true);
+  });
+  it('is true for an exit button hit', () => {
+    expect(rayHitsInteractiveUi(fakeApp({
+      exitHit: true
+    }), ORIGIN, FORWARD)).toBe(true);
+  });
+  it('is false in an empty scene', () => {
+    expect(rayHitsInteractiveUi(fakeApp({}), ORIGIN, FORWARD)).toBe(false);
+  });
+});