@terraware/web-components 5.0.5 → 5.0.7-rc.2

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,4CA2L7D,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"Annotation.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/Annotation.tsx"],"names":[],"mappings":"AAWA,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

@@ -1,10 +1,11 @@
-import { useRef, useEffect, useCallback, useMemo } from 'react';
+import { useContext, useRef, useEffect, useCallback, useMemo } from 'react';
 import { Entity } from '@playcanvas/react';
 import { Script } from '@playcanvas/react/components';
 import { useApp } from '@playcanvas/react/hooks';
 import { Gizmo, TranslateGizmo } from 'playcanvas';
 import { Annotation as Annotation$1 } from 'playcanvas/scripts/esm/annotations.mjs';
 import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
+import { CameraEntityContext } from '../../hooks/cameraEntityContext.js';
 import { useCameraPosition } from '../../hooks/useCameraPosition.js';
 import './annotation-styles.css';
 import { jsx } from 'react/jsx-runtime';
@@ -52,6 +53,7 @@ const Annotation = props => {
     index
   } = props;
   const app = useApp();
+  const walkthroughCamera = useContext(CameraEntityContext);
   const {
     setCamera
   } = useCameraPosition();
@@ -146,9 +148,8 @@ const Annotation = props => {
     }
     const setupGizmo = () => {
       const annotationEntity = app.root.findByName(entityName);
-      const cameraEntity = app.root.findByName('camera');
-      const cameraComponent = cameraEntity?.camera;
-      const cameraControls = cameraEntity?.script?.get(CameraControls.scriptName);
+      const cameraComponent = walkthroughCamera?.camera;
+      const cameraControls = walkthroughCamera?.script?.get(CameraControls.scriptName);
       if (!annotationEntity || !cameraComponent) {
         return false;
       }
@@ -188,7 +189,7 @@ const Annotation = props => {
       clearInterval(intervalId);
       cleanupGizmo();
     };
-  }, [app, isEdit, isSelected, visible, onPositionChange, entityName]);
+  }, [app, isEdit, isSelected, visible, onPositionChange, entityName, walkthroughCamera]);
   return /*#__PURE__*/jsx(Entity, {
     name: entityName,
     position: position,

package/components/VirtualWalkthrough/AutoRotator.d.ts

@@ -88,6 +88,16 @@ export declare class AutoRotator extends Script {
      * Initialize the script.
      */
     initialize(): void;
+    /**
+     * Finds the camera and the script posing it. WalkthroughCamera is mounted on this entity, the rig,
+     * so that it poses a camera the walkthrough adopted from a host scene as readily as one of its own;
+     * CameraControls sits on the camera entity itself.
+     *
+     * Called again while nothing has been found, because an adopted camera is reparented into the rig
+     * by an effect that runs after the scripts are mounted.
+     * @private
+     */
+    private resolveCamera;
     /**
      * Update loop that handles auto-rotation logic.
      * Runs after CameraControls updates.

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

@@ -1 +1 @@
-{"version":3,"file":"AutoRotator.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/AutoRotator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,MAAM,EAAQ,MAAM,YAAY,CAAC;AAEhD;;;GAGG;AACH,qBAAa,WAAY,SAAQ,MAAM;IACrC,MAAM,CAAC,UAAU,SAAiB;IAElC;;;;;OAKG;IACH,KAAK,SAAK;IAEV;;;;;OAKG;IACH,UAAU,SAAK;IAEf;;;;;OAKG;IACH,YAAY,SAAK;IAEjB;;;;;OAKG;IACH,eAAe,SAAK;IAEpB;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAK;IAElB;;;OAGG;IACH,OAAO,CAAC,kBAAkB,CAAS;IAEnC;;;OAGG;IACH,OAAO,CAAC,mBAAmB,CAAS;IAEpC;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAuB;IAEpC;;;OAGG;IACH,OAAO,CAAC,GAAG,CAAuB;IAElC;;;OAGG;IACH,OAAO,CAAC,YAAY,CAAa;IAEjC;;;OAGG;IACH,OAAO,CAAC,cAAc,CAAa;IAEnC;;;OAGG;IACH,OAAO,CAAC,iBAAiB,CAAa;IAEtC;;;OAGG;IACH,OAAO,CAAC,aAAa,CAAC,CAAa;IACnC,OAAO,CAAC,SAAS,CAAC,CAAa;IAE/B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAMvB;;OAEG;IACH,UAAU;IAgBV;;;OAGG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM;IAsErB;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAWlB;;OAEG;IACH,OAAO;CAQR"}
+{"version":3,"file":"AutoRotator.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/AutoRotator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,MAAM,EAAQ,MAAM,YAAY,CAAC;AAEhD;;;GAGG;AACH,qBAAa,WAAY,SAAQ,MAAM;IACrC,MAAM,CAAC,UAAU,SAAiB;IAElC;;;;;OAKG;IACH,KAAK,SAAK;IAEV;;;;;OAKG;IACH,UAAU,SAAK;IAEf;;;;;OAKG;IACH,YAAY,SAAK;IAEjB;;;;;OAKG;IACH,eAAe,SAAK;IAEpB;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAK;IAElB;;;OAGG;IACH,OAAO,CAAC,kBAAkB,CAAS;IAEnC;;;OAGG;IACH,OAAO,CAAC,mBAAmB,CAAS;IAEpC;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAuB;IAEpC;;;OAGG;IACH,OAAO,CAAC,GAAG,CAAuB;IAElC;;;OAGG;IACH,OAAO,CAAC,YAAY,CAAa;IAEjC;;;OAGG;IACH,OAAO,CAAC,cAAc,CAAa;IAEnC;;;OAGG;IACH,OAAO,CAAC,iBAAiB,CAAa;IAEtC;;;OAGG;IACH,OAAO,CAAC,aAAa,CAAC,CAAa;IACnC,OAAO,CAAC,SAAS,CAAC,CAAa;IAE/B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAMvB;;OAEG;IACH,UAAU;IAYV;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;IAQrB;;;OAGG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM;IA0ErB;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAWlB;;OAEG;IACH,OAAO;CAQR"}

package/components/VirtualWalkthrough/AutoRotator.js

@@ -112,11 +112,24 @@ class AutoRotator extends Script {
       this.app.graphicsDevice.canvas.addEventListener('pointerdown', this.onPointerDown);
     }
     window.addEventListener('keydown', this.onKeyDown);
-    this.cameraEntity = this.entity.findByName('camera');
-    if (this.cameraEntity) {
-      this.cameraControls = this.cameraEntity.script?.cameraControls ?? null;
-      this.walkthroughCamera = this.cameraEntity.script?.walkthroughCamera ?? null;
-    }
+    this.resolveCamera();
+  }
+
+  /**
+   * Finds the camera and the script posing it. WalkthroughCamera is mounted on this entity, the rig,
+   * so that it poses a camera the walkthrough adopted from a host scene as readily as one of its own;
+   * CameraControls sits on the camera entity itself.
+   *
+   * Called again while nothing has been found, because an adopted camera is reparented into the rig
+   * by an effect that runs after the scripts are mounted.
+   * @private
+   */
+  resolveCamera() {
+    this.cameraEntity = this.entity.findComponent('camera')?.entity ?? null;
+    this.cameraControls = this.cameraEntity?.script?.cameraControls ?? null;
+    // @ts-expect-error - scripts are added dynamically to the entity
+    const rigWalkthroughCamera = this.entity.script?.walkthroughCamera;
+    this.walkthroughCamera = rigWalkthroughCamera ?? this.cameraEntity?.script?.walkthroughCamera ?? null;
   }
 
   /**
@@ -124,6 +137,9 @@ class AutoRotator extends Script {
    * Runs after CameraControls updates.
    */
   postUpdate(dt) {
+    if (!this.cameraControls && !this.walkthroughCamera) {
+      this.resolveCamera();
+    }
     const hasControls = this.cameraControls && this.cameraControls._pose;
     const hasWalkthrough = !!this.walkthroughCamera;
     if (!hasControls && !hasWalkthrough) {

package/components/VirtualWalkthrough/TfXrNavigation.d.ts

@@ -21,6 +21,20 @@ export declare class TfXrNavigation extends PcXrNavigation {
     clampDistance: number;
     private _gestures;
     private _isBlocked;
+    /**
+     * Tracks controllers the base script never heard about.
+     *
+     * Movement, turning and teleport all iterate `_inputSources`, which the base fills from the XR
+     * input `add` event it subscribes to in initialize. A walkthrough that adopts the host's camera is
+     * mounted into a session that is already running, so the controllers present at session start
+     * fired `add` before this script existed and every control is inert for the whole session.
+     *
+     * The sources are picked up by hand rather than by re-firing `add` on the input manager, which
+     * would also reach the host's own listeners and have them handle controllers they already know
+     * about. The handlers mirror the base's and are stored in its map, so its teardown detaches them.
+     */
+    private _syncInputSources;
+    private _resolveCamera;
     tryTeleport(inputSource: XrInputSource): void;
     update(dt: number): void;
     /**

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,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"}
+{"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;AAoB7F;;;;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;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,iBAAiB;IA2BzB,OAAO,CAAC,cAAc;IAOtB,WAAW,CAAC,WAAW,EAAE,aAAa;IAYtC,MAAM,CAAC,EAAE,EAAE,MAAM;IAqCjB;;;;;;;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

@@ -30,6 +30,50 @@ class TfXrNavigation extends XrNavigation {
   _isBlocked(inputSource) {
     return !this.enableTeleport || this.isTeleportBlocked?.(inputSource) === true;
   }
+
+  /**
+   * Tracks controllers the base script never heard about.
+   *
+   * Movement, turning and teleport all iterate `_inputSources`, which the base fills from the XR
+   * input `add` event it subscribes to in initialize. A walkthrough that adopts the host's camera is
+   * mounted into a session that is already running, so the controllers present at session start
+   * fired `add` before this script existed and every control is inert for the whole session.
+   *
+   * The sources are picked up by hand rather than by re-firing `add` on the input manager, which
+   * would also reach the host's own listeners and have them handle controllers they already know
+   * about. The handlers mirror the base's and are stored in its map, so its teardown detaches them.
+   */
+  _syncInputSources() {
+    const internals = this;
+    for (const inputSource of this.app.xr?.input?.inputSources ?? []) {
+      if (internals._inputSources.has(inputSource)) {
+        continue;
+      }
+      const handleSelectStart = () => {
+        internals._activePointers.set(inputSource, true);
+        internals._arcHits.delete(inputSource);
+      };
+      const handleSelectEnd = () => {
+        internals._activePointers.set(inputSource, false);
+        if (this.enableTeleport) {
+          this.tryTeleport(inputSource);
+        }
+      };
+      inputSource.on('selectstart', handleSelectStart);
+      inputSource.on('selectend', handleSelectEnd);
+      internals._inputHandlers.set(inputSource, {
+        handleSelectStart,
+        handleSelectEnd
+      });
+      internals._inputSources.add(inputSource);
+    }
+  }
+  _resolveCamera() {
+    const internals = this;
+    if (!internals._cameraEntity) {
+      internals._cameraEntity = this.entity.findComponent('camera')?.entity ?? null;
+    }
+  }
   tryTeleport(inputSource) {
     // 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
@@ -41,6 +85,8 @@ class TfXrNavigation extends XrNavigation {
     super.tryTeleport(inputSource);
   }
   update(dt) {
+    this._resolveCamera();
+    this._syncInputSources();
     super.update(dt);
     const internals = this;
     for (const inputSource of internals._inputSources) {

package/components/VirtualWalkthrough/VirtualWalkthroughViewer.d.ts

@@ -13,6 +13,18 @@ export interface VirtualWalkthroughViewerProps {
     /**
      * Camera component mounted on the camera entity. Defaults to a 60 degree camera clearing to the
      * horizon color.
+     *
+     * Pass null to mount no camera of the walkthrough's own, which is what a caller sharing a scene
+     * it does not own wants: an XR session is welded to the camera it was started on, so a
+     * walkthrough that brought its own could only take over by ending the session and dropping the
+     * user out of the headset. The walkthrough adopts the scene's existing camera into its rig
+     * instead, for as long as it is mounted.
+     *
+     * A scene shared this way is expected to hold exactly one camera. The adoption takes the first
+     * camera in graph traversal order, which is only certain to be the one the headset renders
+     * through while it is the only one there: a scene that also carries a spectator or overlay camera
+     * can hand the rig the wrong entity, and locomotion then goes inert with nothing reported. Prefer
+     * the session's own camera, `app.xr.camera`, over the traversal if that ever needs to hold.
      */
     camera?: ReactNode;
     /** World-space point the camera looks at. */
@@ -54,6 +66,12 @@ export interface VirtualWalkthroughViewerProps {
      * but couldn't be started, in which case the error says why.
      */
     onXrExit?: (error?: Error) => void;
+    /**
+     * Runs instead of ending the XR session when the user activates the in-headset exit button.
+     * Without it the button ends the session, which in turn reports `onXrExit`; with it the session
+     * stays running and neither happens, leaving the handler to decide what closing means.
+     */
+    onXrClose?: () => void;
     annotations: AnnotationProps[];
     onSaveAnnotations: (annotations: AnnotationProps[]) => void | Promise<void>;
     editable?: boolean;
@@ -62,6 +80,6 @@ export interface VirtualWalkthroughViewerProps {
     onToggleFullScreen?: () => void;
     maxImagesPerAnnotation?: number;
 }
-declare const VirtualWalkthroughViewer: ({ splatSrc, splatFormat, camera, origin, cameraPosition, sceneBounds, groundPlane: groundPlaneProp, skyColor, groundColor, averageCameraHeight, scaleFactor, splatModelProps, autoStartVr, onXrExit, annotations, onSaveAnnotations, editable, showFreeFly, isFullScreen, onToggleFullScreen, maxImagesPerAnnotation, }: VirtualWalkthroughViewerProps) => import("react/jsx-runtime").JSX.Element;
+declare const VirtualWalkthroughViewer: ({ splatSrc, splatFormat, camera, origin, cameraPosition, sceneBounds, groundPlane: groundPlaneProp, skyColor, groundColor, averageCameraHeight, scaleFactor, splatModelProps, autoStartVr, onXrExit, onXrClose, annotations, onSaveAnnotations, 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":"AAAA,OAAc,EAAE,SAAS,EAAqD,MAAM,OAAO,CAAC;AAY5F,OAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAO3D,OAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAS3D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAmB5C;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,8CAA8C;IAC9C,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,2FAA2F;IAC3F,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,uEAAuE;IACvE,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,6CAA6C;IAC7C,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAC3C;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,IAAI,CAAC;IACnC,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,iBAAiB,EAAE,CAAC,WAAW,EAAE,eAAe,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,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,yTAsB/B,6BAA6B,4CAqa/B,CAAC;AAEF,eAAe,wBAAwB,CAAC"}
+{"version":3,"file":"VirtualWalkthroughViewer.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/VirtualWalkthroughViewer.tsx"],"names":[],"mappings":"AAAA,OAAc,EAAE,SAAS,EAAqD,MAAM,OAAO,CAAC;AAa5F,OAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAO3D,OAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAS3D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAoB5C;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,8CAA8C;IAC9C,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,2FAA2F;IAC3F,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,uEAAuE;IACvE,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,6CAA6C;IAC7C,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAC3C;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,IAAI,CAAC;IACnC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,iBAAiB,EAAE,CAAC,WAAW,EAAE,eAAe,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,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,oUAuB/B,6BAA6B,4CAkb/B,CAAC;AAEF,eAAe,wBAAwB,CAAC"}

package/components/VirtualWalkthrough/VirtualWalkthroughViewer.js

@@ -5,6 +5,7 @@ import { Script, Camera } from '@playcanvas/react/components';
 import { useApp } from '@playcanvas/react/hooks';
 import { Vec3, Color } from 'playcanvas';
 import { XrControllers } from 'playcanvas/scripts/esm/xr/xr-controllers.mjs';
+import { CameraEntityContext } from '../../hooks/cameraEntityContext.js';
 import { useCameraPosition } from '../../hooks/useCameraPosition.js';
 import { useDevicePerformance } from '../../hooks/useDevicePerformance.js';
 import useXr from '../../hooks/useXr.js';
@@ -24,10 +25,11 @@ import XrExitButton from './XrExitButton.js';
 import XrGazeDwell from './XrGazeDwell.js';
 import XrPointerRay from './XrPointerRay.js';
 import { XrStartPose } from './XrStartPose.js';
+import useAdoptedCamera from './useAdoptedCamera.js';
 import useXrRenderTuning from './useXrRenderTuning.js';
 import { WalkthroughCamera } from './walkthrough-camera.js';
 import { rayHitsInteractiveUi } from './xr-interactive-ui.js';
-import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import { jsx, jsxs } from 'react/jsx-runtime';
 
 const DEFAULT_FOCUS_POINT = [0, 0.1, 0];
 const DEFAULT_POSITION = [1, 0.1, 0];
@@ -67,6 +69,7 @@ const VirtualWalkthroughViewer = ({
   splatModelProps,
   autoStartVr = false,
   onXrExit,
+  onXrClose,
   annotations,
   onSaveAnnotations,
   editable = false,
@@ -76,9 +79,19 @@ const VirtualWalkthroughViewer = ({
   maxImagesPerAnnotation
 }) => {
   const theme = useTheme();
+  // Held as state so the effects and hooks that address these entities re-run once they
+  // exist. Addressed directly: a viewer mounted into a host's scene shares the graph
+  // with the host's entities, so the camera can be found by component type.
+  const [cameraRoot, setCameraRoot] = useState(null);
+  const [cameraEntity, setCameraEntity] = useState(null);
+  const adoptedCamera = useAdoptedCamera(cameraRoot, cameraEntity);
+  // The entity carrying the live camera component: the viewer's own, or the host's while adopted.
+  // Everything that poses the camera or projects through it addresses this rather than the entity
+  // the viewer mounts a camera of its own on, which holds nothing while a camera is adopted.
+  const activeCamera = adoptedCamera ?? cameraEntity;
   const {
     setCamera
-  } = useCameraPosition();
+  } = useCameraPosition(activeCamera);
   const {
     isHighPerformance
   } = useDevicePerformance();
@@ -162,27 +175,27 @@ const VirtualWalkthroughViewer = ({
     if (!groundPlane.length || isCurrentlyInXr) {
       return;
     }
-    // @ts-expect-error - scripts are added dynamically to the camera entity
-    const walkthroughCam = app.root.findByName('camera')?.script?.walkthroughCamera;
+    // @ts-expect-error - scripts are added dynamically to the entity
+    const walkthroughCam = cameraRoot?.script?.walkthroughCamera;
     if (walkthroughCam) {
       // Should be changed to a react prop if shallowEquals in playcanvas/react is fixed (see https://github.com/playcanvas/react/pull/298)
       walkthroughCam.groundPlane = groundPlane;
     }
-  }, [groundPlane, app, isCurrentlyInXr]);
+  }, [groundPlane, cameraRoot, isCurrentlyInXr]);
   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;
+    const navigation = cameraRoot?.script?.tfXrNavigation;
     if (navigation) {
       navigation.boundsCenter = sceneBoundsCenter;
       navigation.boundsRadius = sceneBoundsRadius;
     }
-  }, [app, sceneBoundsCenter, sceneBoundsRadius]);
+  }, [cameraRoot, sceneBoundsCenter, sceneBoundsRadius]);
   const handleToggleFreeFly = useCallback(() => {
     const newFreeFly = !isFreeFly;
-    // @ts-expect-error - scripts are added dynamically to the camera entity
-    const walkthroughCam = app.root.findByName('camera')?.script?.walkthroughCamera;
+    // @ts-expect-error - scripts are added dynamically to the entity
+    const walkthroughCam = cameraRoot?.script?.walkthroughCamera;
     if (walkthroughCam) {
       walkthroughCam.freeFly = newFreeFly;
     }
@@ -190,7 +203,7 @@ const VirtualWalkthroughViewer = ({
       setCamera(origin, cameraPosition);
     }
     setIsFreeFly(newFreeFly);
-  }, [isFreeFly, app, setCamera, origin, cameraPosition]);
+  }, [isFreeFly, cameraRoot, setCamera, origin, cameraPosition]);
   useEffect(() => {
     setLocalAnnotations(annotations);
   }, [annotations]);
@@ -300,23 +313,28 @@ const VirtualWalkthroughViewer = ({
     scaleFactor: scaleFactor,
     revealRain: isHighPerformance
   }, 'splat'), [isHighPerformance, splatSrc, splatFormat, scaleFactor, splatModelProps]);
-  return /*#__PURE__*/jsxs(Fragment, {
+  return /*#__PURE__*/jsxs(CameraEntityContext.Provider, {
+    value: activeCamera,
     children: [/*#__PURE__*/jsx(GradientSky, {
       topColor: skyColor || '#FFFFFF',
       horizonColor: skyColor || '#EAF8FF',
       groundColor: groundColor || '#C3BDB7'
     }), /*#__PURE__*/jsxs(Entity, {
       name: "camera-root",
-      children: [/*#__PURE__*/jsxs(Entity, {
+      ref: setCameraRoot,
+      children: [/*#__PURE__*/jsx(Entity, {
         name: "camera",
-        children: [camera, !isCurrentlyInXr && /*#__PURE__*/jsx(Script, {
-          script: WalkthroughCamera,
-          boundsCenter: sceneBoundsCenter,
-          boundsRadius: sceneBoundsRadius,
-          enableFly: !isTextFieldFocused,
-          averageCameraHeight: averageCameraHeight
-        })]
-      }), /*#__PURE__*/jsx(XrExitButton, {}), /*#__PURE__*/jsx(Script, {
+        ref: setCameraEntity,
+        children: camera
+      }), !isCurrentlyInXr && /*#__PURE__*/jsx(Script, {
+        script: WalkthroughCamera,
+        boundsCenter: sceneBoundsCenter,
+        boundsRadius: sceneBoundsRadius,
+        enableFly: !isTextFieldFocused,
+        averageCameraHeight: averageCameraHeight
+      }), /*#__PURE__*/jsx(XrExitButton, {
+        onClose: onXrClose
+      }), /*#__PURE__*/jsx(Script, {
         script: XrControllers,
         enabled: !isEdit
       }), /*#__PURE__*/jsx(XrAnnotationInteraction, {

package/components/VirtualWalkthrough/XrExitButton.d.ts

@@ -1,3 +1,7 @@
-declare const XrExitButton: () => import("react/jsx-runtime").JSX.Element;
+interface XrExitButtonProps {
+    /** Runs instead of ending the XR session when the button is activated. */
+    onClose?: () => void;
+}
+declare const XrExitButton: ({ onClose }: XrExitButtonProps) => import("react/jsx-runtime").JSX.Element;
 export default XrExitButton;
 //# sourceMappingURL=XrExitButton.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"XrExitButton.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/XrExitButton.tsx"],"names":[],"mappings":"AAOA,QAAA,MAAM,YAAY,+CAIjB,CAAC;AAEF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"XrExitButton.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/XrExitButton.tsx"],"names":[],"mappings":"AAOA,UAAU,iBAAiB;IACzB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,QAAA,MAAM,YAAY,GAAI,aAAa,iBAAiB,4CAInD,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/components/VirtualWalkthrough/XrExitButton.js

@@ -4,10 +4,13 @@ import { Script } from '@playcanvas/react/components';
 import { XrExitButton as XrExitButton$1 } from './xr-exit-button.js';
 import { jsx } from 'react/jsx-runtime';
 
-const XrExitButton = () => /*#__PURE__*/jsx(Entity, {
+const XrExitButton = ({
+  onClose
+}) => /*#__PURE__*/jsx(Entity, {
   name: "xr-exit-button",
   children: /*#__PURE__*/jsx(Script, {
-    script: XrExitButton$1
+    script: XrExitButton$1,
+    onClose: onClose
   })
 });
 

package/components/VirtualWalkthrough/boundary-wall.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"boundary-wall.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/boundary-wall.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,EAOL,MAAM,EAEN,IAAI,EACL,MAAM,YAAY,CAAC;AAKpB,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE,IAAI,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,gHAAgH;IAChH,WAAW,EAAE,IAAI,EAAE,CAAC;IACpB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,sGAAsG;IACtG,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,sEAQ9B,0BAA0B,KAAG,oBAqD/B,CAAC;AA2EF;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,MAAM;IAC5C,MAAM,CAAC,UAAU,SAAkB;IAEnC,MAAM,OAAc;IACpB,MAAM,SAAK;IACX,WAAW,EAAE,IAAI,EAAE,CAAM;IACzB,uEAAuE;IACvE,KAAK,SAAK;IACV;;;OAGG;IACH,IAAI,SAAO;IACX,QAAQ,SAAM;IACd,WAAW,SAAO;IAClB,2CAA2C;IAC3C,SAAS,SAAS;IAClB,0EAA0E;IAC1E,YAAY,SAAO;IACnB,0EAA0E;IAC1E,gBAAgB,SAAO;IACvB,SAAS,QAA2B;IACpC,SAAS,QAA2B;IAEpC,OAAO,CAAC,SAAS,CAAC,CAAiB;IACnC,OAAO,CAAC,KAAK,CAAC,CAAO;IACrB,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,UAAU,CAAuB;IAEzC,UAAU;IAwBV;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAW5B,OAAO;IA6CP,MAAM;IAgCN,OAAO,CAAC,UAAU;CASnB"}
+{"version":3,"file":"boundary-wall.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/boundary-wall.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,EAOL,MAAM,EAEN,IAAI,EACL,MAAM,YAAY,CAAC;AAKpB,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE,IAAI,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,gHAAgH;IAChH,WAAW,EAAE,IAAI,EAAE,CAAC;IACpB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,sGAAsG;IACtG,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,sEAQ9B,0BAA0B,KAAG,oBAqD/B,CAAC;AA2EF;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,MAAM;IAC5C,MAAM,CAAC,UAAU,SAAkB;IAEnC,MAAM,OAAc;IACpB,MAAM,SAAK;IACX,WAAW,EAAE,IAAI,EAAE,CAAM;IACzB,uEAAuE;IACvE,KAAK,SAAK;IACV;;;OAGG;IACH,IAAI,SAAO;IACX,QAAQ,SAAM;IACd,WAAW,SAAO;IAClB,2CAA2C;IAC3C,SAAS,SAAS;IAClB,0EAA0E;IAC1E,YAAY,SAAO;IACnB,0EAA0E;IAC1E,gBAAgB,SAAO;IACvB,SAAS,QAA2B;IACpC,SAAS,QAA2B;IAEpC,OAAO,CAAC,SAAS,CAAC,CAAiB;IACnC,OAAO,CAAC,KAAK,CAAC,CAAO;IACrB,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,UAAU,CAAuB;IAEzC,UAAU;IAwBV;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAW5B,OAAO;IA6CP,MAAM;IAgCN,OAAO,CAAC,UAAU;CASnB"}

package/components/VirtualWalkthrough/boundary-wall.js

@@ -237,7 +237,7 @@ class BoundaryWallScript extends Script {
    */
   _resolveDependencies() {
     if (!this._camera) {
-      this._camera = this.app.root.findByName('camera');
+      this._camera = this.app.root.findComponent('camera')?.entity ?? null;
     }
     if (!this._navigation) {
       const rig = this.app.root.findByName('camera-root');

package/components/VirtualWalkthrough/camera-adoption.d.ts

@@ -0,0 +1,39 @@
+import { Entity } from 'playcanvas';
+/**
+ * A camera the walkthrough took over, and the call that hands it back.
+ */
+export interface AdoptedCamera {
+    /** The entity now carrying the live camera component, which the rig poses and projects from. */
+    camera: Entity;
+    release: () => void;
+}
+/**
+ * Hands the scene's existing camera to a walkthrough rig that hasn't been given one.
+ *
+ * A caller mounting the viewer into a scene it doesn't own passes `camera={null}`, because an XR
+ * session is welded to the camera component it was started on — `XrManager.camera` is read-only and
+ * `start` refuses while a session is running — so a walkthrough that brought a camera of its own
+ * could only become the session's camera by ending it, which drops the user out of the headset.
+ *
+ * That leaves the rig with no camera under it, and everything that poses or solves against the head
+ * resolves it with `findComponent('camera')` on the rig: `WalkthroughCamera`'s pointer and keyboard
+ * walk, `XrStartPose`, `XrNavigation`'s thumbstick movement and turning, and the bounds clamp all go
+ * inert, so the head is never placed at the walkthrough's start point and can never be moved from
+ * wherever the host scene left it. Splat LOD is chosen from
+ * the camera's distance to each octree node, so the far side of the model stays coarse for the whole
+ * session no matter which way the headset turns.
+ *
+ * Reparenting carries the live camera component with it, so the session, its views, and the host's
+ * own clear color and clip planes are all untouched — only which entity the camera hangs off
+ * changes. The camera becomes a direct child of the rig, which is exactly where a camera the viewer
+ * owns sits, so the rig means the same thing either way.
+ *
+ * @param root - The scene root to look for a camera in, expected to hold exactly one camera.
+ * @param rig - The entity the walkthrough's XR scripts move, `camera-root`.
+ * @param ownCamera - The entity the viewer mounts its own camera on. Nothing is adopted when it
+ * already carries one.
+ * @returns The adopted camera and the call that puts it back, or null when there was nothing to
+ * adopt.
+ */
+export declare const adoptSceneCamera: (root: Entity, rig: Entity, ownCamera: Entity) => AdoptedCamera | null;
+//# sourceMappingURL=camera-adoption.d.ts.map

package/components/VirtualWalkthrough/camera-adoption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera-adoption.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/camera-adoption.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,MAAM,EAAc,MAAM,YAAY,CAAC;AAWjE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,gGAAgG;IAChG,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,EAAE,KAAK,MAAM,EAAE,WAAW,MAAM,KAAG,aAAa,GAAG,IA8B/F,CAAC"}

package/components/VirtualWalkthrough/camera-adoption.js

@@ -0,0 +1,66 @@
+/**
+ * The pose an adopted camera is put back to when the walkthrough releases it.
+ */
+
+/**
+ * A camera the walkthrough took over, and the call that hands it back.
+ */
+
+/**
+ * Hands the scene's existing camera to a walkthrough rig that hasn't been given one.
+ *
+ * A caller mounting the viewer into a scene it doesn't own passes `camera={null}`, because an XR
+ * session is welded to the camera component it was started on — `XrManager.camera` is read-only and
+ * `start` refuses while a session is running — so a walkthrough that brought a camera of its own
+ * could only become the session's camera by ending it, which drops the user out of the headset.
+ *
+ * That leaves the rig with no camera under it, and everything that poses or solves against the head
+ * resolves it with `findComponent('camera')` on the rig: `WalkthroughCamera`'s pointer and keyboard
+ * walk, `XrStartPose`, `XrNavigation`'s thumbstick movement and turning, and the bounds clamp all go
+ * inert, so the head is never placed at the walkthrough's start point and can never be moved from
+ * wherever the host scene left it. Splat LOD is chosen from
+ * the camera's distance to each octree node, so the far side of the model stays coarse for the whole
+ * session no matter which way the headset turns.
+ *
+ * Reparenting carries the live camera component with it, so the session, its views, and the host's
+ * own clear color and clip planes are all untouched — only which entity the camera hangs off
+ * changes. The camera becomes a direct child of the rig, which is exactly where a camera the viewer
+ * owns sits, so the rig means the same thing either way.
+ *
+ * @param root - The scene root to look for a camera in, expected to hold exactly one camera.
+ * @param rig - The entity the walkthrough's XR scripts move, `camera-root`.
+ * @param ownCamera - The entity the viewer mounts its own camera on. Nothing is adopted when it
+ * already carries one.
+ * @returns The adopted camera and the call that puts it back, or null when there was nothing to
+ * adopt.
+ */
+const adoptSceneCamera = (root, rig, ownCamera) => {
+  if (ownCamera.camera) {
+    return null;
+  }
+  const camera = root.findComponent('camera')?.entity;
+  // isDescendantOf covers a host that mounted the walkthrough inside its own camera, where
+  // reparenting would make a cycle.
+  if (!camera || camera === rig || !camera.parent || rig.isDescendantOf(camera)) {
+    return null;
+  }
+  const previous = {
+    parent: camera.parent,
+    position: camera.getLocalPosition().clone(),
+    rotation: camera.getLocalRotation().clone()
+  };
+
+  // addChild keeps the local transform, so the host's authored camera pose survives the move and
+  // only has to be restored because a session overwrites it with the head pose every frame.
+  rig.addChild(camera);
+  return {
+    camera,
+    release: () => {
+      previous.parent.addChild(camera);
+      camera.setLocalPosition(previous.position);
+      camera.setLocalRotation(previous.rotation);
+    }
+  };
+};
+
+export { adoptSceneCamera };

package/components/VirtualWalkthrough/useAdoptedCamera.d.ts

@@ -0,0 +1,14 @@
+import { Entity } from 'playcanvas';
+/**
+ * Keeps the walkthrough's rig holding a camera for as long as the viewer is mounted, adopting the
+ * scene's own when the viewer wasn't given one. See {@link adoptSceneCamera} for why.
+ *
+ * @param rig - The `camera-root` entity, or null before it exists.
+ * @param ownCamera - The entity the viewer mounts its own camera on, or null before it exists.
+ * @returns The adopted camera, or null when the viewer brought one of its own. Held as state so the
+ * viewer re-renders and re-points everything that addresses the camera at the entity now carrying
+ * it.
+ */
+export declare const useAdoptedCamera: (rig: Entity | null, ownCamera: Entity | null) => Entity | null;
+export default useAdoptedCamera;
+//# sourceMappingURL=useAdoptedCamera.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useAdoptedCamera.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/useAdoptedCamera.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAIpC;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,GAAG,IAAI,EAAE,WAAW,MAAM,GAAG,IAAI,KAAG,MAAM,GAAG,IA8BxF,CAAC;AAEF,eAAe,gBAAgB,CAAC"}

package/components/VirtualWalkthrough/useAdoptedCamera.js

@@ -0,0 +1,45 @@
+import { useState, useLayoutEffect } from 'react';
+import { useApp } from '@playcanvas/react/hooks';
+import { adoptSceneCamera } from './camera-adoption.js';
+
+/**
+ * Keeps the walkthrough's rig holding a camera for as long as the viewer is mounted, adopting the
+ * scene's own when the viewer wasn't given one. See {@link adoptSceneCamera} for why.
+ *
+ * @param rig - The `camera-root` entity, or null before it exists.
+ * @param ownCamera - The entity the viewer mounts its own camera on, or null before it exists.
+ * @returns The adopted camera, or null when the viewer brought one of its own. Held as state so the
+ * viewer re-renders and re-points everything that addresses the camera at the entity now carrying
+ * it.
+ */
+const useAdoptedCamera = (rig, ownCamera) => {
+  const app = useApp();
+  const [adopted, setAdopted] = useState(null);
+
+  // A layout effect, so that the camera is handed back before the rig it was parented into is
+  // destroyed. `@playcanvas/react`'s Entity destroys its entity in a layout effect's teardown, and
+  // destroying an entity destroys its children — so a release deferred to a passive effect runs
+  // after the host's camera has already been destroyed along with the walkthrough, leaving the host
+  // scene with no camera to render through at all.
+  //
+  // The rig is a child of the viewer, and React tears an unmounting tree's layout effects down from
+  // the top, so this runs first.
+  useLayoutEffect(() => {
+    if (!rig || !ownCamera) {
+      return;
+    }
+
+    // Both entities are state set from refs, so this runs a commit after the child that mounts the
+    // camera component: a viewer that was given a camera is recognised as owning one rather than
+    // adopted on top of.
+    const adoption = adoptSceneCamera(app.root, rig, ownCamera);
+    setAdopted(adoption?.camera ?? null);
+    return () => {
+      adoption?.release();
+      setAdopted(null);
+    };
+  }, [app, rig, ownCamera]);
+  return adopted;
+};
+
+export { useAdoptedCamera as default, useAdoptedCamera };

package/components/VirtualWalkthrough/useXrRenderTuning.d.ts

@@ -1,5 +1,6 @@
 /**
- * Holds the XR render settings in place for the duration of a session.
+ * Holds the XR render settings in place for the duration of a session, including one that is
+ * already running when this mounts.
  *
  * Call this once per application. The gsplat settings it writes are scene-global, so a second
  * caller would capture the first caller's tuned values as the state to restore, and the scene would

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

@@ -1 +1 @@
-{"version":3,"file":"useXrRenderTuning.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/useXrRenderTuning.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,YAsC7B,CAAC;AAEF,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"useXrRenderTuning.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/useXrRenderTuning.ts"],"names":[],"mappings":"AAMA;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,YA8C7B,CAAC;AAEF,eAAe,iBAAiB,CAAC"}

package/components/VirtualWalkthrough/useXrRenderTuning.js

@@ -3,7 +3,8 @@ import { useApp } from '@playcanvas/react/hooks';
 import { applyGsplatTuning, XR_FIXED_FOVEATION, restoreGsplatTuning } from './xr-render-tuning.js';
 
 /**
- * Holds the XR render settings in place for the duration of a session.
+ * Holds the XR render settings in place for the duration of a session, including one that is
+ * already running when this mounts.
  *
  * Call this once per application. The gsplat settings it writes are scene-global, so a second
  * caller would capture the first caller's tuned values as the state to restore, and the scene would
@@ -35,6 +36,14 @@ const useXrRenderTuning = () => {
     };
     xr.on('start', handleStart);
     xr.on('end', restore);
+
+    // A viewer can be mounted into a scene that is already in a headset, in which case `start`
+    // fired before this hook existed and waiting for it would leave the whole session rendering
+    // with the desktop settings. `handleStart` is idempotent, so a session that goes on to fire
+    // `start` anyway does not capture the tuned values as the ones to restore.
+    if (xr.active) {
+      handleStart();
+    }
     return () => {
       xr.off('start', handleStart);
       xr.off('end', restore);

package/components/VirtualWalkthrough/walkthrough-camera.d.ts

@@ -34,7 +34,7 @@ export declare class WalkthroughCamera extends Script {
      * Script component is wrapped in memo() whose shallowEquals comparator returns early on the first prop
      * with a .equals() method (Vec3), so any prop listed after boundsCenter is never compared and the
      * component won't re-render when it changes. Set via:
-     *   app.root.findByName('camera')?.script?.walkthroughCamera.groundPlane = points
+     *   cameraRoot.script.walkthroughCamera.groundPlane = points
      * Should be updated if shallowEquals is fixed (see https://github.com/playcanvas/react/pull/298)
      */
     groundPlane: Vec3[];
@@ -48,9 +48,16 @@ export declare class WalkthroughCamera extends Script {
     private _scrollDelta;
     private _keys;
     private _removeListeners;
+    private _camera;
     private _planeNormal;
     private _planePoint;
     private _hasGroundPlane;
+    /**
+     * The camera to pose, or null while there is none to pose. The entity this script is mounted on is
+     * never posed in its place: on the walkthrough that is the rig, which is the frame an XR session
+     * is measured from and whose height the session's floor is taken from.
+     */
+    private _posedCamera;
     private _syncGroundPlane;
     initialize(): void;
     /**

package/components/VirtualWalkthrough/walkthrough-camera.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"walkthrough-camera.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/walkthrough-camera.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,MAAM,EAAE,IAAI,EAAQ,MAAM,YAAY,CAAC;AA8BtD,qBAAa,iBAAkB,SAAQ,MAAM;IAC3C,MAAM,CAAC,UAAU,SAAuB;IAExC,SAAS,SAAO;IAEhB,iBAAiB;IACjB,aAAa,SAAO;IAEpB,iBAAiB;IACjB,aAAa,SAAQ;IAErB,iBAAiB;IACjB,eAAe,SAAO;IAEtB,iBAAiB;IACjB,aAAa,SAAQ;IAErB,iBAAiB;IACjB,QAAQ,SAAO;IAEf,iBAAiB;IACjB,QAAQ,SAAM;IAEd,iBAAiB;IACjB,WAAW,SAAS;IAEpB,iBAAiB;IACjB,YAAY,OAAqB;IAEjC,iBAAiB;IACjB,YAAY,SAAM;IAElB,iBAAiB;IACjB,OAAO,UAAS;IAEhB,iBAAiB;IACjB,SAAS,UAAQ;IAEjB,iBAAiB;IACjB,mBAAmB,SAAK;IAExB;;;;;;;;;;OAUG;IACH,WAAW,EAAE,IAAI,EAAE,CAAM;IAGzB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,IAAI,CAAK;IAGjB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,UAAU,CAAK;IAEvB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,KAAK,CAAwC;IACrD,OAAO,CAAC,gBAAgB,CAAsB;IAG9C,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,eAAe,CAAS;IAEhC,OAAO,CAAC,gBAAgB;IAaxB,UAAU;IAkFV;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI;IAsBjC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM;IAsB1B;;;OAGG;IACH,IAAI,UAAU,IAAI,IAAI,CAMrB;IAED,MAAM,CAAC,EAAE,EAAE,MAAM;IA4FjB,OAAO;CAIR"}
+{"version":3,"file":"walkthrough-camera.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/walkthrough-camera.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,MAAM,EAAE,IAAI,EAAQ,MAAM,YAAY,CAAC;AAmC/E,qBAAa,iBAAkB,SAAQ,MAAM;IAC3C,MAAM,CAAC,UAAU,SAAuB;IAExC,SAAS,SAAO;IAEhB,iBAAiB;IACjB,aAAa,SAAO;IAEpB,iBAAiB;IACjB,aAAa,SAAQ;IAErB,iBAAiB;IACjB,eAAe,SAAO;IAEtB,iBAAiB;IACjB,aAAa,SAAQ;IAErB,iBAAiB;IACjB,QAAQ,SAAO;IAEf,iBAAiB;IACjB,QAAQ,SAAM;IAEd,iBAAiB;IACjB,WAAW,SAAS;IAEpB,iBAAiB;IACjB,YAAY,OAAqB;IAEjC,iBAAiB;IACjB,YAAY,SAAM;IAElB,iBAAiB;IACjB,OAAO,UAAS;IAEhB,iBAAiB;IACjB,SAAS,UAAQ;IAEjB,iBAAiB;IACjB,mBAAmB,SAAK;IAExB;;;;;;;;;;OAUG;IACH,WAAW,EAAE,IAAI,EAAE,CAAM;IAGzB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,IAAI,CAAK;IAGjB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,UAAU,CAAK;IAEvB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,KAAK,CAAwC;IACrD,OAAO,CAAC,gBAAgB,CAAsB;IAI9C,OAAO,CAAC,OAAO,CAAuB;IAGtC,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,eAAe,CAAS;IAEhC;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,gBAAgB;IAaxB,UAAU;IAkFV;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI;IAuBjC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM;IA0B1B;;;OAGG;IACH,IAAI,UAAU,IAAI,IAAI,CAMrB;IAED,MAAM,CAAC,EAAE,EAAE,MAAM;IAgGjB,OAAO;CAIR"}

package/components/VirtualWalkthrough/walkthrough-camera.js

@@ -12,6 +12,11 @@ import { computeGroundPlane, yOnPlane } from './groundPlane.js';
  * - Y position is clamped between boundsMin.y and boundsMax.y; set them equal
  *   to lock vertical position entirely.
  * - Exposes reset() and focusPoint to stay compatible with useCameraPosition.
+ *
+ * The pose is written to the camera under this script's entity rather than to the entity itself, so
+ * mounting it on the walkthrough's rig drives whichever camera the rig is holding — one the viewer
+ * brought, or one it adopted from the host scene. Mounted straight onto a camera entity it still
+ * drives that entity, which `findComponent` resolves to itself.
  */
 
 const _quat = new Quat();
@@ -74,7 +79,7 @@ class WalkthroughCamera extends Script {
    * Script component is wrapped in memo() whose shallowEquals comparator returns early on the first prop
    * with a .equals() method (Vec3), so any prop listed after boundsCenter is never compared and the
    * component won't re-render when it changes. Set via:
-   *   app.root.findByName('camera')?.script?.walkthroughCamera.groundPlane = points
+   *   cameraRoot.script.walkthroughCamera.groundPlane = points
    * Should be updated if shallowEquals is fixed (see https://github.com/playcanvas/react/pull/298)
    */
   groundPlane = [];
@@ -93,10 +98,24 @@ class WalkthroughCamera extends Script {
   _keys = {};
   _removeListeners = [];
 
+  // The camera being posed, resolved lazily. Held until it exists: a camera adopted from the host
+  // scene is reparented into the rig by an effect that runs after the scripts are mounted.
+  _camera = null;
+
   // Cached plane derived from groundPlane attribute. Computed once when 3 points become available.
   _planeNormal = new Vec3(0, 1, 0);
   _planePoint = new Vec3(0, 0, 0);
   _hasGroundPlane = false;
+
+  /**
+   * The camera to pose, or null while there is none to pose. The entity this script is mounted on is
+   * never posed in its place: on the walkthrough that is the rig, which is the frame an XR session
+   * is measured from and whose height the session's floor is taken from.
+   */
+  _posedCamera() {
+    this._camera ??= this.entity.findComponent('camera')?.entity ?? null;
+    return this._camera;
+  }
   _syncGroundPlane() {
     if (this._hasGroundPlane || this.groundPlane.length < 3) {
       return;
@@ -179,7 +198,8 @@ class WalkthroughCamera extends Script {
    * Compatible with the useCameraPosition hook's reset() call.
    */
   reset(focus, position) {
-    this.entity.setPosition(position);
+    const camera = this._posedCamera();
+    camera?.setPosition(position);
     const dx = focus.x - position.x;
     const dy = focus.y - position.y;
     const dz = focus.z - position.z;
@@ -195,7 +215,7 @@ class WalkthroughCamera extends Script {
     // Snap targets so there's no damped drift from the previous pose.
     this._targetPitch = this._pitch;
     this._targetYaw = this._yaw;
-    this.entity.setEulerAngles(this._pitch, this._yaw, 0);
+    camera?.setEulerAngles(this._pitch, this._yaw, 0);
   }
   get currentYaw() {
     return this._targetYaw;
@@ -210,7 +230,11 @@ class WalkthroughCamera extends Script {
    */
   orbitStep(yawDelta) {
     this._syncGroundPlane();
-    const pos = this.entity.getPosition();
+    const camera = this._posedCamera();
+    if (!camera) {
+      return;
+    }
+    const pos = camera.getPosition();
     const dx = pos.x - this.boundsCenter.x;
     const dz = pos.z - this.boundsCenter.z;
     const radius = Math.sqrt(dx * dx + dz * dz) || this.boundsRadius * 0.5;
@@ -219,12 +243,12 @@ class WalkthroughCamera extends Script {
     const nx = this.boundsCenter.x + radius * Math.cos(newAngle);
     const nz = this.boundsCenter.z + radius * Math.sin(newAngle);
     const ny = this._hasGroundPlane ? yOnPlane(nx, nz, this._planeNormal, this._planePoint, this.boundsCenter.y) + this.averageCameraHeight : this.boundsCenter.y;
-    this.entity.setPosition(nx, ny, nz);
+    camera.setPosition(nx, ny, nz);
     const faceDx = this.boundsCenter.x - nx;
     const faceDz = this.boundsCenter.z - nz;
     this._yaw = Math.atan2(-faceDx, -faceDz) * (180 / Math.PI);
     this._targetYaw = this._yaw;
-    this.entity.setEulerAngles(this._pitch, this._yaw, 0);
+    camera.setEulerAngles(this._pitch, this._yaw, 0);
   }
 
   /**
@@ -232,13 +256,17 @@ class WalkthroughCamera extends Script {
    * Compatible with the useCameraPosition hook's focusPoint read.
    */
   get focusPoint() {
-    const pos = this.entity.getPosition();
+    const pos = (this._posedCamera() ?? this.entity).getPosition();
     _quat.setFromEulerAngles(this._pitch, this._yaw, 0);
     _quat.transformVector(Vec3.FORWARD, _flatForward);
     return new Vec3(pos.x + _flatForward.x, pos.y + _flatForward.y, pos.z + _flatForward.z);
   }
   update(dt) {
     this._syncGroundPlane();
+    const camera = this._posedCamera();
+    if (!camera) {
+      return;
+    }
 
     // Lerp current angles toward targets using the same damping as CameraControls.
     // Snap to the target once within ANGLE_EPSILON so the asymptotic lerp actually
@@ -262,9 +290,9 @@ class WalkthroughCamera extends Script {
     this._pitch = nextPitch;
     this._yaw = nextYaw;
     if (anglesChanged) {
-      this.entity.setEulerAngles(this._pitch, this._yaw, 0);
+      camera.setEulerAngles(this._pitch, this._yaw, 0);
     }
-    const pos = this.entity.getPosition();
+    const pos = camera.getPosition();
     let nx = pos.x;
     let ny = pos.y;
     let nz = pos.z;
@@ -308,7 +336,7 @@ class WalkthroughCamera extends Script {
     // idle frames; note it does not stop per-frame rasterization — while autoRender is on
     // the app renders every frame regardless of whether the transform changed.
     if (Math.abs(nx - pos.x) > POSITION_EPSILON || Math.abs(targetY - pos.y) > POSITION_EPSILON || Math.abs(nz - pos.z) > POSITION_EPSILON) {
-      this.entity.setPosition(nx, targetY, nz);
+      camera.setPosition(nx, targetY, nz);
     }
   }
   destroy() {

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

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

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

@@ -35,8 +35,8 @@ class XrAnnotationInteraction extends Script {
       entity,
       script
     } = candidates[index];
-    const camera = this.app.root.findByName('camera');
-    const screen = camera?.camera?.worldToScreen(entity.getPosition());
+    const camera = this.app.root.findComponent('camera');
+    const screen = camera?.worldToScreen(entity.getPosition());
     script.onVrOpenCallback(screen?.x ?? 0, screen?.y ?? 0);
   }
   initialize() {

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

@@ -12,6 +12,11 @@ export declare class XrExitButton extends Script {
     halfSize: number;
     /** World-space radius of the hover/hit sphere. Slightly larger than halfSize for easier targeting. */
     hitRadius: number;
+    /**
+     * Called in place of ending the XR session when the user activates the button, leaving the
+     * session running so the handler decides what happens next.
+     */
+    onClose?: () => void;
     private _material?;
     private _texture?;
     private _mesh?;
@@ -28,6 +33,8 @@ export declare class XrExitButton extends Script {
     private _onSelect;
     /** True when the ray points at the button's hit sphere. False while the button entity is disabled. */
     rayHitsButton(origin: Vec3, direction: Vec3): boolean;
+    /** The button's exit action: the `onClose` handler when one is set, otherwise ending the session. */
+    close(): void;
     /** The button's static artwork, painted once. Only the sweep changes per frame, and that lives in
      * the shader. */
     private _createMaskTexture;

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,EAOL,MAAM,EAGN,IAAI,EAGL,MAAM,YAAY,CAAC;AASpB;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,IAAI,EAAE,WAAW,IAAI,EAAE,QAAQ,IAAI,EAAE,QAAQ,MAAM,KAAG,OAUhG,CAAC;AAUF,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,CAAiB;IACnC,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,KAAK,CAAiC;IAC9C,OAAO,CAAC,OAAO,CAA2B;IAE1C,OAAO,CAAC,WAAW,CAAyE;IAE5F,OAAO,CAAC,UAAU,CAGhB;IAEF,OAAO,CAAC,QAAQ,CAMd;IAEF,OAAO,CAAC,SAAS,CAOf;IAEF,sGAAsG;IACtG,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,OAAO;IAQrD;qBACiB;IACjB,OAAO,CAAC,kBAAkB;IAyB1B,OAAO,CAAC,cAAc;IAKtB,UAAU;IAwBV,MAAM,CAAC,EAAE,EAAE,MAAM;IAiDjB;;;;;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,EAOL,MAAM,EAGN,IAAI,EAGL,MAAM,YAAY,CAAC;AASpB;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,IAAI,EAAE,WAAW,IAAI,EAAE,QAAQ,IAAI,EAAE,QAAQ,MAAM,KAAG,OAUhG,CAAC;AAUF,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;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAErB,OAAO,CAAC,SAAS,CAAC,CAAiB;IACnC,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,KAAK,CAAiC;IAC9C,OAAO,CAAC,OAAO,CAA2B;IAE1C,OAAO,CAAC,WAAW,CAAyE;IAE5F,OAAO,CAAC,UAAU,CAGhB;IAEF,OAAO,CAAC,QAAQ,CAMd;IAEF,OAAO,CAAC,SAAS,CAOf;IAEF,sGAAsG;IACtG,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,OAAO;IAQrD,qGAAqG;IACrG,KAAK;IASL;qBACiB;IACjB,OAAO,CAAC,kBAAkB;IAyB1B,OAAO,CAAC,cAAc;IAKtB,UAAU;IAwBV,MAAM,CAAC,EAAE,EAAE,MAAM;IAiDjB;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAuBlB,OAAO;CAcR"}

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

@@ -38,6 +38,12 @@ class XrExitButton extends Script {
 
   /** World-space radius of the hover/hit sphere. Slightly larger than halfSize for easier targeting. */
   hitRadius = 0.15;
+
+  /**
+   * Called in place of ending the XR session when the user activates the button, leaving the
+   * session running so the handler decides what happens next.
+   */
+
   _hovered = false;
   _headPosition = new Vec3();
   _headRotation = new Quat();
@@ -62,7 +68,7 @@ class XrExitButton extends Script {
       return;
     }
     if (this.rayHitsButton(inputSource.getOrigin(), inputSource.getDirection())) {
-      this.app.xr?.end();
+      this.close();
     }
   };
 
@@ -74,6 +80,15 @@ class XrExitButton extends Script {
     return raySphereIntersect(origin, direction, this.entity.getPosition(), this.hitRadius);
   }
 
+  /** The button's exit action: the `onClose` handler when one is set, otherwise ending the session. */
+  close() {
+    if (this.onClose) {
+      this.onClose();
+      return;
+    }
+    this.app.xr?.end();
+  }
+
   /** The button's static artwork, painted once. Only the sweep changes per frame, and that lives in
    * the shader. */
   _createMaskTexture() {
@@ -141,7 +156,7 @@ class XrExitButton extends Script {
       // trigger. Edge-detected so holding a button and then aiming onto it doesn't fire.
       const facePressed = this._faceButtons.justPressed(source);
       if (sourceHovers && facePressed) {
-        this.app.xr?.end();
+        this.close();
         return;
       }
 
@@ -155,7 +170,7 @@ class XrExitButton extends Script {
     this._hold = hold.state;
     this._material?.setParameter('uProgress', pieShaderProgress(hold.progress));
     if (hold.justFired) {
-      this.app.xr?.end();
+      this.close();
       return;
     }
     if (hovered !== this._hovered) {

package/components/VirtualWalkthrough/xr-gaze-dwell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xr-gaze-dwell.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-gaze-dwell.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,MAAM,EAKP,MAAM,YAAY,CAAC;AAmBpB,qBAAa,WAAY,SAAQ,MAAM;IACrC,MAAM,CAAC,UAAU,SAAiB;IAElC;6FACyF;IACzF,WAAW,SAAM;IAEjB,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,WAAW,CAAqC;IAExD,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,YAAY,CAAC,CAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,CAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,CAAU;IAE3B,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;;;;;OAKG;IACH,OAAO,CAAC,UAAU,CAGhB;IAEF,OAAO,CAAC,QAAQ,CAId;IAEF,OAAO,CAAC,cAAc;IAMtB,UAAU;IA4BV,MAAM,CAAC,EAAE,EAAE,MAAM;IAgCjB,OAAO,CAAC,UAAU;IAgBlB,uDAAuD;IACvD,OAAO,CAAC,SAAS;IAcjB,OAAO;CAiBR"}
+{"version":3,"file":"xr-gaze-dwell.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-gaze-dwell.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,MAAM,EAKP,MAAM,YAAY,CAAC;AAmBpB,qBAAa,WAAY,SAAQ,MAAM;IACrC,MAAM,CAAC,UAAU,SAAiB;IAElC;6FACyF;IACzF,WAAW,SAAM;IAEjB,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,WAAW,CAAqC;IAExD,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,YAAY,CAAC,CAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,CAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,CAAU;IAE3B,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;;;;;OAKG;IACH,OAAO,CAAC,UAAU,CAGhB;IAEF,OAAO,CAAC,QAAQ,CAId;IAEF,OAAO,CAAC,cAAc;IAMtB,UAAU;IA4BV,MAAM,CAAC,EAAE,EAAE,MAAM;IAgCjB,OAAO,CAAC,UAAU;IAgBlB,uDAAuD;IACvD,OAAO,CAAC,SAAS;IAcjB,OAAO;CAiBR"}

package/components/VirtualWalkthrough/xr-gaze-dwell.js

@@ -102,8 +102,8 @@ class XrGazeDwell extends Script {
         entity,
         script
       } = candidates[target];
-      const camera = this.app.root.findByName('camera');
-      const screen = camera?.camera?.worldToScreen(entity.getPosition());
+      const camera = this.app.root.findComponent('camera');
+      const screen = camera?.worldToScreen(entity.getPosition());
       script.onVrOpenCallback(screen?.x ?? 0, screen?.y ?? 0);
     }
   }

package/hooks/cameraEntityContext.d.ts

@@ -0,0 +1,12 @@
+import { Entity } from 'playcanvas';
+/**
+ * The camera entity the walkthrough owns, published by `VirtualWalkthroughViewer` for the hooks
+ * beneath it.
+ *
+ * Looking the camera up by name is not safe once the viewer shares a scene graph with a host that
+ * has entities of its own: `findByName('camera')` walks the whole graph and returns whichever
+ * entity was added first, so a host that names its own camera entity `camera` shadows the viewer's.
+ * Null outside a viewer, where the name lookup is still the only thing to go on.
+ */
+export declare const CameraEntityContext: import("react").Context<Entity | null>;
+//# sourceMappingURL=cameraEntityContext.d.ts.map

package/hooks/cameraEntityContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cameraEntityContext.d.ts","sourceRoot":"","sources":["../../src/hooks/cameraEntityContext.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEpC;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,wCAAqC,CAAC"}

package/hooks/cameraEntityContext.js

@@ -0,0 +1,14 @@
+import { createContext } from 'react';
+
+/**
+ * The camera entity the walkthrough owns, published by `VirtualWalkthroughViewer` for the hooks
+ * beneath it.
+ *
+ * Looking the camera up by name is not safe once the viewer shares a scene graph with a host that
+ * has entities of its own: `findByName('camera')` walks the whole graph and returns whichever
+ * entity was added first, so a host that names its own camera entity `camera` shadows the viewer's.
+ * Null outside a viewer, where the name lookup is still the only thing to go on.
+ */
+const CameraEntityContext = /*#__PURE__*/createContext(null);
+
+export { CameraEntityContext };

package/hooks/useCameraPosition.d.ts

@@ -1,4 +1,10 @@
-export declare const useCameraPosition: () => {
+import { Entity } from 'playcanvas';
+/**
+ * @param cameraEntity - The camera to drive. Callers above {@link CameraEntityContext} pass it
+ * directly; the ones beneath take it from the context, and anything with neither falls back to
+ * looking an entity named `camera` in the scene graph.
+ */
+export declare const useCameraPosition: (cameraEntity?: Entity | null) => {
     setCamera: (focus: [number, number, number], position?: [number, number, number], horizontalNdcBias?: number) => void;
     getCameraState: () => {
         position: [number, number, number];

package/hooks/useCameraPosition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCameraPosition.d.ts","sourceRoot":"","sources":["../../src/hooks/useCameraPosition.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,iBAAiB;uBAIlB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;;kBAqBf,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;eACrB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;;CAQpF,CAAC"}
+{"version":3,"file":"useCameraPosition.d.ts","sourceRoot":"","sources":["../../src/hooks/useCameraPosition.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAmB,MAAM,YAAY,CAAC;AAcrD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,eAAe,MAAM,GAAG,IAAI;uBAkBlD,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;;kBAmBf,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;eACrB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;;CAQpF,CAAC"}

package/hooks/useCameraPosition.js

@@ -1,22 +1,44 @@
-import { useCallback, useMemo } from 'react';
+import { useContext, useCallback, useMemo } from 'react';
 import { useApp } from '@playcanvas/react/hooks';
 import { Vec3 } from 'playcanvas';
+import { CameraEntityContext } from './cameraEntityContext.js';
 
-const useCameraPosition = () => {
+/** The camera-driving scripts this hook talks to. */
+
+/** Scripts are added to entities dynamically, so they aren't on the engine's types. */
+const scriptsOn = node => node?.script;
+
+/**
+ * @param cameraEntity - The camera to drive. Callers above {@link CameraEntityContext} pass it
+ * directly; the ones beneath take it from the context, and anything with neither falls back to
+ * looking an entity named `camera` in the scene graph.
+ */
+const useCameraPosition = cameraEntity => {
   const app = useApp();
+  const contextCamera = useContext(CameraEntityContext);
+  const resolvedCamera = cameraEntity ?? contextCamera;
+  const findCamera = useCallback(() => resolvedCamera ?? app.root.findByName('camera'), [app, resolvedCamera]);
+
+  /**
+   * The script driving the camera. WalkthroughCamera is mounted on the rig above the camera rather
+   * than on the camera entity, so that it poses a camera the walkthrough adopted from a host scene
+   * as readily as one of its own; CameraControls sits on the camera entity itself.
+   */
+  const findControls = useCallback(camera => {
+    const own = scriptsOn(camera);
+    return own?.cameraControls ?? own?.walkthroughCamera ?? scriptsOn(camera?.parent)?.walkthroughCamera;
+  }, []);
   const setCamera = useCallback((focus, position, horizontalNdcBias = 0) => {
-    const camera = app.root.findByName('camera');
-    // @ts-expect-error - scripts are added dynamically to the camera entity
-    const controls = camera?.script?.cameraControls ?? camera?.script?.walkthroughCamera;
+    const camera = findCamera();
+    const controls = findControls(camera);
     if (controls && camera) {
       // The extra bias arg is only honored by WalkthroughCamera; CameraControls ignores it.
       controls.reset(new Vec3(focus), position ? new Vec3(position) : camera.getPosition(), horizontalNdcBias);
     }
-  }, [app]);
+  }, [findCamera, findControls]);
   const getCameraState = useCallback(() => {
-    const camera = app.root.findByName('camera');
-    // @ts-expect-error - scripts are added dynamically to the camera entity
-    const controls = camera?.script?.cameraControls ?? camera?.script?.walkthroughCamera;
+    const camera = findCamera();
+    const controls = findControls(camera);
     if (camera && controls) {
       const position = camera.getPosition();
       const focusPoint = controls?.focusPoint;
@@ -26,7 +48,7 @@ const useCameraPosition = () => {
       };
     }
     return null;
-  }, [app]);
+  }, [findCamera, findControls]);
   return useMemo(() => ({
     setCamera,
     getCameraState

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terraware/web-components",
-  "version": "5.0.5",
+  "version": "5.0.7-rc.2",
   "author": "Terraformation Inc.",
   "license": "Apache-2.0",
   "repository": {