@terraware/web-components 4.2.21 → 4.2.22

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);
+  });
+});

package/components/VirtualWalkthrough/xr-pointer-ray.d.ts

@@ -0,0 +1,10 @@
+import { Color, Script } from 'playcanvas';
+/** Default ray colour (cyan) — bright enough to read against the scene. */
+export declare const DEFAULT_RAY_COLOR: Color;
+export declare class XrPointerRay extends Script {
+    static scriptName: string;
+    color: Color;
+    private _end;
+    update(): void;
+}
+//# sourceMappingURL=xr-pointer-ray.d.ts.map

package/components/VirtualWalkthrough/xr-pointer-ray.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-pointer-ray.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-pointer-ray.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,EAAQ,MAAM,YAAY,CAAC;AAKjD,2EAA2E;AAC3E,eAAO,MAAM,iBAAiB,OAA0B,CAAC;AAEzD,qBAAa,YAAa,SAAQ,MAAM;IACtC,MAAM,CAAC,UAAU,SAAkB;IAEnC,KAAK,QAA6B;IAElC,OAAO,CAAC,IAAI,CAAc;IAE1B,MAAM;CAaP"}

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

@@ -0,0 +1,24 @@
+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. */
+export const DEFAULT_RAY_COLOR = new Color(0.25, 0.8, 1);
+export 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);
+    }
+  }
+}

package/components/VirtualWalkthrough/xr-progress-pie.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Draws a circular progress pie into the `size` x `size` region at the context origin: a faint
+ * full-circle track under a wedge that sweeps clockwise as `progress` goes 0 -> 1. A `progress`
+ * above 1 simply sweeps a full circle. Neither clears the context nor uploads a texture, so callers
+ * can composite it between their own layers. Saves and restores the drawing state it touches and
+ * leaves the path clean on exit, so callers can stroke or fill right after without an explicit
+ * `beginPath()` of their own.
+ */
+export declare const drawProgressPie: (ctx: CanvasRenderingContext2D, size: number, progress: number) => void;
+//# sourceMappingURL=xr-progress-pie.d.ts.map

package/components/VirtualWalkthrough/xr-progress-pie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-progress-pie.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-progress-pie.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,wBAAwB,EAAE,MAAM,MAAM,EAAE,UAAU,MAAM,SAsB5F,CAAC"}

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

@@ -0,0 +1,30 @@
+/** Sweep starts at 12 o'clock. */
+const PIE_START_ANGLE = -Math.PI / 2;
+
+/**
+ * Draws a circular progress pie into the `size` x `size` region at the context origin: a faint
+ * full-circle track under a wedge that sweeps clockwise as `progress` goes 0 -> 1. A `progress`
+ * above 1 simply sweeps a full circle. Neither clears the context nor uploads a texture, so callers
+ * can composite it between their own layers. Saves and restores the drawing state it touches and
+ * leaves the path clean on exit, so callers can stroke or fill right after without an explicit
+ * `beginPath()` of their own.
+ */
+export const drawProgressPie = (ctx, size, progress) => {
+  const c = size / 2;
+  const r = c * 0.92;
+  ctx.save();
+  ctx.beginPath();
+  ctx.arc(c, c, r, 0, Math.PI * 2);
+  ctx.fillStyle = 'rgba(255, 255, 255, 0.18)';
+  ctx.fill();
+  if (progress > 0) {
+    ctx.beginPath();
+    ctx.moveTo(c, c);
+    ctx.arc(c, c, r, PIE_START_ANGLE, PIE_START_ANGLE + progress * Math.PI * 2);
+    ctx.closePath();
+    ctx.fillStyle = 'rgba(64, 200, 255, 0.85)';
+    ctx.fill();
+  }
+  ctx.restore();
+  ctx.beginPath();
+};

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

@@ -0,0 +1,79 @@
+import { drawProgressPie } from './xr-progress-pie';
+const TRACK_FILL = 'rgba(255, 255, 255, 0.18)';
+const WEDGE_FILL = 'rgba(64, 200, 255, 0.85)';
+
+/** Minimal 2D-context stand-in that records the arcs drawn and the fill colour used for each. */
+const stubContext = () => {
+  const arcs = [];
+  const fills = [];
+  const ctx = {
+    fillStyle: '',
+    save: () => undefined,
+    restore: () => undefined,
+    beginPath: () => undefined,
+    moveTo: () => undefined,
+    closePath: () => undefined,
+    arc: (_x, _y, radius, start, end) => {
+      arcs.push({
+        radius,
+        start,
+        end
+      });
+    },
+    fill: () => {
+      fills.push(ctx.fillStyle);
+    }
+  };
+  return {
+    ctx: ctx,
+    arcs,
+    fills
+  };
+};
+describe('drawProgressPie', () => {
+  it('draws only the full-circle track at zero progress', () => {
+    const {
+      ctx,
+      arcs,
+      fills
+    } = stubContext();
+    drawProgressPie(ctx, 128, 0);
+    expect(arcs).toHaveLength(1);
+    expect(arcs[0].end - arcs[0].start).toBeCloseTo(Math.PI * 2);
+    expect(fills).toEqual([TRACK_FILL]);
+  });
+  it('sweeps a quarter turn clockwise from the top at quarter progress', () => {
+    const {
+      ctx,
+      arcs
+    } = stubContext();
+    drawProgressPie(ctx, 128, 0.25);
+    expect(arcs).toHaveLength(2);
+    expect(arcs[1].start).toBeCloseTo(-Math.PI / 2);
+    expect(arcs[1].end).toBeCloseTo(0);
+  });
+  it('sweeps a full turn at full progress', () => {
+    const {
+      ctx,
+      arcs
+    } = stubContext();
+    drawProgressPie(ctx, 128, 1);
+    expect(arcs[1].end - arcs[1].start).toBeCloseTo(Math.PI * 2);
+  });
+  it('fills the wedge over the track', () => {
+    const {
+      ctx,
+      fills
+    } = stubContext();
+    drawProgressPie(ctx, 128, 0.5);
+    expect(fills).toEqual([TRACK_FILL, WEDGE_FILL]);
+  });
+  it('scales the radius to the drawn size', () => {
+    const {
+      ctx,
+      arcs
+    } = stubContext();
+    drawProgressPie(ctx, 256, 0);
+    expect(arcs[0].radius).toBeCloseTo(128 * 0.92);
+  });
+});

package/components/VirtualWalkthrough/xr-ray-quad.d.ts

@@ -0,0 +1,13 @@
+import { Vec3 } from 'playcanvas';
+export interface QuadHit {
+    u: number;
+    v: number;
+}
+/**
+ * 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.
+ */
+export declare const rayQuadHit: (origin: Vec3, direction: Vec3, center: Vec3, right: Vec3, up: Vec3, halfWidth: number, halfHeight: number) => QuadHit | null;
+//# sourceMappingURL=xr-ray-quad.d.ts.map

package/components/VirtualWalkthrough/xr-ray-quad.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-ray-quad.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-ray-quad.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,MAAM,WAAW,OAAO;IACtB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GACrB,QAAQ,IAAI,EACZ,WAAW,IAAI,EACf,QAAQ,IAAI,EACZ,OAAO,IAAI,EACX,IAAI,IAAI,EACR,WAAW,MAAM,EACjB,YAAY,MAAM,KACjB,OAAO,GAAG,IAqBZ,CAAC"}