@terraware/web-components 4.2.21 → 4.2.22

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

@@ -0,0 +1,29 @@
+import { Vec3 } from 'playcanvas';
+/**
+ * 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 const rayQuadHit = (origin, direction, center, right, up, halfWidth, halfHeight) => {
+  const dir = direction.clone().normalize();
+  const normal = new Vec3().cross(right, up);
+  const denom = dir.dot(normal);
+  if (Math.abs(denom) < 1e-6) {
+    return null;
+  }
+  const t = new Vec3().sub2(center, origin).dot(normal) / denom;
+  if (t < 0) {
+    return null;
+  }
+  const offset = new Vec3().copy(dir).mulScalar(t).add(origin).sub(center);
+  const u = offset.dot(right) / halfWidth;
+  const v = offset.dot(up) / halfHeight;
+  if (u < -1 || u > 1 || v < -1 || v > 1) {
+    return null;
+  }
+  return {
+    u,
+    v
+  };
+};

package/components/VirtualWalkthrough/xr-ray-quad.test.js

@@ -0,0 +1,37 @@
+import { Vec3 } from 'playcanvas';
+import { rayQuadHit } from './xr-ray-quad';
+const CENTER = new Vec3(0, 0, 0);
+const RIGHT = new Vec3(1, 0, 0);
+const UP = new Vec3(0, 1, 0);
+describe('rayQuadHit', () => {
+  it('hits the centre straight on', () => {
+    const hit = rayQuadHit(new Vec3(0, 0, 5), new Vec3(0, 0, -1), CENTER, RIGHT, UP, 1, 1);
+    expect(hit).not.toBeNull();
+    expect(hit?.u).toBeCloseTo(0, 5);
+    expect(hit?.v).toBeCloseTo(0, 5);
+  });
+  it('maps an off-centre hit to normalized quad coordinates', () => {
+    const hit = rayQuadHit(new Vec3(0.5, -0.25, 5), new Vec3(0, 0, -1), CENTER, RIGHT, UP, 1, 1);
+    expect(hit?.u).toBeCloseTo(0.5, 5);
+    expect(hit?.v).toBeCloseTo(-0.25, 5);
+  });
+  it('returns null when the hit falls outside the rectangle', () => {
+    expect(rayQuadHit(new Vec3(2, 0, 5), new Vec3(0, 0, -1), CENTER, RIGHT, UP, 1, 1)).toBeNull();
+  });
+  it('returns null for a ray parallel to the quad plane', () => {
+    expect(rayQuadHit(new Vec3(0, 0, 5), new Vec3(1, 0, 0), CENTER, RIGHT, UP, 1, 1)).toBeNull();
+  });
+  it('returns null when the quad is behind the ray origin', () => {
+    expect(rayQuadHit(new Vec3(0, 0, 5), new Vec3(0, 0, 1), CENTER, RIGHT, UP, 1, 1)).toBeNull();
+  });
+  it('respects half extents (scales u/v by them)', () => {
+    // half width 2: an x offset of 1 maps to u = 0.5.
+    const hit = rayQuadHit(new Vec3(1, 0, 5), new Vec3(0, 0, -1), CENTER, RIGHT, UP, 2, 1);
+    expect(hit?.u).toBeCloseTo(0.5, 5);
+  });
+  it('normalizes a non-unit ray direction', () => {
+    const hit = rayQuadHit(new Vec3(0, 0, 5), new Vec3(0, 0, -3), CENTER, RIGHT, UP, 1, 1);
+    expect(hit).not.toBeNull();
+    expect(hit?.u).toBeCloseTo(0, 5);
+  });
+});

package/components/VirtualWalkthrough/xr-scene-bounds.d.ts

@@ -0,0 +1,17 @@
+/** A world-space XZ point clamped into the bounds circle, and how far it had to move to get there. */
+export type ClampResult = {
+    x: number;
+    z: number;
+    distance: number;
+};
+/**
+ * Clamp a world-space XZ point into the circle of `radius` about (centerX, centerZ).
+ *
+ * `distance` is how far the point was moved and is 0 whenever the point was already inside, which
+ * callers use as the "was this clamped?" signal. A non-positive radius means "no bounds" and leaves
+ * the point untouched; so does a point at the exact center, which has no direction to project along.
+ */
+export declare const clampToCircle: (x: number, z: number, centerX: number, centerZ: number, radius: number) => ClampResult;
+/** Horizontal distance from a world-space XZ point to the circle's edge: negative inside, positive outside. */
+export declare const distanceToCircleEdge: (x: number, z: number, centerX: number, centerZ: number, radius: number) => number;
+//# sourceMappingURL=xr-scene-bounds.d.ts.map

