@terraware/web-components 4.2.21 → 4.2.22

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

@@ -0,0 +1,35 @@
+import { ButtonArmingLatch } from './xr-button-arming';
+const source = () => ({});
+describe('ButtonArmingLatch', () => {
+  it('never counts a source pressed from the very first poll, while it stays down', () => {
+    const latch = new ButtonArmingLatch();
+    const src = source();
+    expect(latch.trackPress(src, true)).toBe(false);
+    expect(latch.trackPress(src, true)).toBe(false);
+    expect(latch.trackPress(src, true)).toBe(false);
+  });
+  it('counts a press that follows a release', () => {
+    const latch = new ButtonArmingLatch();
+    const src = source();
+    latch.trackPress(src, true);
+    latch.trackPress(src, false);
+    expect(latch.trackPress(src, true)).toBe(true);
+  });
+  it('tracks each input source independently, so one held from the first poll does not block another', () => {
+    const latch = new ButtonArmingLatch();
+    const held = source();
+    const other = source();
+    latch.trackPress(held, true);
+    latch.trackPress(other, false);
+    expect(latch.trackPress(held, true)).toBe(false);
+    expect(latch.trackPress(other, true)).toBe(true);
+  });
+  it('stays armed across later press/release cycles', () => {
+    const latch = new ButtonArmingLatch();
+    const src = source();
+    latch.trackPress(src, false);
+    expect(latch.trackPress(src, true)).toBe(true);
+    latch.trackPress(src, false);
+    expect(latch.trackPress(src, true)).toBe(true);
+  });
+});

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

@@ -0,0 +1,20 @@
+export interface HoldState {
+    elapsed: number;
+    armed: boolean;
+}
+export interface HoldUpdate {
+    state: HoldState;
+    progress: number;
+    justFired: boolean;
+}
+export declare const INITIAL_HOLD_STATE: HoldState;
+/**
+ * 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.
+ */
+export declare const advanceHold: (prev: HoldState, held: boolean, dt: number, threshold: number) => HoldUpdate;
+//# sourceMappingURL=xr-button-hold.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"xr-button-hold.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-button-hold.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,eAAO,MAAM,kBAAkB,EAAE,SAAwC,CAAC;AAI1E;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,EAAE,MAAM,OAAO,EAAE,IAAI,MAAM,EAAE,WAAW,MAAM,KAAG,UAY3F,CAAC"}

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

@@ -0,0 +1,43 @@
+export const INITIAL_HOLD_STATE = {
+  elapsed: 0,
+  armed: false
+};
+const RELEASED_STATE = {
+  elapsed: 0,
+  armed: true
+};
+
+/**
+ * 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.
+ */
+export 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
+    };
+  }
+  const elapsed = Math.min(prev.elapsed + dt, threshold);
+  const justFired = prev.elapsed < threshold && elapsed >= threshold;
+  return {
+    state: {
+      elapsed,
+      armed: true
+    },
+    progress: elapsed / threshold,
+    justFired
+  };
+};

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

