@terraware/web-components 4.2.21 → 4.2.22

package/components/VirtualWalkthrough/vr-annotation-panel.d.ts

@@ -0,0 +1,40 @@
+import { Script, Vec3 } from 'playcanvas';
+export declare class VrAnnotationPanel extends Script {
+    static scriptName: string;
+    title: string;
+    label?: string;
+    bodyText?: string;
+    imageUrls?: string[];
+    annotationIndex: number;
+    scaleFactor: number;
+    private _material?;
+    private _texture?;
+    private _mesh?;
+    private _canvas?;
+    private _drawnSignature;
+    private _currentImage;
+    private _loadToken;
+    private _headRotation;
+    private _anchor;
+    private _scratchDir;
+    private _yawQuat;
+    private _axisRight;
+    private _axisUp;
+    private _scratchScale;
+    private _onSelect;
+    initialize(): void;
+    private _createMesh;
+    private _roundRect;
+    private _drawArrow;
+    private _drawDots;
+    private _drawContent;
+    private _setImage;
+    private _loadCurrentImage;
+    private _rayQuadHit;
+    /** True when the ray points at the panel quad (used to suppress the empty-select dismiss). */
+    rayHitsPanel(origin: Vec3, direction: Vec3): boolean;
+    update(): void;
+    private _trackHead;
+    private _teardown;
+}
+//# sourceMappingURL=vr-annotation-panel.d.ts.map

package/components/VirtualWalkthrough/vr-annotation-panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vr-annotation-panel.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/vr-annotation-panel.ts"],"names":[],"mappings":"AAAA,OAAO,EAUL,MAAM,EAGN,IAAI,EAEL,MAAM,YAAY,CAAC;AAiCpB,qBAAa,iBAAkB,SAAQ,MAAM;IAC3C,MAAM,CAAC,UAAU,SAAuB;IAGxC,KAAK,SAAM;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,eAAe,SAAM;IACrB,WAAW,SAAK;IAEhB,OAAO,CAAC,SAAS,CAAC,CAAmB;IACrC,OAAO,CAAC,QAAQ,CAAC,CAAU;IAC3B,OAAO,CAAC,KAAK,CAAC,CAAO;IACrB,OAAO,CAAC,OAAO,CAAC,CAAoB;IACpC,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAK;IAEvB,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,QAAQ,CAAc;IAC9B,OAAO,CAAC,UAAU,CAAc;IAChC,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,aAAa,CAAc;IAEnC,OAAO,CAAC,SAAS,CAsBf;IAEF,UAAU;IAwCV,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,UAAU;IAkBlB,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,YAAY;IAqFpB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,iBAAiB;IAkBzB,OAAO,CAAC,WAAW;IAmBnB,8FAA8F;IAC9F,YAAY,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,OAAO;IAIpD,MAAM;IAsCN,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,SAAS;CAYlB"}

package/components/VirtualWalkthrough/vr-annotation-panel.js