package/components/VirtualWalkthrough/xr-scene-bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-scene-bounds.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-scene-bounds.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,MAAM,MAAM,WAAW,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,SAAS,MAAM,EAAE,SAAS,MAAM,EAAE,QAAQ,MAAM,KAAG,WAetG,CAAC;AAEF,+GAA+G;AAC/G,eAAO,MAAM,oBAAoB,GAC/B,GAAG,MAAM,EACT,GAAG,MAAM,EACT,SAAS,MAAM,EACf,SAAS,MAAM,EACf,QAAQ,MAAM,KACb,MAKF,CAAC"}

package/components/VirtualWalkthrough/xr-scene-bounds.js

@@ -0,0 +1,41 @@
+/** A world-space XZ point clamped into the bounds circle, and how far it had to move to get there. */
+
+/**
+ * Clamp a world-space XZ point into the circle of `radius` about (centerX, centerZ).
+ *
+ * `distance` is how far the point was moved and is 0 whenever the point was already inside, which
+ * callers use as the "was this clamped?" signal. A non-positive radius means "no bounds" and leaves
+ * the point untouched; so does a point at the exact center, which has no direction to project along.
+ */
+export const clampToCircle = (x, z, centerX, centerZ, radius) => {
+  if (radius <= 0) {
+    return {
+      x,
+      z,
+      distance: 0
+    };
+  }
+  const dx = x - centerX;
+  const dz = z - centerZ;
+  const dist = Math.sqrt(dx * dx + dz * dz);
+  if (dist <= radius) {
+    return {
+      x,
+      z,
+      distance: 0
+    };
+  }
+  const scale = radius / dist;
+  return {
+    x: centerX + dx * scale,
+    z: centerZ + dz * scale,
+    distance: dist - radius
+  };
+};
+
+/** Horizontal distance from a world-space XZ point to the circle's edge: negative inside, positive outside. */
+export const distanceToCircleEdge = (x, z, centerX, centerZ, radius) => {
+  const dx = x - centerX;
+  const dz = z - centerZ;
+  return Math.sqrt(dx * dx + dz * dz) - radius;
+};

package/components/VirtualWalkthrough/xr-scene-bounds.test.js