@@ -0,0 +1,57 @@
+import { INITIAL_HOLD_STATE, advanceHold } from './xr-button-hold';
+const THRESHOLD = 1.25;
+
+/** Arms the timer the way a real release does, so a press can start accumulating. */
+const released = () => advanceHold(INITIAL_HOLD_STATE, false, 0.1, THRESHOLD).state;
+describe('advanceHold', () => {
+  it('ignores a button that is already held when tracking starts', () => {
+    const result = advanceHold(INITIAL_HOLD_STATE, true, 2, THRESHOLD);
+    expect(result.progress).toBe(0);
+    expect(result.justFired).toBe(false);
+  });
+  it('stays unarmed for as long as a pre-held button is down', () => {
+    let state = INITIAL_HOLD_STATE;
+    for (let frame = 0; frame < 5; frame += 1) {
+      state = advanceHold(state, true, 1, THRESHOLD).state;
+    }
+    expect(advanceHold(state, true, 1, THRESHOLD).justFired).toBe(false);
+  });
+  it('arms on release so the next press accumulates', () => {
+    expect(advanceHold(released(), true, 0.5, THRESHOLD).progress).toBeCloseTo(0.4);
+  });
+  it('accumulates progress across frames', () => {
+    let state = released();
+    let progress = 0;
+    for (let frame = 0; frame < 3; frame += 1) {
+      const result = advanceHold(state, true, 0.25, THRESHOLD);
+      state = result.state;
+      progress = result.progress;
+    }
+    expect(progress).toBeCloseTo(0.6);
+  });
+  it('fires once when the hold reaches the threshold', () => {
+    const partial = advanceHold(released(), true, 1, THRESHOLD).state;
+    const firing = advanceHold(partial, true, 1, THRESHOLD);
+    expect(firing.justFired).toBe(true);
+    expect(firing.progress).toBe(1);
+    expect(advanceHold(firing.state, true, 1, THRESHOLD).justFired).toBe(false);
+  });
+  it('clamps progress to the threshold', () => {
+    const result = advanceHold(released(), true, 99, THRESHOLD);
+    expect(result.progress).toBe(1);
+    expect(result.justFired).toBe(true);
+  });
+  it('resets to zero on release', () => {
+    const partial = advanceHold(released(), true, 1, THRESHOLD).state;
+    const result = advanceHold(partial, false, 0.1, THRESHOLD);
+    expect(result.progress).toBe(0);
+    expect(result.state.elapsed).toBe(0);
+  });
+  it('fires again only after a fresh press', () => {
+    const fired = advanceHold(advanceHold(released(), true, 1, THRESHOLD).state, true, 1, THRESHOLD).state;
+    const afterRelease = advanceHold(fired, false, 0.1, THRESHOLD).state;
+    const rePressed = advanceHold(afterRelease, true, 1, THRESHOLD);
+    expect(rePressed.justFired).toBe(false);
+    expect(advanceHold(rePressed.state, true, 1, THRESHOLD).justFired).toBe(true);
+  });
+});

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