@@ -0,0 +1,312 @@
+import { ADDRESS_CLAMP_TO_EDGE, BLEND_NORMAL, CULLFACE_NONE, Color, FILTER_LINEAR, LAYERID_IMMEDIATE, Mesh, MeshInstance, Quat, Script, StandardMaterial, Texture, Vec3 } from 'playcanvas';
+import { wrapText } from './vr-annotation-panel-layout';
+import { rayQuadHit } from './xr-ray-quad';
+const CANVAS_WIDTH = 1024;
+const CANVAS_HEIGHT = 768;
+
+/** Panel width in world meters; height derived from the canvas aspect ratio. */
+const PANEL_WIDTH = 0.5;
+const PANEL_HEIGHT = PANEL_WIDTH * CANVAS_HEIGHT / CANVAS_WIDTH;
+
+/** World-space offset from the anchored hotspot: raise the panel above it so the
+ * (tall) panel clears the hotspot rather than covering it. */
+const PANEL_OFFSET = new Vec3(0, PANEL_HEIGHT / 2 + 0.05, 0);
+const PAD_X = 48;
+
+/** Local +z (the quad's front face) — used to derive the panel's yaw toward the viewer. */
+const FORWARD_Z = new Vec3(0, 0, 1);
+/** Quad in-plane axes in local space, transformed to world for ray hit-testing. */
+const RIGHT_AXIS = new Vec3(1, 0, 0);
+const UP_AXIS = new Vec3(0, 1, 0);
+const RAD_TO_DEG = 180 / Math.PI;
+
+/** Fixed image band (canvas px) so arrows/dots keep a stable position while images load. */
+const IMAGE_Y = 40;
+const IMAGE_H = 360;
+
+/** Width (canvas px) of the left/right arrow hit + draw zones over the image band. */
+const ARROW_ZONE_W = 170;
+export class VrAnnotationPanel extends Script {
+  static scriptName = 'vrAnnotationPanel';
+
+  // Props assigned by the React wrapper.
+  title = '';
+  annotationIndex = -1;
+  scaleFactor = 1;
+  _drawnSignature = null;
+  _currentImage = 0;
+  _loadToken = 0;
+  _headRotation = new Quat();
+  _anchor = new Vec3();
+  _scratchDir = new Vec3();
+  _yawQuat = new Quat();
+  _axisRight = new Vec3();
+  _axisUp = new Vec3();
+  _scratchScale = new Vec3();
+  _onSelect = inputSource => {
+    if (this.app.xr?.active !== true) {
+      return;
+    }
+    const images = this.imageUrls ?? [];
+    if (images.length <= 1) {
+      return;
+    }
+    const hit = this._rayQuadHit(inputSource.getOrigin(), inputSource.getDirection());
+    if (!hit) {
+      return;
+    }
+    const cx = (hit.u + 1) / 2 * CANVAS_WIDTH;
+    const cy = (1 - hit.v) / 2 * CANVAS_HEIGHT;
+    if (cy < IMAGE_Y || cy > IMAGE_Y + IMAGE_H) {
+      return;
+    }
+    if (cx <= ARROW_ZONE_W) {
+      this._setImage((this._currentImage - 1 + images.length) % images.length);
+    } else if (cx >= CANVAS_WIDTH - ARROW_ZONE_W) {
+      this._setImage((this._currentImage + 1) % images.length);
+    }
+  };
+  initialize() {
+    this._canvas = document.createElement('canvas');
+    this._canvas.width = CANVAS_WIDTH;
+    this._canvas.height = CANVAS_HEIGHT;
+    this._texture = new Texture(this.app.graphicsDevice, {
+      name: 'vr-annotation-panel',
+      width: CANVAS_WIDTH,
+      height: CANVAS_HEIGHT,
+      addressU: ADDRESS_CLAMP_TO_EDGE,
+      addressV: ADDRESS_CLAMP_TO_EDGE,
+      minFilter: FILTER_LINEAR,
+      magFilter: FILTER_LINEAR,
+      mipmaps: true
+    });
+    this._texture.setSource(this._canvas);
+    const material = new StandardMaterial();
+    material.useLighting = false;
+    material.emissive = new Color(1, 1, 1);
+    material.emissiveMap = this._texture;
+    material.opacityMap = this._texture;
+    material.opacityMapChannel = 'a';
+    material.blendType = BLEND_NORMAL;
+    material.depthTest = false;
+    material.depthWrite = false;
+    material.cull = CULLFACE_NONE;
+    material.update();
+    this._material = material;
+    this._mesh = this._createMesh();
+    const meshInstance = new MeshInstance(this._mesh, material);
+    this.entity.addComponent('render', {
+      meshInstances: [meshInstance],
+      layers: [LAYERID_IMMEDIATE]
+    });
+    this.app.xr?.input?.on('select', this._onSelect);
+    // Script removal fires a 'destroy' event rather than calling a destroy() method, so the
+    // teardown has to be registered as a listener or the handler and GPU resources outlive us.
+    this.once('destroy', () => this._teardown());
+  }
+  _createMesh() {
+    const hw = PANEL_WIDTH / 2;
+    const hh = PANEL_HEIGHT / 2;
+    const mesh = new Mesh(this.app.graphicsDevice);
+    mesh.setPositions([-hw, -hh, 0, hw, -hh, 0, hw, hh, 0, -hw, hh, 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;
+  }
+  _roundRect(ctx, x, y, w, h, r) {
+    ctx.beginPath();
+    ctx.moveTo(x + r, y);
+    ctx.arcTo(x + w, y, x + w, y + h, r);
+    ctx.arcTo(x + w, y + h, x, y + h, r);
+    ctx.arcTo(x, y + h, x, y, r);
+    ctx.arcTo(x, y, x + w, y, r);
+    ctx.closePath();
+  }
+  _drawArrow(ctx, cx, cy, pointsLeft) {
+    ctx.beginPath();
+    ctx.arc(cx, cy, 40, 0, Math.PI * 2);
+    ctx.fillStyle = 'rgba(0, 0, 0, 0.45)';
+    ctx.fill();
+    const s = 16;
+    const tip = pointsLeft ? cx - s * 0.6 : cx + s * 0.6;
+    const base = pointsLeft ? cx + s * 0.6 : cx - s * 0.6;
+    ctx.beginPath();
+    ctx.moveTo(base, cy - s);
+    ctx.lineTo(tip, cy);
+    ctx.lineTo(base, cy + s);
+    ctx.closePath();
+    ctx.fillStyle = '#ffffff';
+    ctx.fill();
+  }
+  _drawDots(ctx, count, dotY) {
+    const gap = 26;
+    const startX = CANVAS_WIDTH / 2 - (count - 1) * gap / 2;
+    for (let i = 0; i < count; i++) {
+      ctx.beginPath();
+      ctx.arc(startX + i * gap, dotY, 7, 0, Math.PI * 2);
+      ctx.fillStyle = i === this._currentImage ? 'rgba(0, 0, 0, 0.85)' : 'rgba(0, 0, 0, 0.25)';
+      ctx.fill();
+    }
+  }
+  _drawContent(image) {
+    const ctx = this._canvas?.getContext('2d');
+    if (!ctx) {
+      return;
+    }
+    ctx.clearRect(0, 0, CANVAS_WIDTH, CANVAS_HEIGHT);
+    ctx.fillStyle = 'rgba(255, 255, 255, 0.96)';
+    this._roundRect(ctx, 0, 0, CANVAS_WIDTH, CANVAS_HEIGHT, 32);
+    ctx.fill();
+    let y = IMAGE_Y;
+    const contentWidth = CANVAS_WIDTH - PAD_X * 2;
+    const images = this.imageUrls ?? [];
+    if (images.length > 0) {
+      ctx.save();
+      this._roundRect(ctx, PAD_X, IMAGE_Y, contentWidth, IMAGE_H, 16);
+      ctx.clip();
+      if (image) {
+        const scale = Math.max(contentWidth / image.width, IMAGE_H / image.height);
+        const dw = image.width * scale;
+        const dh = image.height * scale;
+        ctx.drawImage(image, PAD_X + (contentWidth - dw) / 2, IMAGE_Y + (IMAGE_H - dh) / 2, dw, dh);
+      } else {
+        ctx.fillStyle = 'rgba(0, 0, 0, 0.06)';
+        ctx.fillRect(PAD_X, IMAGE_Y, contentWidth, IMAGE_H);
+      }
+      ctx.restore();
+      y = IMAGE_Y + IMAGE_H + 16;
+      if (images.length > 1) {
+        const bandCenterY = IMAGE_Y + IMAGE_H / 2;
+        this._drawArrow(ctx, ARROW_ZONE_W / 2, bandCenterY, true);
+        this._drawArrow(ctx, CANVAS_WIDTH - ARROW_ZONE_W / 2, bandCenterY, false);
+        this._drawDots(ctx, images.length, y + 4);
+        y += 32;
+      }
+      y += 16;
+    }
+    if (this.label) {
+      ctx.font = '600 28px sans-serif';
+      ctx.textBaseline = 'middle';
+      const chipW = ctx.measureText(this.label).width + 32;
+      const chipH = 44;
+      ctx.fillStyle = 'rgba(44, 134, 88, 0.95)';
+      this._roundRect(ctx, PAD_X, y, chipW, chipH, 12);
+      ctx.fill();
+      ctx.fillStyle = '#ffffff';
+      ctx.fillText(this.label, PAD_X + 16, y + chipH / 2);
+      y += chipH + 24;
+    }
+    ctx.textBaseline = 'top';
+    ctx.fillStyle = '#000000';
+    ctx.font = '700 48px sans-serif';
+    const titleLines = wrapText(this.title, contentWidth, s => ctx.measureText(s).width);
+    for (const line of titleLines) {
+      if (y > CANVAS_HEIGHT - 40) {
+        break;
+      }
+      ctx.fillText(line, PAD_X, y);
+      y += 56;
+    }
+    y += 16;
+    if (this.bodyText) {
+      ctx.font = '400 32px sans-serif';
+      ctx.fillStyle = 'rgba(0, 0, 0, 0.85)';
+      const lines = wrapText(this.bodyText, contentWidth, s => ctx.measureText(s).width);
+      for (const line of lines) {
+        if (y > CANVAS_HEIGHT - 40) {
+          break;
+        }
+        ctx.fillText(line, PAD_X, y);
+        y += 40;
+      }
+    }
+    this._texture?.upload();
+  }
+  _setImage(index) {
+    this._currentImage = index;
+    this._drawContent();
+    this._loadCurrentImage();
+  }
+  _loadCurrentImage() {
+    const url = this.imageUrls?.[this._currentImage];
+    if (!url) {
+      return;
+    }
+    const token = ++this._loadToken;
+    const img = new Image();
+    img.crossOrigin = 'anonymous';
+    img.onload = () => {
+      // Ignore a stale load that a newer navigation has superseded.
+      if (token === this._loadToken) {
+        this._drawContent(img);
+      }
+    };
+    // onerror (e.g. a host without CORS headers): keep the placeholder + text already drawn.
+    img.src = url;
+  }
+  _rayQuadHit(origin, direction) {
+    const rotation = this.entity.getRotation();
+    rotation.transformVector(RIGHT_AXIS, this._axisRight);
+    rotation.transformVector(UP_AXIS, this._axisUp);
+    this.entity.getWorldTransform().getScale(this._scratchScale);
+    const halfWidth = PANEL_WIDTH / 2 * this._scratchScale.x;
+    const halfHeight = PANEL_HEIGHT / 2 * this._scratchScale.y;
+    return rayQuadHit(origin, direction, this.entity.getPosition(), this._axisRight, this._axisUp, halfWidth, halfHeight);
+  }
+
+  /** True when the ray points at the panel quad (used to suppress the empty-select dismiss). */
+  rayHitsPanel(origin, direction) {
+    return this._rayQuadHit(origin, direction) !== null;
+  }
+  update() {
+    if (this.app.xr?.active !== true) {
+      return;
+    }
+    const signature = `${this.title}|${this.label ?? ''}|${this.bodyText ?? ''}|${(this.imageUrls ?? []).join(',')}`;
+    if (signature !== this._drawnSignature) {
+      this._drawnSignature = signature;
+      this._currentImage = 0;
+      this._drawContent();
+      this._loadCurrentImage();
+    }
+    this._trackHead();
+    const anchor = this.app.root.findByName(`annotation-${this.annotationIndex}`);
+    if (!anchor) {
+      return;
+    }
+    this._anchor.copy(anchor.getPosition());
+    // Panel size and its offset from the hotspot scale with the scene so the panel keeps its
+    // proportions relative to the (content-root-scaled) annotations across scenes.
+    this.entity.setLocalScale(this.scaleFactor, this.scaleFactor, this.scaleFactor);
+    this.entity.setPosition(this._anchor.x + PANEL_OFFSET.x * this.scaleFactor, this._anchor.y + PANEL_OFFSET.y * this.scaleFactor, this._anchor.z + PANEL_OFFSET.z * this.scaleFactor);
+
+    // Billboard on yaw only: face the viewer horizontally but stay upright and level, so
+    // tilting/rolling the headset does not tilt the panel. Derived from the head's forward
+    // heading, so it matches the level head-rotation orientation but with pitch/roll removed.
+    this._headRotation.transformVector(FORWARD_Z, this._scratchDir);
+    const yaw = Math.atan2(this._scratchDir.x, this._scratchDir.z) * RAD_TO_DEG;
+    this._yawQuat.setFromEulerAngles(0, yaw, 0);
+    this.entity.setRotation(this._yawQuat);
+  }
+  _trackHead() {
+    const views = this.app.xr?.views?.list;
+    if (!views || views.length === 0) {
+      return;
+    }
+    this._headRotation.setFromMat4(views[0].viewInvOffMat);
+  }
+  _teardown() {
+    this.app.xr?.input?.off('select', this._onSelect);
+    if (this.entity.render) {
+      this.entity.render.meshInstances = [];
+    }
+    this._mesh?.destroy();
+    this._material?.destroy();
+    this._texture?.destroy();
+    this._mesh = undefined;
+    this._material = undefined;
+    this._texture = undefined;
+  }
+}

package/components/VirtualWalkthrough/xr-annotation-candidates.d.ts

@@ -0,0 +1,18 @@
+import { Vec3 } from 'playcanvas';
+/** Local half-extent of the unit-plane hotspot quad. */
+export declare const HOTSPOT_HALF_EXTENT = 0.5;
+/** Multiplier on the hotspot's world radius to make controller targeting forgiving. */
+export declare const HIT_RADIUS_PAD = 2.5;
+export interface AnnotationCandidate {
+    entity: any;
+    script: any;
+    position: Vec3;
+    radius: number;
+}
+/**
+ * World-space hit candidates for every openable annotation hotspot: its entity, its stock
+ * annotation script (which carries `onVrOpenCallback`), its world position, and a hit-sphere
+ * radius derived from the hotspot's rendered world size, padded by `radiusPad` for easier aiming.
+ */
+export declare const collectAnnotationHitCandidates: (app: any, radiusPad: number) => AnnotationCandidate[];
+//# sourceMappingURL=xr-annotation-candidates.d.ts.map

package/components/VirtualWalkthrough/xr-annotation-candidates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-annotation-candidates.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-annotation-candidates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAGlC,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,uFAAuF;AACvF,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,GAAG,CAAC;IACZ,MAAM,EAAE,GAAG,CAAC;IACZ,QAAQ,EAAE,IAAI,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAID;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,GAAI,KAAK,GAAG,EAAE,WAAW,MAAM,KAAG,mBAAmB,EAmB/F,CAAC"}

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

@@ -0,0 +1,38 @@
+import { Vec3 } from 'playcanvas';
+import { Annotation as PcAnnotation } from 'playcanvas/scripts/esm/annotations.mjs';
+
+/** Local half-extent of the unit-plane hotspot quad. */
+export const HOTSPOT_HALF_EXTENT = 0.5;
+
+/** Multiplier on the hotspot's world radius to make controller targeting forgiving. */
+export const HIT_RADIUS_PAD = 2.5;
+const scratchScale = new Vec3();
+
+/**
+ * World-space hit candidates for every openable annotation hotspot: its entity, its stock
+ * annotation script (which carries `onVrOpenCallback`), its world position, and a hit-sphere
+ * radius derived from the hotspot's rendered world size, padded by `radiusPad` for easier aiming.
+ */
+export const collectAnnotationHitCandidates = (app, radiusPad) => {
+  const root = app.root.findByName('annotations-root');
+  if (!root) {
+    return [];
+  }
+  return root.children.map(entity => ({
+    entity,
+    script: entity.script?.get(PcAnnotation.scriptName)
+  })).filter(({
+    script
+  }) => script && script.enabled !== false && typeof script.onVrOpenCallback === 'function').map(({
+    entity,
+    script
+  }) => {
+    entity.getWorldTransform().getScale(scratchScale);
+    return {
+      entity,
+      script,
+      position: entity.getPosition(),
+      radius: HOTSPOT_HALF_EXTENT * scratchScale.x * radiusPad
+    };
+  });
+};

package/components/VirtualWalkthrough/xr-annotation-interaction.d.ts

@@ -0,0 +1,13 @@
+import { Script } from 'playcanvas';
+export declare class XrAnnotationInteraction extends Script {
+    static scriptName: string;
+    onDismissCallback?: () => void;
+    private _faceButtons;
+    private _isVrActive;
+    private _dismiss;
+    private _onSelect;
+    private _openAnnotationUnderRay;
+    initialize(): void;
+    update(): void;
+}
+//# sourceMappingURL=xr-annotation-interaction.d.ts.map

package/components/VirtualWalkthrough/xr-annotation-interaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-annotation-interaction.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-annotation-interaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAkC,MAAM,YAAY,CAAC;AAOpE,qBAAa,uBAAwB,SAAQ,MAAM;IACjD,MAAM,CAAC,UAAU,SAA6B;IAE9C,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAC;IAE/B,OAAO,CAAC,YAAY,CAAgC;IAEpD,OAAO,CAAC,WAAW,CAAyE;IAE5F,OAAO,CAAC,QAAQ,CAId;IAEF,OAAO,CAAC,SAAS,CAKf;IAEF,OAAO,CAAC,uBAAuB;IAqB/B,UAAU;IAKV,MAAM;CAeP"}

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

@@ -0,0 +1,59 @@
+import { Script, XRTYPE_VR } from 'playcanvas';
+import { HIT_RADIUS_PAD, collectAnnotationHitCandidates } from './xr-annotation-candidates';
+import { nearestAnnotationHit } from './xr-annotation-targeting';
+import { FaceButtonPressTracker } from './xr-face-buttons';
+import { rayHitsAnnotationPanel } from './xr-interactive-ui';
+export class XrAnnotationInteraction extends Script {
+  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();
+    }
+  };
+  _onSelect = inputSource => {
+    if (!this._isVrActive()) {
+      return;
+    }
+    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.findByName('camera');
+    const screen = camera?.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;
+      }
+    }
+  }
+}