@@ -0,0 +1,70 @@
+import { clampToCircle, distanceToCircleEdge } from './xr-scene-bounds';
+describe('clampToCircle', () => {
+  it('leaves a point inside the circle untouched', () => {
+    expect(clampToCircle(1, 2, 0, 0, 5)).toEqual({
+      x: 1,
+      z: 2,
+      distance: 0
+    });
+  });
+  it('leaves a point exactly on the edge untouched', () => {
+    expect(clampToCircle(5, 0, 0, 0, 5)).toEqual({
+      x: 5,
+      z: 0,
+      distance: 0
+    });
+  });
+  it('projects a point outside back onto the edge', () => {
+    const result = clampToCircle(10, 0, 0, 0, 4);
+    expect(result.x).toBeCloseTo(4);
+    expect(result.z).toBeCloseTo(0);
+    expect(result.distance).toBeCloseTo(6);
+  });
+  it('projects along the line from the center, preserving direction', () => {
+    const result = clampToCircle(30, 40, 0, 0, 5);
+    expect(result.x).toBeCloseTo(3);
+    expect(result.z).toBeCloseTo(4);
+    expect(result.distance).toBeCloseTo(45);
+  });
+  it('respects an off-origin center', () => {
+    const result = clampToCircle(12, -3, 2, -3, 4);
+    expect(result.x).toBeCloseTo(6);
+    expect(result.z).toBeCloseTo(-3);
+    expect(result.distance).toBeCloseTo(6);
+  });
+  it('leaves a point at the exact center untouched rather than dividing by zero', () => {
+    const result = clampToCircle(2, -3, 2, -3, 4);
+    expect(result).toEqual({
+      x: 2,
+      z: -3,
+      distance: 0
+    });
+    expect(Number.isNaN(result.x)).toBe(false);
+  });
+  it('leaves the point untouched for a non-positive radius', () => {
+    expect(clampToCircle(10, 10, 0, 0, 0)).toEqual({
+      x: 10,
+      z: 10,
+      distance: 0
+    });
+    expect(clampToCircle(10, 10, 0, 0, -1)).toEqual({
+      x: 10,
+      z: 10,
+      distance: 0
+    });
+  });
+});
+describe('distanceToCircleEdge', () => {
+  it('is negative inside the circle', () => {
+    expect(distanceToCircleEdge(1, 0, 0, 0, 5)).toBeCloseTo(-4);
+  });
+  it('is zero on the edge', () => {
+    expect(distanceToCircleEdge(0, 5, 0, 0, 5)).toBeCloseTo(0);
+  });
+  it('is positive outside the circle', () => {
+    expect(distanceToCircleEdge(8, 0, 0, 0, 5)).toBeCloseTo(3);
+  });
+  it('respects an off-origin center', () => {
+    expect(distanceToCircleEdge(2, 9, 2, 3, 4)).toBeCloseTo(2);
+  });
+});

package/components/VirtualWalkthrough/xr-teleport-gesture.d.ts

@@ -0,0 +1,30 @@
+import { XrInputSource } from 'playcanvas';
+/** Per-frame aim state for one input source, sampled while its select gesture is in progress. */
+export interface TeleportGestureFrame {
+    pressed: boolean;
+    teleportDisabled: boolean;
+    uiBlocked: boolean;
+}
+/**
+ * Decides whether the select gesture that just ended is allowed to teleport. The two reasons to
+ * refuse have deliberately different lifetimes:
+ *
+ * - `teleportDisabled` latches for the rest of the press. The React flag behind it re-enables as
+ *   soon as the select dismisses the panel, which can land before the selectend that ends the press.
+ * - `uiBlocked` keeps only the newest frame, because that frame is the one whose arc hit the base
+ *   script has cached and would commit on release. Re-deciding from the release-time ray instead
+ *   would let a flick off the UI commit a target that was aimed while over it, and latching the
+ *   whole press would refuse an aim that merely swept across UI before coming to rest on floor.
+ *
+ * Callers must poll every frame for every source they care about; a press and release between polls
+ * is missed.
+ */
+export declare class TeleportGestureLatch {
+    private _teleportDisabled;
+    private _uiBlocked;
+    /** Records a frame of an in-progress press. A source that isn't pressed drops both latches. */
+    track(inputSource: XrInputSource, frame: TeleportGestureFrame): void;
+    /** True when the press may not teleport. Clears both latches so they never outlive the press. */
+    consumeBlocked(inputSource: XrInputSource): boolean;
+}
+//# sourceMappingURL=xr-teleport-gesture.d.ts.map

package/components/VirtualWalkthrough/xr-teleport-gesture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-teleport-gesture.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-teleport-gesture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,iGAAiG;AACjG,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,iBAAiB,CAAgC;IACzD,OAAO,CAAC,UAAU,CAAgC;IAElD,+FAA+F;IAC/F,KAAK,CAAC,WAAW,EAAE,aAAa,EAAE,KAAK,EAAE,oBAAoB;IAmB7D,iGAAiG;IACjG,cAAc,CAAC,WAAW,EAAE,aAAa,GAAG,OAAO;CAOpD"}

package/components/VirtualWalkthrough/xr-teleport-gesture.js

