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

package/components/VirtualWalkthrough/Annotation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Annotation.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/Annotation.tsx"],"names":[],"mappings":"AAUA,OAAO,yBAAyB,CAAC;AAEjC,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAS5D,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;IAChE,MAAM,CAAC,EAAE,CAAC,UAAU,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjF,sBAAsB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACnG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,QAAA,MAAM,UAAU,GAAI,OAAO,eAAe,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,4CAiL7D,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"Annotation.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/Annotation.tsx"],"names":[],"mappings":"AAUA,OAAO,yBAAyB,CAAC;AAEjC,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAS5D,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;IAChE,MAAM,CAAC,EAAE,CAAC,UAAU,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjF,sBAAsB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACnG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,QAAA,MAAM,UAAU,GAAI,OAAO,eAAe,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,4CA2L7D,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/components/VirtualWalkthrough/Annotation.js

@@ -101,6 +101,15 @@ const Annotation = props => {
     }
   }, [setCamera]);
 
+  // VR open path: shows the annotation without moving the camera (roomscale head pose
+  // comes from the XR views, so a camera move would be disorienting or a no-op).
+  const handleVrOpen = useCallback((screenX, screenY) => {
+    if (isEditRef.current) {
+      return;
+    }
+    onViewRef.current?.(annotationForViewRef.current, screenX, screenY);
+  }, []);
+
   // Stable callback so its identity doesn't churn the underlying script prop each frame.
   const handleScreenPositionUpdate = useCallback((screenX, screenY, size) => {
     onScreenPositionUpdateRef.current?.(index, screenX, screenY, size);
@@ -190,6 +199,7 @@ const Annotation = props => {
       text: bodyText,
       enabled: visible,
       onClickCallback: handleClick,
+      onVrOpenCallback: handleVrOpen,
       onScreenPositionUpdateCallback: isViewed ? handleScreenPositionUpdate : undefined
     })
   });

package/components/VirtualWalkthrough/BoundaryWall.d.ts

@@ -0,0 +1,11 @@
+import { Vec3 } from 'playcanvas';
+export type BoundaryWallProps = {
+    /** World-space, i.e. already multiplied by the scene scaleFactor. */
+    center: Vec3;
+    radius: number;
+    groundPlane: Vec3[];
+    baseY: number;
+};
+declare const BoundaryWall: ({ center, radius, groundPlane, baseY }: BoundaryWallProps) => import("react/jsx-runtime").JSX.Element;
+export default BoundaryWall;
+//# sourceMappingURL=BoundaryWall.d.ts.map

package/components/VirtualWalkthrough/BoundaryWall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BoundaryWall.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/BoundaryWall.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAIlC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,qEAAqE;IACrE,MAAM,EAAE,IAAI,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,IAAI,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,QAAA,MAAM,YAAY,GAAI,wCAAwC,iBAAiB,4CAuB9E,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/components/VirtualWalkthrough/BoundaryWall.js

@@ -0,0 +1,35 @@
+import React, { useEffect } from 'react';
+import { Entity } from '@playcanvas/react';
+import { Script } from '@playcanvas/react/components';
+import { useApp } from '@playcanvas/react/hooks';
+import { BoundaryWallScript } from './boundary-wall';
+import { jsx as _jsx } from "react/jsx-runtime";
+const BoundaryWall = ({
+  center,
+  radius,
+  groundPlane,
+  baseY
+}) => {
+  const app = useApp();
+  useEffect(() => {
+    // Set imperatively rather than via reactive Script props. @playcanvas/react wraps Script
+    // in memo() whose shallowEquals returns early on the first prop with a .equals() method
+    // (Vec3), so any prop after a Vec3 is never compared and would not propagate.
+    // @ts-expect-error - scripts are added dynamically to the entity
+    const script = app.root.findByName('boundary-wall')?.script?.boundaryWall;
+    if (script) {
+      script.center = center;
+      script.radius = radius;
+      script.groundPlane = groundPlane;
+      script.baseY = baseY;
+      script.rebuild();
+    }
+  }, [app, center, radius, groundPlane, baseY]);
+  return /*#__PURE__*/_jsx(Entity, {
+    name: "boundary-wall",
+    children: /*#__PURE__*/_jsx(Script, {
+      script: BoundaryWallScript
+    })
+  });
+};
+export default BoundaryWall;

package/components/VirtualWalkthrough/SplatModel.d.ts