package/components/VirtualWalkthrough/xr-annotation-targeting.d.ts

@@ -0,0 +1,10 @@
+import { Vec3 } from 'playcanvas';
+export interface AnnotationHitCandidate {
+    position: Vec3;
+    radius: number;
+}
+/**
+ * Index of the closest candidate sphere the ray enters, or null if it hits none.
+ */
+export declare const nearestAnnotationHit: (origin: Vec3, direction: Vec3, candidates: AnnotationHitCandidate[]) => number | null;
+//# sourceMappingURL=xr-annotation-targeting.d.ts.map

package/components/VirtualWalkthrough/xr-annotation-targeting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-annotation-targeting.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-annotation-targeting.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,IAAI,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAsBD;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,IAAI,EACZ,WAAW,IAAI,EACf,YAAY,sBAAsB,EAAE,KACnC,MAAM,GAAG,IAcX,CAAC"}

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

@@ -0,0 +1,36 @@
+import { Vec3 } from 'playcanvas';
+/**
+ * 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 = new Vec3().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;
+};
+
+/**
+ * Index of the closest candidate sphere the ray enters, or null if it hits none.
+ */
+export const nearestAnnotationHit = (origin, direction, candidates) => {
+  const dir = direction.clone().normalize();
+  let bestIndex = null;
+  let bestDistance = Infinity;
+  candidates.forEach((candidate, index) => {
+    const distance = raySphereEntryDistance(origin, dir, candidate.position, candidate.radius);
+    if (distance !== null && distance < bestDistance) {
+      bestDistance = distance;
+      bestIndex = index;
+    }
+  });
+  return bestIndex;
+};

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