@@ -19,17 +19,34 @@ export declare class XrExitButton extends Script {
     private _headPosition;
     private _headRotation;
     private _worldOffset;
-    private _faceButtonDown;
+    private _faceButtons;
+    private _canvas?;
+    private _context?;
+    private _drawnProgress;
+    private _hold;
+    private _arming;
     private _isVrActive;
     private _onXrStart;
     private _onXrEnd;
     private _onSelect;
-    private _rayHitsButton;
-    private _faceButtonPressed;
+    /** True when the ray points at the button's hit sphere. False while the button entity is disabled. */
+    rayHitsButton(origin: Vec3, direction: Vec3): boolean;
+    private _createCanvas;
     private _createTexture;
+    /**
+     * Repaints the button: dark disc, then the hold progress wedge, then the X arms on top so the
+     * glyph stays legible over the fill. The pie is skipped entirely at zero progress so the idle
+     * button doesn't wear the pie's faint track. Returns whether it painted, so callers can tell a
+     * missing context from a successful repaint.
+     */
+    private _drawButton;
+    /** Repaints only when the drawn wedge would visibly move. Only records the paint on success, so a
+     * missing context doesn't fool the dedupe cache into thinking a repaint already happened. */
+    private _setProgress;
+    private _resetProgress;
     private _createMesh;
     initialize(): void;
-    update(): void;
+    update(dt: number): void;
     /**
      * Pin the button to the upper-right of the headset view. The camera entity's transform is
      * overwritten every frame by WalkthroughCamera and is not the rendered head pose, so the head

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

@@ -1 +1 @@
-{"version":3,"file":"xr-exit-button.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-exit-button.ts"],"names":[],"mappings":"AAAA,OAAO,EAUL,MAAM,EAGN,IAAI,EAGL,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,IAAI,EAAE,WAAW,IAAI,EAAE,QAAQ,IAAI,EAAE,QAAQ,MAAM,KAAG,OAUhG,CAAC;AAOF,qBAAa,YAAa,SAAQ,MAAM;IACtC,MAAM,CAAC,UAAU,SAAkB;IAEnC,yGAAyG;IACzG,MAAM,OAA8B;IAEpC,oFAAoF;IACpF,QAAQ,SAAQ;IAEhB,sGAAsG;IACtG,SAAS,SAAQ;IAEjB,OAAO,CAAC,SAAS,CAAC,CAAmB;IACrC,OAAO,CAAC,QAAQ,CAAC,CAAU;IAC3B,OAAO,CAAC,KAAK,CAAC,CAAO;IACrB,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,YAAY,CAAc;IAClC,OAAO,CAAC,eAAe,CAAyC;IAEhE,OAAO,CAAC,WAAW,CAAyE;IAE5F,OAAO,CAAC,UAAU,CAEhB;IAEF,OAAO,CAAC,QAAQ,CAQd;IAEF,OAAO,CAAC,SAAS,CAOf;IAEF,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,cAAc;IAyCtB,OAAO,CAAC,WAAW;IAYnB,UAAU;IA6BV,MAAM;IAqCN;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAuBlB,OAAO;CAcR"}
+{"version":3,"file":"xr-exit-button.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-exit-button.ts"],"names":[],"mappings":"AAAA,OAAO,EAUL,MAAM,EAGN,IAAI,EAGL,MAAM,YAAY,CAAC;AAOpB;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,IAAI,EAAE,WAAW,IAAI,EAAE,QAAQ,IAAI,EAAE,QAAQ,MAAM,KAAG,OAUhG,CAAC;AAOF,qBAAa,YAAa,SAAQ,MAAM;IACtC,MAAM,CAAC,UAAU,SAAkB;IAEnC,yGAAyG;IACzG,MAAM,OAA8B;IAEpC,oFAAoF;IACpF,QAAQ,SAAQ;IAEhB,sGAAsG;IACtG,SAAS,SAAQ;IAEjB,OAAO,CAAC,SAAS,CAAC,CAAmB;IACrC,OAAO,CAAC,QAAQ,CAAC,CAAU;IAC3B,OAAO,CAAC,KAAK,CAAC,CAAO;IACrB,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,YAAY,CAAc;IAClC,OAAO,CAAC,YAAY,CAAgC;IAEpD,OAAO,CAAC,OAAO,CAAC,CAAoB;IACpC,OAAO,CAAC,QAAQ,CAAC,CAA2B;IAC5C,OAAO,CAAC,cAAc,CAAM;IAC5B,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,OAAO,CAA2B;IAE1C,OAAO,CAAC,WAAW,CAAyE;IAE5F,OAAO,CAAC,UAAU,CAGhB;IAEF,OAAO,CAAC,QAAQ,CASd;IAEF,OAAO,CAAC,SAAS,CAOf;IAEF,sGAAsG;IACtG,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,OAAO;IAQrD,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,cAAc;IAgBtB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAiCnB;iGAC6F;IAC7F,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,WAAW;IAYnB,UAAU;IAgCV,MAAM,CAAC,EAAE,EAAE,MAAM;IAoDjB;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAuBlB,OAAO;CAgBR"}

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

@@ -1,4 +1,8 @@
 import { ADDRESS_CLAMP_TO_EDGE, BLEND_NORMAL, CULLFACE_NONE, Color, FILTER_LINEAR, LAYERID_IMMEDIATE, Mesh, MeshInstance, Quat, Script, StandardMaterial, Texture, Vec3, XRTYPE_VR } from 'playcanvas';
+import { ButtonArmingLatch } from './xr-button-arming';
+import { INITIAL_HOLD_STATE, advanceHold } from './xr-button-hold';
+import { FaceButtonPressTracker, secondaryFaceButtonPressed } from './xr-face-buttons';
+import { drawProgressPie } from './xr-progress-pie';
 
 /**
  * Boolean ray-sphere hit test. Treats the ray as a half-line (t >= 0) and returns true when it
@@ -16,8 +20,8 @@ export const raySphereIntersect = (origin, direction, center, radius) => {
 };
 const TEXTURE_SIZE = 256;
 
-/** xr-standard gamepad button indices for the face buttons: A/X (4) and B/Y (5). */
-const FACE_BUTTON_INDICES = [4, 5];
+/** Seconds of continuous B/Y hold required to leave the session. Matches the gaze-dwell threshold. */
+const EXIT_HOLD_SECONDS = 1.25;
 export class XrExitButton extends Script {
   static scriptName = 'xrExitButton';
 
@@ -33,14 +37,19 @@ export class XrExitButton extends Script {
   _headPosition = new Vec3();
   _headRotation = new Quat();
   _worldOffset = new Vec3();
-  _faceButtonDown = new WeakMap();
+  _faceButtons = new FaceButtonPressTracker();
+  _drawnProgress = -1;
+  _hold = INITIAL_HOLD_STATE;
+  _arming = new ButtonArmingLatch();
   _isVrActive = () => this.app.xr?.active === true && this.app.xr?.type === XRTYPE_VR;
   _onXrStart = () => {
     this.entity.enabled = this._isVrActive();
+    this._resetProgress();
   };
   _onXrEnd = () => {
     this.entity.enabled = false;
     this._hovered = false;
+    this._resetProgress();
     this.entity.setLocalScale(1, 1, 1);
     if (this._material) {
       this._material.opacity = 0.9;
@@ -51,40 +60,25 @@ export class XrExitButton extends Script {
     if (!this.entity.enabled) {
       return;
     }
-    if (this._rayHitsButton(inputSource)) {
+    if (this.rayHitsButton(inputSource.getOrigin(), inputSource.getDirection())) {
       this.app.xr?.end();
     }
   };
-  _rayHitsButton(inputSource) {
-    return raySphereIntersect(inputSource.getOrigin(), inputSource.getDirection(), this.entity.getPosition(), this.hitRadius);
-  }
-  _faceButtonPressed(inputSource) {
-    const buttons = inputSource.gamepad?.buttons;
-    return buttons ? FACE_BUTTON_INDICES.some(index => buttons[index]?.pressed === true) : false;
+
+  /** True when the ray points at the button's hit sphere. False while the button entity is disabled. */
+  rayHitsButton(origin, direction) {
+    if (!this.entity.enabled) {
+      return false;
+    }
+    return raySphereIntersect(origin, direction, this.entity.getPosition(), this.hitRadius);
   }
-  _createTexture() {
+  _createCanvas() {
     const canvas = document.createElement('canvas');
     canvas.width = TEXTURE_SIZE;
     canvas.height = TEXTURE_SIZE;
-    const ctx = canvas.getContext('2d');
-    const c = TEXTURE_SIZE / 2;
-    if (ctx) {
-      ctx.clearRect(0, 0, TEXTURE_SIZE, TEXTURE_SIZE);
-      ctx.fillStyle = 'rgba(20, 20, 20, 0.75)';
-      ctx.beginPath();
-      ctx.arc(c, c, c * 0.92, 0, Math.PI * 2);
-      ctx.fill();
-      const arm = TEXTURE_SIZE * 0.24;
-      ctx.strokeStyle = '#ffffff';
-      ctx.lineWidth = TEXTURE_SIZE * 0.09;
-      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();
-    }
+    return canvas;
+  }
+  _createTexture(canvas) {
     const texture = new Texture(this.app.graphicsDevice, {
       name: 'xr-exit-button',
       width: TEXTURE_SIZE,
@@ -98,6 +92,56 @@ export class XrExitButton extends Script {
     texture.setSource(canvas);
     return texture;
   }
+
+  /**
+   * Repaints the button: dark disc, then the hold progress wedge, then the X arms on top so the
+   * glyph stays legible over the fill. The pie is skipped entirely at zero progress so the idle
+   * button doesn't wear the pie's faint track. Returns whether it painted, so callers can tell a
+   * missing context from a successful repaint.
+   */
+  _drawButton(progress) {
+    const ctx = this._context;
+    if (!ctx) {
+      return false;
+    }
+    const c = TEXTURE_SIZE / 2;
+    ctx.clearRect(0, 0, TEXTURE_SIZE, TEXTURE_SIZE);
+    ctx.fillStyle = 'rgba(20, 20, 20, 0.75)';
+    ctx.beginPath();
+    ctx.arc(c, c, c * 0.92, 0, Math.PI * 2);
+    ctx.fill();
+    if (progress > 0) {
+      drawProgressPie(ctx, TEXTURE_SIZE, progress);
+    }
+    const arm = TEXTURE_SIZE * 0.24;
+    ctx.strokeStyle = '#ffffff';
+    ctx.lineWidth = TEXTURE_SIZE * 0.09;
+    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();
+    this._texture?.upload();
+    return true;
+  }
+
+  /** Repaints only when the drawn wedge would visibly move. Only records the paint on success, so a
+   * missing context doesn't fool the dedupe cache into thinking a repaint already happened. */
+  _setProgress(progress) {
+    if (Math.abs(progress - this._drawnProgress) <= 0.001) {
+      return;
+    }
+    if (this._drawButton(progress)) {
+      this._drawnProgress = progress;
+    }
+  }
+  _resetProgress() {
+    this._hold = INITIAL_HOLD_STATE;
+    this._drawnProgress = -1;
+    this._setProgress(0);
+  }
   _createMesh() {
     const h = this.halfSize;
     const mesh = new Mesh(this.app.graphicsDevice);
@@ -109,7 +153,10 @@ export class XrExitButton extends Script {
     return mesh;
   }
   initialize() {
-    this._texture = this._createTexture();
+    this._canvas = this._createCanvas();
+    this._context = this._canvas.getContext('2d') ?? undefined;
+    this._texture = this._createTexture(this._canvas);
+    this._resetProgress();
     const material = new StandardMaterial();
     material.useLighting = false;
     material.emissive = new Color(1, 1, 1);
@@ -136,26 +183,38 @@ export class XrExitButton extends Script {
     this.app.xr?.on('end', this._onXrEnd);
     this.app.xr?.input?.on('select', this._onSelect);
   }
-  update() {
+  update(dt) {
     if (!this.entity.enabled) {
       return;
     }
     this._trackHead();
     const sources = this.app.xr?.input?.inputSources ?? [];
     let hovered = false;
+    let holdActive = false;
     for (const source of sources) {
-      const sourceHovers = this._rayHitsButton(source);
+      const sourceHovers = this.rayHitsButton(source.getOrigin(), source.getDirection());
       hovered = hovered || sourceHovers;
 
       // A face-button press exits only while that controller is aimed at the button, matching the
       // trigger. Edge-detected so holding a button and then aiming onto it doesn't fire.
-      const facePressed = this._faceButtonPressed(source);
-      const faceWasDown = this._faceButtonDown.get(source) ?? false;
-      this._faceButtonDown.set(source, facePressed);
-      if (sourceHovers && facePressed && !faceWasDown) {
+      const facePressed = this._faceButtons.justPressed(source);
+      if (sourceHovers && facePressed) {
         this.app.xr?.end();
         return;
       }
+
+      // Two statements, not `holdActive = holdActive || this._arming.trackPress(...)`: trackPress
+      // arms the source as a side effect and must run for every source every frame, but `||`
+      // short-circuits once holdActive is true and would skip arming later sources.
+      const armedPress = this._arming.trackPress(source, secondaryFaceButtonPressed(source));
+      holdActive = holdActive || armedPress;
+    }
+    const hold = advanceHold(this._hold, holdActive, dt, EXIT_HOLD_SECONDS);
+    this._hold = hold.state;
+    this._setProgress(hold.progress);
+    if (hold.justFired) {
+      this.app.xr?.end();
+      return;
     }
     if (hovered !== this._hovered) {
       this._hovered = hovered;
@@ -203,5 +262,7 @@ export class XrExitButton extends Script {
     this._mesh = undefined;
     this._material = undefined;
     this._texture = undefined;
+    this._canvas = undefined;
+    this._context = undefined;
   }
 }

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