@@ -1,13 +1,6 @@
 import React from 'react';
-import { SplatFormat } from './splatFormat';
 export interface SplatModelProps {
     splatSrc: string;
-    /**
-     * Splat format of `splatSrc`. Inferred from the URL when omitted, which covers bundled `.sog`,
-     * unbundled sog (`meta.json`), streamed LOD sog (`lod-meta.json`) and `.ply` sources. Set this
-     * explicitly when the URL hides the filename.
-     */
-    splatFormat?: SplatFormat;
     rotation?: [number, number, number];
     cropAabbMin?: [number, number, number];
     cropAabbMax?: [number, number, number];
@@ -17,6 +10,6 @@ export interface SplatModelProps {
     revealRain?: boolean;
     onError?: (error: Error) => void;
 }
-declare const _default: React.MemoExoticComponent<({ splatSrc, splatFormat, rotation, cropAabbMin, cropAabbMax, cropEdgeScaleFactor, cropFade, cropFadeDistance, revealRain, onError, }: SplatModelProps) => import("react/jsx-runtime").JSX.Element | null>;
+declare const _default: React.MemoExoticComponent<({ splatSrc, rotation, cropAabbMin, cropAabbMax, cropEdgeScaleFactor, cropFade, cropFadeDistance, revealRain, onError, }: SplatModelProps) => import("react/jsx-runtime").JSX.Element | null>;
 export default _default;
 //# sourceMappingURL=SplatModel.d.ts.map

package/components/VirtualWalkthrough/SplatModel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SplatModel.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/SplatModel.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA0B,MAAM,OAAO,CAAC;AAU/C,OAAO,EAAE,WAAW,EAA0C,MAAM,eAAe,CAAC;AAEpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;yLAaE,eAAe;AAkClB,wBAAgC"}
+{"version":3,"file":"SplatModel.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/SplatModel.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA0B,MAAM,OAAO,CAAC;AAW/C,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;4KAYE,eAAe;AAgClB,wBAAgC"}

package/components/VirtualWalkthrough/SplatModel.js

@@ -6,11 +6,9 @@ import BlockingSpinner from './BlockingSpinner';
 import SplatCrop from './SplatCrop';
 import SplatFadeCrop from './SplatFadeCrop';
 import SplatRevealRain from './SplatRevealRain';
-import { detectSplatFormat, splatLoaderFilename } from './splatFormat';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const SplatModel = ({
   splatSrc,
-  splatFormat,
   rotation,
   cropAabbMin,
   cropAabbMax,
@@ -20,16 +18,14 @@ const SplatModel = ({
   revealRain = false,
   onError
 }) => {
-  // The loader selects its parser from this filename rather than from splatSrc, so it has to name the
-  // format we are actually loading. See splatFormat.ts.
-  const filename = splatLoaderFilename(splatFormat ?? detectSplatFormat(splatSrc));
+  // A filename is required for the file props to assist with the asset loading. Otherwise it assumes that the splatSrc is a ply file.
   const {
     asset,
     loading,
     error
   } = useSplat(splatSrc, {
     file: {
-      filename
+      filename: 'model.sog'
     }
   });
   useEffect(() => {

package/components/VirtualWalkthrough/TfXrNavigation.d.ts

@@ -1,15 +1,51 @@
+import { Vec3, XrInputSource } from 'playcanvas';
 import { XrNavigation as PcXrNavigation } from 'playcanvas/scripts/esm/xr/xr-navigation.mjs';
 /**
- * Extended XrNavigation that fixes the bug where tryTeleport doesn't respect
- * the enableTeleport flag setting.
+ * XrNavigation that never teleports on a select meant for something else: it honours the
+ * enableTeleport flag (which the base ignores in tryTeleport) and skips sources whose ray is over
+ * interactive UI.
  */
 export declare class TfXrNavigation extends PcXrNavigation {
     static scriptName: string;
+    /** Assigned by the React wrapper. True when this source's ray is over interactive UI. */
+    isTeleportBlocked?: (inputSource: XrInputSource) => boolean;
     /**
-     * Override tryTeleport to respect the enableTeleport flag.
-     * The base implementation is always called from handleSelectEnd,
-     * but we only want to teleport when enableTeleport is true.
+     * World-space bounds circle. Assigned by the React wrapper rather than passed as a Script prop:
+     * boundsCenter is a Vec3, and @playcanvas/react's memo() comparator stops at the first prop with
+     * an .equals() method, so any prop after it would never propagate.
+     * A boundsRadius of 0 disables clamping entirely.
      */
-    tryTeleport(inputSource: any): void;
+    boundsCenter: Vec3;
+    boundsRadius: number;
+    /** How far the rig was pulled back in the last postUpdate to keep the head inside the bounds. */
+    clampDistance: number;
+    private _gestures;
+    private _isBlocked;
+    tryTeleport(inputSource: XrInputSource): void;
+    update(dt: number): void;
+    /**
+     * Holds the head inside the bounds circle. Runs in postUpdate, after PlayCanvas has written this
+     * frame's head pose into the camera's local transform (xr.update runs before app.update) and after
+     * the base script's locomotion, so one clamp covers every way the head can move: thumbstick
+     * translation of the rig, room-scale walking within the rig, and snap turns pivoting the rig.
+     *
+     * This script must stay a no-op outside XR regardless of how it's mounted.
+     */
+    postUpdate(): void;
+    /**
+     * Clamps the teleport landing point to the bounds circle. Overriding here rather than in
+     * tryTeleport covers both paths that produce a landing point — the per-frame aim in
+     * _handleTeleportation and tryTeleport's own recompute when no hit is cached — and because
+     * _handleTeleportation positions the landing ring from this same record immediately afterwards,
+     * the ring previews the clamped destination without any extra work.
+     *
+     * Only valid hits are clamped: when the base finds no hit it leaves rec.point holding a stale
+     * value from an earlier frame, which must not be projected onto the circle and shown as a target.
+     * Clamping only ever shortens the throw, so a hit that passed the base's distance check still does.
+     */
+    _computeArcHit(origin: Vec3, direction: Vec3, rec: {
+        point: Vec3;
+        valid: boolean;
+    }): void;
 }
 //# sourceMappingURL=TfXrNavigation.d.ts.map

package/components/VirtualWalkthrough/TfXrNavigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TfXrNavigation.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/TfXrNavigation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,IAAI,cAAc,EAAE,MAAM,6CAA6C,CAAC;AAE7F;;;GAGG;AACH,qBAAa,cAAe,SAAQ,cAAc;IAChD,MAAM,CAAC,UAAU,SAAoB;IAErC;;;;OAIG;IACH,WAAW,CAAC,WAAW,EAAE,GAAG;CAS7B"}
+{"version":3,"file":"TfXrNavigation.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/TfXrNavigation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,IAAI,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,YAAY,IAAI,cAAc,EAAE,MAAM,6CAA6C,CAAC;AAkB7F;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,cAAc;IAChD,MAAM,CAAC,UAAU,SAAoB;IAErC,yFAAyF;IACzF,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,aAAa,KAAK,OAAO,CAAC;IAE5D;;;;;OAKG;IACH,YAAY,OAAc;IAC1B,YAAY,SAAK;IAEjB,iGAAiG;IACjG,aAAa,SAAK;IAElB,OAAO,CAAC,SAAS,CAA8B;IAE/C,OAAO,CAAC,UAAU;IAIlB,WAAW,CAAC,WAAW,EAAE,aAAa;IAYtC,MAAM,CAAC,EAAE,EAAE,MAAM;IAmCjB;;;;;;;OAOG;IACH,UAAU;IAoBV;;;;;;;;;;OAUG;IACH,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE;CAkBnF"}

package/components/VirtualWalkthrough/TfXrNavigation.js

@@ -1,24 +1,124 @@
+import { Vec3 } from 'playcanvas';
 import { XrNavigation as PcXrNavigation } from 'playcanvas/scripts/esm/xr/xr-navigation.mjs';
+import { clampToCircle } from './xr-scene-bounds';
+import { TeleportGestureLatch } from './xr-teleport-gesture';
+
+/** The base script's per-source aim state, which it exposes only as underscore-private fields. */
 
 /**
- * Extended XrNavigation that fixes the bug where tryTeleport doesn't respect
- * the enableTeleport flag setting.
+ * XrNavigation that never teleports on a select meant for something else: it honours the
+ * enableTeleport flag (which the base ignores in tryTeleport) and skips sources whose ray is over
+ * interactive UI.
  */
 export class TfXrNavigation extends PcXrNavigation {
   static scriptName = 'tfXrNavigation';
 
+  /** Assigned by the React wrapper. True when this source's ray is over interactive UI. */
+
   /**
-   * Override tryTeleport to respect the enableTeleport flag.
-   * The base implementation is always called from handleSelectEnd,
-   * but we only want to teleport when enableTeleport is true.
+   * World-space bounds circle. Assigned by the React wrapper rather than passed as a Script prop:
+   * boundsCenter is a Vec3, and @playcanvas/react's memo() comparator stops at the first prop with
+   * an .equals() method, so any prop after it would never propagate.
+   * A boundsRadius of 0 disables clamping entirely.
    */
+  boundsCenter = new Vec3();
+  boundsRadius = 0;
+
+  /** How far the rig was pulled back in the last postUpdate to keep the head inside the bounds. */
+  clampDistance = 0;
+  _gestures = new TeleportGestureLatch();
+  _isBlocked(inputSource) {
+    return !this.enableTeleport || this.isTeleportBlocked?.(inputSource) === true;
+  }
   tryTeleport(inputSource) {
-    // Only proceed with teleportation if enableTeleport is true
-    if (!this.enableTeleport) {
+    // The latch decides on the frames the press actually aimed through, because super.tryTeleport
+    // commits the arc hit cached back then rather than re-tracing the release-time ray. The live
+    // check stays too: the same release also fires 'select', so a ray that lands on UI at release
+    // is operating that UI and must not move the rig as well.
+    if (this._gestures.consumeBlocked(inputSource) || this._isBlocked(inputSource)) {
       return;
     }
-
-    // Call the parent implementation
     super.tryTeleport(inputSource);
   }
+  update(dt) {
+    super.update(dt);
+    const internals = this;
+    for (const inputSource of internals._inputSources) {
+      // Sampled once per source per frame: isTeleportBlocked ray-tests every hotspot.
+      const uiBlocked = this.isTeleportBlocked?.(inputSource) === true;
+
+      // Tracked unconditionally, and before the arc-hiding work below. super.update has just cached
+      // this frame's arc hit, which is what a release would commit, so the latch has to see the same
+      // frame. A source that isn't pressed carries no gesture, so any stale entry from a press that
+      // ended while teleport was disabled (skipping tryTeleport entirely) is dropped here rather
+      // than leaking into the source's next press.
+      this._gestures.track(inputSource, {
+        pressed: internals._activePointers.get(inputSource) === true,
+        teleportDisabled: !this.enableTeleport,
+        uiBlocked
+      });
+
+      // The base hides the arc only from inside its own teleport handling, which it skips entirely
+      // once teleport is off - so an arc raised before the block (gaze dwell can open a panel while
+      // the trigger is held) would otherwise stay frozen in the world. These writes are idempotent,
+      // and the base re-enables the visuals itself on the first frame a source is unblocked.
+      const visual = internals._arcVisuals.get(inputSource);
+      if (!visual || !visual.entity.enabled && !visual.ringEntity.enabled) {
+        continue;
+      }
+      if (!this.enableTeleport || uiBlocked) {
+        visual.entity.enabled = false;
+        visual.ringEntity.enabled = false;
+      }
+    }
+  }
+
+  /**
+   * Holds the head inside the bounds circle. Runs in postUpdate, after PlayCanvas has written this
+   * frame's head pose into the camera's local transform (xr.update runs before app.update) and after
+   * the base script's locomotion, so one clamp covers every way the head can move: thumbstick
+   * translation of the rig, room-scale walking within the rig, and snap turns pivoting the rig.
+   *
+   * This script must stay a no-op outside XR regardless of how it's mounted.
+   */
+  postUpdate() {
+    this.clampDistance = 0;
+    const camera = this._cameraEntity;
+    if (!this.app.xr?.active || !camera || this.boundsRadius <= 0) {
+      return;
+    }
+    const head = camera.getPosition();
+    const clamped = clampToCircle(head.x, head.z, this.boundsCenter.x, this.boundsCenter.z, this.boundsRadius);
+    if (clamped.distance === 0) {
+      return;
+    }
+
+    // World-space translate, not translateLocal: a snap turn has yawed the rig, so a local-space
+    // correction would be rotated away from the direction the head actually overshot.
+    this.entity.translate(clamped.x - head.x, 0, clamped.z - head.z);
+    this.clampDistance = clamped.distance;
+  }
+
+  /**
+   * Clamps the teleport landing point to the bounds circle. Overriding here rather than in
+   * tryTeleport covers both paths that produce a landing point — the per-frame aim in
+   * _handleTeleportation and tryTeleport's own recompute when no hit is cached — and because
+   * _handleTeleportation positions the landing ring from this same record immediately afterwards,
+   * the ring previews the clamped destination without any extra work.
+   *
+   * Only valid hits are clamped: when the base finds no hit it leaves rec.point holding a stale
+   * value from an earlier frame, which must not be projected onto the circle and shown as a target.
+   * Clamping only ever shortens the throw, so a hit that passed the base's distance check still does.
+   */
+  _computeArcHit(origin, direction, rec) {
+    super._computeArcHit(origin, direction, rec);
+    if (!rec.valid || this.boundsRadius <= 0) {
+      return;
+    }
+
+    // Y is left alone: it is the navigation plane height, and bounds are XZ-only.
+    const clamped = clampToCircle(rec.point.x, rec.point.z, this.boundsCenter.x, this.boundsCenter.z, this.boundsRadius);
+    rec.point.x = clamped.x;
+    rec.point.z = clamped.z;
+  }
 }

package/components/VirtualWalkthrough/TfXrNavigation.test.js

@@ -0,0 +1,110 @@
+import { Vec3 } from 'playcanvas';
+
+// The real base script is an .mjs file that Jest's default CRA transform config never transforms
+// (node_modules is excluded), so importing it directly fails to parse. TfXrNavigation.postUpdate
+// never calls into the base class, so a stub with no behaviour is enough to satisfy `extends`.
+jest.mock('playcanvas/scripts/esm/xr/xr-navigation.mjs', () => ({
+  XrNavigation: class {}
+}));
+import { TfXrNavigation } from './TfXrNavigation';
+const BOUNDS_CENTER = new Vec3(2, 0, 3);
+const BOUNDS_RADIUS = 5;
+const makeNavigation = options => {
+  const translate = jest.fn();
+  const navigation = Object.create(TfXrNavigation.prototype);
+  navigation.boundsCenter = BOUNDS_CENTER.clone();
+  navigation.boundsRadius = options.boundsRadius;
+  navigation.clampDistance = 0;
+  navigation.app = {
+    xr: {
+      active: options.xrActive
+    }
+  };
+  navigation.entity = {
+    translate
+  };
+  Object.assign(navigation, {
+    _cameraEntity: {
+      getPosition: () => options.head
+    }
+  });
+  return {
+    navigation,
+    translate
+  };
+};
+describe('TfXrNavigation.postUpdate', () => {
+  it('does not clamp when there is no active XR session, even with the head far outside the circle', () => {
+    const {
+      navigation,
+      translate
+    } = makeNavigation({
+      xrActive: false,
+      boundsRadius: BOUNDS_RADIUS,
+      head: new Vec3(1000, 1.5, 1000)
+    });
+    navigation.postUpdate();
+    expect(translate).not.toHaveBeenCalled();
+    expect(navigation.clampDistance).toBe(0);
+  });
+  it('does not clamp when boundsRadius is 0', () => {
+    const {
+      navigation,
+      translate
+    } = makeNavigation({
+      xrActive: true,
+      boundsRadius: 0,
+      head: new Vec3(1000, 1.5, 1000)
+    });
+    navigation.postUpdate();
+    expect(translate).not.toHaveBeenCalled();
+    expect(navigation.clampDistance).toBe(0);
+  });
+  it('does not clamp when the head is inside the circle', () => {
+    const {
+      navigation,
+      translate
+    } = makeNavigation({
+      xrActive: true,
+      boundsRadius: BOUNDS_RADIUS,
+      head: new Vec3(3, 1.5, 4)
+    });
+    navigation.postUpdate();
+    expect(translate).not.toHaveBeenCalled();
+    expect(navigation.clampDistance).toBe(0);
+  });
+  it('pulls the rig back and records the overshoot when the head is outside the circle in an active session', () => {
+    const {
+      navigation,
+      translate
+    } = makeNavigation({
+      xrActive: true,
+      boundsRadius: BOUNDS_RADIUS,
+      head: new Vec3(10, 1.5, 3)
+    });
+    navigation.postUpdate();
+    expect(translate).toHaveBeenCalledTimes(1);
+    expect(translate).toHaveBeenCalledWith(-3, 0, 0);
+    expect(navigation.clampDistance).toBe(3);
+  });
+  it('does not latch clampDistance across frames', () => {
+    const {
+      navigation,
+      translate
+    } = makeNavigation({
+      xrActive: true,
+      boundsRadius: BOUNDS_RADIUS,
+      head: new Vec3(10, 1.5, 3)
+    });
+    navigation.postUpdate();
+    expect(navigation.clampDistance).toBe(3);
+    Object.assign(navigation, {
+      _cameraEntity: {
+        getPosition: () => new Vec3(3, 1.5, 4)
+      }
+    });
+    navigation.postUpdate();
+    expect(translate).toHaveBeenCalledTimes(1);
+    expect(navigation.clampDistance).toBe(0);
+  });
+});

package/components/VirtualWalkthrough/VirtualWalkthroughViewer.d.ts

@@ -1,9 +1,7 @@
 import { AnnotationProps } from './Annotation';
 import { SplatControlsStrings } from './SplatControls';
-import { SplatFormat } from './splatFormat';
 export interface VirtualWalkthroughViewerProps {
     splatSrc: string;
-    splatFormat?: SplatFormat;
     origin?: [number, number, number];
     cameraPosition?: [number, number, number];
     sceneBounds?: {
@@ -26,6 +24,6 @@ export interface VirtualWalkthroughViewerProps {
     onToggleFullScreen?: () => void;
     maxImagesPerAnnotation?: number;
 }
-declare const VirtualWalkthroughViewer: ({ splatSrc, splatFormat, origin, cameraPosition, sceneBounds, groundPlane: groundPlaneProp, skyColor, groundColor, averageCameraHeight, scaleFactor, annotations, onSaveAnnotations, strings, editable, showFreeFly, isFullScreen, onToggleFullScreen, maxImagesPerAnnotation, }: VirtualWalkthroughViewerProps) => import("react/jsx-runtime").JSX.Element;
+declare const VirtualWalkthroughViewer: ({ splatSrc, origin, cameraPosition, sceneBounds, groundPlane: groundPlaneProp, skyColor, groundColor, averageCameraHeight, scaleFactor, annotations, onSaveAnnotations, strings, editable, showFreeFly, isFullScreen, onToggleFullScreen, maxImagesPerAnnotation, }: VirtualWalkthroughViewerProps) => import("react/jsx-runtime").JSX.Element;
 export default VirtualWalkthroughViewer;
 //# sourceMappingURL=VirtualWalkthroughViewer.d.ts.map

package/components/VirtualWalkthrough/VirtualWalkthroughViewer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VirtualWalkthroughViewer.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/VirtualWalkthroughViewer.tsx"],"names":[],"mappings":"AAYA,OAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAK3D,OAAsB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAKtE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAM5C,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,WAAW,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,iBAAiB,EAAE,CAAC,WAAW,EAAE,eAAe,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,OAAO,EAAE,oBAAoB,CAAC;IAC9B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,QAAA,MAAM,wBAAwB,GAAI,kRAmB/B,6BAA6B,4CAmU/B,CAAC;AAEF,eAAe,wBAAwB,CAAC"}
+{"version":3,"file":"VirtualWalkthroughViewer.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/VirtualWalkthroughViewer.tsx"],"names":[],"mappings":"AAYA,OAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAM3D,OAAsB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAqBtE,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,WAAW,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,iBAAiB,EAAE,CAAC,WAAW,EAAE,eAAe,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,OAAO,EAAE,oBAAoB,CAAC;IAC9B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,QAAA,MAAM,wBAAwB,GAAI,qQAkB/B,6BAA6B,4CA+W/B,CAAC;AAEF,eAAe,wBAAwB,CAAC"}

package/components/VirtualWalkthrough/VirtualWalkthroughViewer.js

@@ -12,19 +12,30 @@ import Annotation from './Annotation';
 import AnnotationPanel from './AnnotationPanel';
 import { AutoRotator } from './AutoRotator';
 import BoundaryRing from './BoundaryRing';
+import BoundaryWall from './BoundaryWall';
 import GradientSky from './GradientSky';
 import SplatControls from './SplatControls';
 import SplatModel from './SplatModel';
 import { TfAnnotationManager } from './TfAnnotationManager';
 import { TfXrNavigation } from './TfXrNavigation';
+import VrAnnotationPanel from './VrAnnotationPanel';
+import XrAnnotationInteraction from './XrAnnotationInteraction';
 import XrExitButton from './XrExitButton';
+import XrGazeDwell from './XrGazeDwell';
+import XrPointerRay from './XrPointerRay';
 import { WalkthroughCamera } from './walkthrough-camera';
+import { rayHitsInteractiveUi } from './xr-interactive-ui';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 const DEFAULT_FOCUS_POINT = [0, 0.1, 0];
 const DEFAULT_POSITION = [1, 0.1, 0];
+
+// How far outside the clamp radius the boundary wall stands. Without it the wall would be coplanar
+// with the surface the head is clamped to, so a pinned user would have it in their face and through
+// their near clip plane. Deliberately an absolute world-space distance rather than one scaled by
+// scaleFactor: it is about the size of the user's body, not about the size of the scene.
+const WALL_INSET = 0.25;
 const VirtualWalkthroughViewer = ({
   splatSrc,
-  splatFormat,
   origin = DEFAULT_FOCUS_POINT,
   cameraPosition = DEFAULT_POSITION,
   sceneBounds,
@@ -61,7 +72,9 @@ const VirtualWalkthroughViewer = ({
   const [viewingAnnotationIndex, setViewingAnnotationIndex] = useState(-1);
   const [viewedScreenPos, setViewedScreenPos] = useState(null);
   const {
-    isCurrentlyInXr
+    isCurrentlyInXr,
+    isCurrentlyInVr,
+    isCurrentlyInAr
   } = useXr();
   const sceneBoundsRadius = useMemo(() => {
     if (sceneBounds?.m !== undefined) {
@@ -90,6 +103,16 @@ const VirtualWalkthroughViewer = ({
       walkthroughCam.groundPlane = cameraGroundPlane;
     }
   }, [cameraGroundPlane, app]);
+  useEffect(() => {
+    // Set imperatively for the same reason as BoundaryRing: boundsCenter is a Vec3, and the
+    // @playcanvas/react memo() comparator stops at the first prop with an .equals() method.
+    // @ts-expect-error - scripts are added dynamically to the entity
+    const navigation = app.root.findByName('camera-root')?.script?.tfXrNavigation;
+    if (navigation) {
+      navigation.boundsCenter = cameraBoundsCenter;
+      navigation.boundsRadius = sceneBoundsRadius * scaleFactor;
+    }
+  }, [app, cameraBoundsCenter, sceneBoundsRadius, scaleFactor]);
   const handleToggleFreeFly = useCallback(() => {
     const newFreeFly = !isFreeFly;
     // @ts-expect-error - scripts are added dynamically to the camera entity
@@ -164,6 +187,9 @@ const VirtualWalkthroughViewer = ({
     setViewedScreenPos(null);
   }, []);
   const handleAnnotationScreenPositionUpdate = useCallback((_index, screenX, screenY, size) => {
+    if (isCurrentlyInXr) {
+      return;
+    }
     // The scene is frozen while the panel is open, so guard against redundant
     // updates from the per-frame callback to avoid needless re-renders.
     setViewedScreenPos(prev => prev && prev.x === screenX && prev.y === screenY && prev.size === size ? prev : {
@@ -171,12 +197,18 @@ const VirtualWalkthroughViewer = ({
       y: screenY,
       size
     });
-  }, []);
+  }, [isCurrentlyInXr]);
   const handleCloseAnnotation = useCallback(() => {
     setViewingAnnotation(null);
     setViewingAnnotationIndex(-1);
     setViewedScreenPos(null);
   }, []);
+  const isTeleportBlocked = useCallback(inputSource => rayHitsInteractiveUi(app, inputSource.getOrigin(), inputSource.getDirection()), [app]);
+  useEffect(() => {
+    if (!isCurrentlyInXr) {
+      handleCloseAnnotation();
+    }
+  }, [isCurrentlyInXr, handleCloseAnnotation]);
   const handleAnnotationUpdate = useCallback(updates => {
     if (selectedAnnotationIndex === -1) {
       return;
@@ -196,10 +228,9 @@ const VirtualWalkthroughViewer = ({
   const canSave = useMemo(() => localAnnotations.every(annotation => annotation.title && annotation.title.trim() !== ''), [localAnnotations]);
   const splatModel = useMemo(() => /*#__PURE__*/_jsx(SplatModel, {
     splatSrc: splatSrc,
-    splatFormat: splatFormat,
     rotation: [-180, 0, 0],
     revealRain: isHighPerformance
-  }, 'splat'), [isHighPerformance, splatSrc, splatFormat]);
+  }, 'splat'), [isHighPerformance, splatSrc]);
   return /*#__PURE__*/_jsxs(_Fragment, {
     children: [/*#__PURE__*/_jsx(GradientSky, {
       topColor: skyColor || '#FFFFFF',
@@ -225,10 +256,19 @@ const VirtualWalkthroughViewer = ({
       }), /*#__PURE__*/_jsx(XrExitButton, {}), /*#__PURE__*/_jsx(Script, {
         script: XrControllers,
         enabled: !isEdit
+      }), /*#__PURE__*/_jsx(XrAnnotationInteraction, {
+        onDismiss: handleCloseAnnotation
+      }), /*#__PURE__*/_jsx(XrPointerRay, {}), isCurrentlyInVr && viewingAnnotation && /*#__PURE__*/_jsx(VrAnnotationPanel, {
+        annotation: viewingAnnotation,
+        annotationIndex: viewingAnnotationIndex,
+        scaleFactor: scaleFactor
+      }, viewingAnnotationIndex), isCurrentlyInXr && /*#__PURE__*/_jsx(XrGazeDwell, {
+        activeIndex: viewingAnnotationIndex
       }), /*#__PURE__*/_jsx(Script, {
         script: TfXrNavigation,
         enabled: !isEdit,
-        enableTeleport: false
+        enableTeleport: !isCurrentlyInAr && !viewingAnnotation,
+        isTeleportBlocked: isTeleportBlocked
       }), !isCurrentlyInXr && /*#__PURE__*/_jsx(Script, {
         script: AutoRotator,
         enabled: !isEdit && autoRotate && !viewingAnnotation,
@@ -267,6 +307,11 @@ const VirtualWalkthroughViewer = ({
           onScreenPositionUpdate: handleAnnotationScreenPositionUpdate
         }, `annotation-${index}`))]
       })]
+    }), isCurrentlyInXr && sceneBoundsRadius > 0 && /*#__PURE__*/_jsx(BoundaryWall, {
+      center: cameraBoundsCenter,
+      radius: sceneBoundsRadius * scaleFactor + WALL_INSET,
+      groundPlane: cameraGroundPlane,
+      baseY: 0
     }), /*#__PURE__*/_jsx(SplatControls, {
       defaultCameraFocus: origin,
       defaultCameraPosition: cameraPosition,

package/components/VirtualWalkthrough/VrAnnotationPanel.d.ts

@@ -0,0 +1,9 @@
+import type { AnnotationProps } from './Annotation';
+interface VrAnnotationPanelProps {
+    annotation: AnnotationProps;
+    annotationIndex: number;
+    scaleFactor: number;
+}
+declare const VrAnnotationPanel: ({ annotation, annotationIndex, scaleFactor }: VrAnnotationPanelProps) => import("react/jsx-runtime").JSX.Element;
+export default VrAnnotationPanel;
+//# sourceMappingURL=VrAnnotationPanel.d.ts.map

package/components/VirtualWalkthrough/VrAnnotationPanel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VrAnnotationPanel.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/VrAnnotationPanel.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,UAAU,sBAAsB;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,QAAA,MAAM,iBAAiB,GAAI,8CAA8C,sBAAsB,4CAY9F,CAAC;AAEF,eAAe,iBAAiB,CAAC"}

package/components/VirtualWalkthrough/VrAnnotationPanel.js

@@ -0,0 +1,22 @@
+import React from 'react';
+import { Entity } from '@playcanvas/react';
+import { Script } from '@playcanvas/react/components';
+import { VrAnnotationPanel as VrAnnotationPanelScript } from './vr-annotation-panel';
+import { jsx as _jsx } from "react/jsx-runtime";
+const VrAnnotationPanel = ({
+  annotation,
+  annotationIndex,
+  scaleFactor
+}) => /*#__PURE__*/_jsx(Entity, {
+  name: "vr-annotation-panel",
+  children: /*#__PURE__*/_jsx(Script, {
+    script: VrAnnotationPanelScript,
+    title: annotation.title,
+    label: annotation.label,
+    bodyText: annotation.bodyText,
+    imageUrls: annotation.imageUrls,
+    annotationIndex: annotationIndex,
+    scaleFactor: scaleFactor
+  })
+});
+export default VrAnnotationPanel;