@@ -0,0 +1,45 @@
+/** Per-frame aim state for one input source, sampled while its select gesture is in progress. */
+
+/**
+ * Decides whether the select gesture that just ended is allowed to teleport. The two reasons to
+ * refuse have deliberately different lifetimes:
+ *
+ * - `teleportDisabled` latches for the rest of the press. The React flag behind it re-enables as
+ *   soon as the select dismisses the panel, which can land before the selectend that ends the press.
+ * - `uiBlocked` keeps only the newest frame, because that frame is the one whose arc hit the base
+ *   script has cached and would commit on release. Re-deciding from the release-time ray instead
+ *   would let a flick off the UI commit a target that was aimed while over it, and latching the
+ *   whole press would refuse an aim that merely swept across UI before coming to rest on floor.
+ *
+ * Callers must poll every frame for every source they care about; a press and release between polls
+ * is missed.
+ */
+export class TeleportGestureLatch {
+  _teleportDisabled = new WeakSet();
+  _uiBlocked = new WeakSet();
+
+  /** Records a frame of an in-progress press. A source that isn't pressed drops both latches. */
+  track(inputSource, frame) {
+    if (!frame.pressed) {
+      this._teleportDisabled.delete(inputSource);
+      this._uiBlocked.delete(inputSource);
+      return;
+    }
+    if (frame.teleportDisabled) {
+      this._teleportDisabled.add(inputSource);
+    }
+    if (frame.uiBlocked) {
+      this._uiBlocked.add(inputSource);
+    } else {
+      this._uiBlocked.delete(inputSource);
+    }
+  }
+
+  /** True when the press may not teleport. Clears both latches so they never outlive the press. */
+  consumeBlocked(inputSource) {
+    const blocked = this._teleportDisabled.has(inputSource) || this._uiBlocked.has(inputSource);
+    this._teleportDisabled.delete(inputSource);
+    this._uiBlocked.delete(inputSource);
+    return blocked;
+  }
+}

package/components/VirtualWalkthrough/xr-teleport-gesture.test.js

@@ -0,0 +1,90 @@
+import { TeleportGestureLatch } from './xr-teleport-gesture';
+const source = () => ({});
+
+/** An ordinary aiming frame: pressed, teleport on, ray clear of interactive UI. */
+const AIMING = {
+  pressed: true,
+  teleportDisabled: false,
+  uiBlocked: false
+};
+describe('TeleportGestureLatch', () => {
+  it('allows a press that never aimed at UI', () => {
+    const latch = new TeleportGestureLatch();
+    const src = source();
+    latch.track(src, AIMING);
+    latch.track(src, AIMING);
+    expect(latch.consumeBlocked(src)).toBe(false);
+  });
+  it('blocks a press whose last aiming frame was over UI, even after the ray leaves on release', () => {
+    const latch = new TeleportGestureLatch();
+    const src = source();
+    latch.track(src, {
+      ...AIMING,
+      uiBlocked: true
+    });
+
+    // The release-time ray no longer hits the UI, but the cached arc hit is from the frame above.
+    expect(latch.consumeBlocked(src)).toBe(true);
+  });
+  it('allows a press that swept across UI but came to rest on open floor', () => {
+    const latch = new TeleportGestureLatch();
+    const src = source();
+    latch.track(src, AIMING);
+    latch.track(src, {
+      ...AIMING,
+      uiBlocked: true
+    });
+    latch.track(src, AIMING);
+    expect(latch.consumeBlocked(src)).toBe(false);
+  });
+  it('latches a teleport-disabled frame for the rest of the press', () => {
+    const latch = new TeleportGestureLatch();
+    const src = source();
+    latch.track(src, {
+      ...AIMING,
+      teleportDisabled: true
+    });
+    latch.track(src, AIMING);
+    expect(latch.consumeBlocked(src)).toBe(true);
+  });
+  it('clears the latches once consumed, so the next press starts clean', () => {
+    const latch = new TeleportGestureLatch();
+    const src = source();
+    latch.track(src, {
+      pressed: true,
+      teleportDisabled: true,
+      uiBlocked: true
+    });
+    expect(latch.consumeBlocked(src)).toBe(true);
+    latch.track(src, AIMING);
+    expect(latch.consumeBlocked(src)).toBe(false);
+  });
+  it('drops latches from a press that ended without being consumed', () => {
+    const latch = new TeleportGestureLatch();
+    const src = source();
+    latch.track(src, {
+      pressed: true,
+      teleportDisabled: true,
+      uiBlocked: true
+    });
+    latch.track(src, {
+      pressed: false,
+      teleportDisabled: true,
+      uiBlocked: true
+    });
+    latch.track(src, AIMING);
+    expect(latch.consumeBlocked(src)).toBe(false);
+  });
+  it('tracks each input source independently', () => {
+    const latch = new TeleportGestureLatch();
+    const left = source();
+    const right = source();
+    latch.track(left, {
+      ...AIMING,
+      uiBlocked: true
+    });
+    latch.track(right, AIMING);
+    expect(latch.consumeBlocked(right)).toBe(false);
+    expect(latch.consumeBlocked(left)).toBe(true);
+  });
+});