@@ -0,0 +1,66 @@
+import { Vec3 } from 'playcanvas';
+import { nearestAnnotationHit } from './xr-annotation-targeting';
+describe('nearestAnnotationHit', () => {
+  const origin = new Vec3(0, 0, 5);
+  const forward = new Vec3(0, 0, -1);
+  it('returns null when there are no candidates', () => {
+    expect(nearestAnnotationHit(origin, forward, [])).toBeNull();
+  });
+  it('returns null when the ray misses every candidate', () => {
+    const candidates = [{
+      position: new Vec3(0, 5, 0),
+      radius: 1
+    }];
+    expect(nearestAnnotationHit(origin, forward, candidates)).toBeNull();
+  });
+  it('returns the index of a single hit candidate', () => {
+    const candidates = [{
+      position: new Vec3(0, 0, 0),
+      radius: 1
+    }];
+    expect(nearestAnnotationHit(origin, forward, candidates)).toBe(0);
+  });
+  it('returns the nearest candidate when several are hit, regardless of order', () => {
+    const far = {
+      position: new Vec3(0, 0, -5),
+      radius: 1
+    };
+    const near = {
+      position: new Vec3(0, 0, 0),
+      radius: 1
+    };
+    expect(nearestAnnotationHit(origin, forward, [far, near])).toBe(1);
+  });
+  it('treats a ray starting inside a sphere as the nearest hit', () => {
+    const inside = {
+      position: new Vec3(0, 0, 5),
+      radius: 1
+    };
+    const ahead = {
+      position: new Vec3(0, 0, 0),
+      radius: 1
+    };
+    expect(nearestAnnotationHit(origin, forward, [ahead, inside])).toBe(1);
+  });
+  it('normalizes a non-unit direction', () => {
+    const candidates = [{
+      position: new Vec3(0, 0, 0),
+      radius: 1
+    }];
+    expect(nearestAnnotationHit(origin, new Vec3(0, 0, -4), candidates)).toBe(0);
+  });
+  it('returns null when the only candidate is behind the ray origin', () => {
+    const candidates = [{
+      position: new Vec3(0, 0, 0),
+      radius: 1
+    }];
+    expect(nearestAnnotationHit(origin, new Vec3(0, 0, 1), candidates)).toBeNull();
+  });
+  it('registers a tangent graze as a hit', () => {
+    const candidates = [{
+      position: new Vec3(0, 0, 0),
+      radius: 1
+    }];
+    expect(nearestAnnotationHit(new Vec3(0, 1, 5), new Vec3(0, 0, -1), candidates)).toBe(0);
+  });
+});

package/components/VirtualWalkthrough/xr-button-arming.d.ts

@@ -0,0 +1,14 @@
+import { XrInputSource } from 'playcanvas';
+/**
+ * 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.
+ */
+export declare class ButtonArmingLatch {
+    private _armed;
+    /** Records one frame for `inputSource` and returns whether its current press may count. */
+    trackPress(inputSource: XrInputSource, pressed: boolean): boolean;
+}
+//# sourceMappingURL=xr-button-arming.d.ts.map

package/components/VirtualWalkthrough/xr-button-arming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-button-arming.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-button-arming.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAgC;IAE9C,2FAA2F;IAC3F,UAAU,CAAC,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;CASlE"}

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

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+export class ButtonArmingLatch {
+  _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);
+  }
+}