package/hooks/useXr.d.ts

@@ -7,6 +7,8 @@ export declare const useXr: ({ onError }?: UseXrOptions) => {
     startXr: (type: XrType) => void;
     endXr: () => void;
     isCurrentlyInXr: boolean;
+    isCurrentlyInAr: boolean;
+    isCurrentlyInVr: boolean;
 };
 export default useXr;
 //# sourceMappingURL=useXr.d.ts.map

package/hooks/useXr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useXr.d.ts","sourceRoot":"","sources":["../../src/hooks/useXr.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;AAEjC,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAOD,eAAO,MAAM,KAAK,GAAI,cAAa,YAAiB;0BA0CT,MAAM;oBAGtC,MAAM;;;CAsBhB,CAAC;AAEF,eAAe,KAAK,CAAC"}
+{"version":3,"file":"useXr.d.ts","sourceRoot":"","sources":["../../src/hooks/useXr.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;AAEjC,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAOD,eAAO,MAAM,KAAK,GAAI,cAAa,YAAiB;0BA4CT,MAAM;oBAGtC,MAAM;;;;;CA6BhB,CAAC;AAEF,eAAe,KAAK,CAAC"}

package/hooks/useXr.js

@@ -13,7 +13,8 @@ export const useXr = ({
     VR: false,
     AR: false
   });
-  const [isCurrentlyInXr, setIsCurrentlyInXr] = useState(app.xr?.active ?? false);
+  // `type` is set as soon as a session is requested, so gate on `active` to ignore pending sessions.
+  const [currentXrType, setCurrentXrType] = useState(app.xr?.active ? app.xr.type : null);
   useEffect(() => {
     // We subscribe to the manager directly because `app` doesn't update when XR's availability changes.
     const handleAvailable = (type, isAvailable) => {
@@ -39,9 +40,10 @@ export const useXr = ({
     };
   }, [app]);
   useEffect(() => {
-    const handleStart = () => setIsCurrentlyInXr(true);
-    const handleEnd = () => setIsCurrentlyInXr(false);
-    setIsCurrentlyInXr(app.xr?.active ?? false);
+    const handleStart = () => setCurrentXrType(app.xr?.type ?? null);
+    // `app.xr.type` isn't cleared until after the `end` event fires, so don't read it here.
+    const handleEnd = () => setCurrentXrType(null);
+    setCurrentXrType(app.xr?.active ? app.xr.type : null);
     app.xr?.on('start', handleStart);
     app.xr?.on('end', handleEnd);
     return () => {
@@ -68,7 +70,9 @@ export const useXr = ({
     isXrAvailable,
     startXr,
     endXr,
-    isCurrentlyInXr
-  }), [isXrAvailable, startXr, endXr, isCurrentlyInXr]);
+    isCurrentlyInXr: currentXrType !== null,
+    isCurrentlyInAr: currentXrType === XRTYPE_AR,
+    isCurrentlyInVr: currentXrType === XRTYPE_VR
+  }), [isXrAvailable, startXr, endXr, currentXrType]);
 };
 export default useXr;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terraware/web-components",
-  "version": "4.2.21",
+  "version": "4.2.22",
   "author": "Terraformation Inc.",
   "license": "Apache-2.0",
   "repository": {