@ericchen1990/pano-view 2.4.0 → 2.5.1

package/dist/index.mjs

@@ -2274,6 +2274,20 @@ function subscribeBackgroundAudioHost(host, listener) {
     host.listeners.delete(listener);
   };
 }
+function subscribeBackgroundAudioStore(host, onStoreChange) {
+  let unsubscribeController = host.controller?.subscribe(onStoreChange) ?? (() => {
+  });
+  const unsubscribeHost = subscribeBackgroundAudioHost(host, () => {
+    unsubscribeController();
+    unsubscribeController = host.controller?.subscribe(onStoreChange) ?? (() => {
+    });
+    onStoreChange();
+  });
+  return () => {
+    unsubscribeController();
+    unsubscribeHost();
+  };
+}
 
 // src/cn.ts
 function cn(...values) {
@@ -5022,6 +5036,20 @@ function subscribePanoVideoHost(host, onStoreChange) {
     host.listeners.delete(onStoreChange);
   };
 }
+function subscribePanoVideoStore(host, onStoreChange) {
+  let unsubscribeController = host.controller?.subscribe(onStoreChange) ?? (() => {
+  });
+  const unsubscribeHost = subscribePanoVideoHost(host, () => {
+    unsubscribeController();
+    unsubscribeController = host.controller?.subscribe(onStoreChange) ?? (() => {
+    });
+    onStoreChange();
+  });
+  return () => {
+    unsubscribeController();
+    unsubscribeHost();
+  };
+}
 function getPanoVideoHostRevision(host) {
   return host.revision;
 }
@@ -6953,7 +6981,7 @@ var PanoViewer = forwardRef2(
         requestVRPermission: () => webVRHost.controller?.requestPermission() ?? Promise.resolve(false),
         // -- Video --
         getVideo: () => videoHost.controller,
-        subscribeVideo: (onStoreChange) => subscribePanoVideoHost(videoHost, onStoreChange),
+        subscribeVideo: (onStoreChange) => subscribePanoVideoStore(videoHost, onStoreChange),
         playVideo: () => videoHost.controller?.play() ?? Promise.resolve(),
         pauseVideo: () => videoHost.controller?.pause(),
         toggleVideo: () => videoHost.controller?.togglePlay(),
@@ -6963,7 +6991,7 @@ var PanoViewer = forwardRef2(
         toggleVideoMuted: () => videoHost.controller?.toggleMuted(),
         // -- Background Audio --
         getBackgroundAudio: () => bgmHost.controller,
-        subscribeBackgroundAudio: (onStoreChange) => subscribeBackgroundAudioHost(bgmHost, onStoreChange),
+        subscribeBackgroundAudio: (onStoreChange) => subscribeBackgroundAudioStore(bgmHost, onStoreChange),
         playBackgroundAudio: () => {
           bgmHost.controller?.play();
           return Promise.resolve();
@@ -7327,6 +7355,8 @@ function BackgroundAudio({
   const loopRef = useRef13(loop);
   const mutedRef = useRef13(muted);
   const volumeRef = useRef13(volume);
+  const mutedPropRef = useRef13(muted);
+  const volumePropRef = useRef13(volume);
   const fadeMsRef = useRef13(resolveFadeMs(fadeMs));
   const onPlaybackStateChangeRef = useRef13(onPlaybackStateChange);
   const onPlaybackErrorRef = useRef13(onPlaybackError);
@@ -7334,9 +7364,15 @@ function BackgroundAudio({
   const onErrorRef = useRef13(onError);
   playingRef.current = playing;
   loopRef.current = loop;
-  mutedRef.current = muted;
-  volumeRef.current = volume;
   fadeMsRef.current = resolveFadeMs(fadeMs);
+  if (mutedPropRef.current !== muted) {
+    mutedPropRef.current = muted;
+    mutedRef.current = muted;
+  }
+  if (volumePropRef.current !== volume) {
+    volumePropRef.current = volume;
+    volumeRef.current = volume;
+  }
   onPlaybackStateChangeRef.current = onPlaybackStateChange;
   onPlaybackErrorRef.current = onPlaybackError;
   onEndedRef.current = onEnded;
@@ -7390,20 +7426,17 @@ function BackgroundAudio({
         if (isControlledRef.current) {
           return;
         }
-        const howl = currentRef.current?.handle.howl;
-        if (howl) {
-          howl.volume(clampAudioVolume(vol));
-        }
-        notifySnapshot({ volume: clampAudioVolume(vol) });
+        const next = clampAudioVolume(vol);
+        volumeRef.current = next;
+        currentRef.current?.handle.howl.volume(next);
+        notifySnapshot({ volume: next });
       },
       setMuted: (m) => {
         if (isControlledRef.current) {
           return;
         }
-        const howl = currentRef.current?.handle.howl;
-        if (howl) {
-          howl.mute(m);
-        }
+        mutedRef.current = m;
+        currentRef.current?.handle.howl.mute(m);
         notifySnapshot({ muted: m });
       },
       toggleMuted: () => {
@@ -7411,10 +7444,8 @@ function BackgroundAudio({
           return;
         }
         const next = !snapshotRef.current.muted;
-        const howl = currentRef.current?.handle.howl;
-        if (howl) {
-          howl.mute(next);
-        }
+        mutedRef.current = next;
+        currentRef.current?.handle.howl.mute(next);
         notifySnapshot({ muted: next });
       }
     }),
@@ -7481,6 +7512,9 @@ function BackgroundAudio({
           shouldRetryPlay: () => currentRef.current?.key === trackKey && playingRef.current,
           onEnded: () => {
             notifySnapshot({ playing: false, ended: true });
+            if (!isControlledRef.current) {
+              setInternalPlaying(false);
+            }
             onPlaybackStateChangeRef.current?.("ended");
             onEndedRef.current?.();
           },
@@ -7553,7 +7587,9 @@ function BackgroundAudio({
     }
     if (!playing) {
       fadingInRef.current = false;
-      howl.pause();
+      if (howl.playing()) {
+        howl.pause();
+      }
       for (const slot of outgoingRef.current) {
         slot.handle.dispose();
       }
@@ -7568,11 +7604,14 @@ function BackgroundAudio({
       return;
     }
     slot.handle.howl.loop(loop);
-    slot.handle.howl.mute(muted);
+    slot.handle.howl.mute(mutedRef.current);
     if (!fadingInRef.current) {
-      slot.handle.howl.volume(clampAudioVolume(volume));
+      slot.handle.howl.volume(clampAudioVolume(volumeRef.current));
     }
-    notifySnapshot({ muted, volume: clampAudioVolume(volume) });
+    notifySnapshot({
+      muted: mutedRef.current,
+      volume: clampAudioVolume(volumeRef.current)
+    });
   }, [loop, muted, trackKey, volume]);
   useEffect13(() => {
     if (!pauseWhenHidden) {
@@ -9178,9 +9217,92 @@ var WebVR = forwardRef4(function WebVR2({
   ] });
 });
 
+// src/use-pano-viewer.ts
+import { useMemo as useMemo12, useRef as useRef19 } from "react";
+function createPanoViewerHandle(ref) {
+  return {
+    getView: () => ref.current?.getView() ?? { yaw: 0, pitch: 0, fov: 75 },
+    setView: (view, options) => {
+      ref.current?.setView(view, options);
+    },
+    reset: () => {
+      ref.current?.reset();
+    },
+    enterFullscreen: () => ref.current?.enterFullscreen() ?? Promise.resolve(),
+    exitFullscreen: () => ref.current?.exitFullscreen() ?? Promise.resolve(),
+    toggleFullscreen: () => ref.current?.toggleFullscreen() ?? Promise.resolve(),
+    isFullscreen: () => ref.current?.isFullscreen() ?? false,
+    setScene: (id) => ref.current?.setScene(id) ?? false,
+    nextScene: () => ref.current?.nextScene() ?? false,
+    previousScene: () => ref.current?.previousScene() ?? false,
+    getActiveSceneId: () => ref.current?.getActiveSceneId() ?? null,
+    getSceneIds: () => ref.current?.getSceneIds() ?? [],
+    isSceneTransitioning: () => ref.current?.isSceneTransitioning() ?? false,
+    enterVR: () => ref.current?.enterVR() ?? Promise.resolve(false),
+    exitVR: () => ref.current?.exitVR() ?? Promise.resolve(),
+    toggleVR: () => ref.current?.toggleVR() ?? Promise.resolve(false),
+    isVRAvailable: () => ref.current?.isVRAvailable() ?? false,
+    isVREnabled: () => ref.current?.isVREnabled() ?? false,
+    getVRMode: () => ref.current?.getVRMode() ?? null,
+    requestVRPermission: () => ref.current?.requestVRPermission() ?? Promise.resolve(false),
+    getVideo: () => ref.current?.getVideo() ?? null,
+    subscribeVideo: (onStoreChange) => ref.current?.subscribeVideo(onStoreChange) ?? (() => {
+    }),
+    playVideo: () => ref.current?.playVideo() ?? Promise.resolve(),
+    pauseVideo: () => {
+      ref.current?.pauseVideo();
+    },
+    toggleVideo: () => {
+      ref.current?.toggleVideo();
+    },
+    seekVideo: (time) => {
+      ref.current?.seekVideo(time);
+    },
+    setVideoVolume: (volume) => {
+      ref.current?.setVideoVolume(volume);
+    },
+    setVideoMuted: (muted) => {
+      ref.current?.setVideoMuted(muted);
+    },
+    toggleVideoMuted: () => {
+      ref.current?.toggleVideoMuted();
+    },
+    getBackgroundAudio: () => ref.current?.getBackgroundAudio() ?? null,
+    subscribeBackgroundAudio: (onStoreChange) => ref.current?.subscribeBackgroundAudio(onStoreChange) ?? (() => {
+    }),
+    playBackgroundAudio: () => ref.current?.playBackgroundAudio() ?? Promise.resolve(),
+    pauseBackgroundAudio: () => {
+      ref.current?.pauseBackgroundAudio();
+    },
+    toggleBackgroundAudio: () => {
+      ref.current?.toggleBackgroundAudio();
+    },
+    setBackgroundAudioVolume: (volume) => {
+      ref.current?.setBackgroundAudioVolume(volume);
+    },
+    setBackgroundAudioMuted: (muted) => {
+      ref.current?.setBackgroundAudioMuted(muted);
+    },
+    toggleBackgroundAudioMuted: () => {
+      ref.current?.toggleBackgroundAudioMuted();
+    },
+    startAutoRotate: () => {
+      ref.current?.startAutoRotate();
+    },
+    stopAutoRotate: () => {
+      ref.current?.stopAutoRotate();
+    }
+  };
+}
+function usePanoViewer() {
+  const ref = useRef19(null);
+  const handle = useMemo12(() => createPanoViewerHandle(ref), []);
+  return useMemo12(() => ({ ref, ...handle }), [handle]);
+}
+
 // src/sphere.tsx
 import { useThree as useThree13 } from "@react-three/fiber";
-import { useEffect as useEffect20, useMemo as useMemo13, useRef as useRef20, useState as useState9 } from "react";
+import { useEffect as useEffect20, useMemo as useMemo14, useRef as useRef21, useState as useState9 } from "react";
 import {
   BackSide as BackSide2,
   LinearFilter,
@@ -9213,7 +9335,7 @@ function resolveUrlAgainstFile(fileUrl, path) {
 }
 
 // src/pano-filter/pano-basic-material.tsx
-import { useLayoutEffect as useLayoutEffect2, useMemo as useMemo12, useRef as useRef19 } from "react";
+import { useLayoutEffect as useLayoutEffect2, useMemo as useMemo13, useRef as useRef20 } from "react";
 
 // src/pano-filter/shaders.ts
 var GLSL_FILTER_COMMON = `
@@ -9373,13 +9495,13 @@ function PanoBasicMaterial({
   toneMapped = false
 }) {
   const snapshot = usePanoFilterSnapshot();
-  const materialRef = useRef19(null);
-  const intensityRef = useRef19(snapshot.intensity);
-  const intensityUniformRef = useRef19(null);
+  const materialRef = useRef20(null);
+  const intensityRef = useRef20(snapshot.intensity);
+  const intensityUniformRef = useRef20(null);
   intensityRef.current = snapshot.intensity;
   const active = isPanoFilterActive(snapshot);
   const preset = snapshot.preset;
-  const onBeforeCompile = useMemo12(() => {
+  const onBeforeCompile = useMemo13(() => {
     if (!active || preset === "none") {
       return void 0;
     }
@@ -9430,8 +9552,8 @@ function PanoBasicMaterial({
 import { jsx as jsx15, jsxs as jsxs9 } from "react/jsx-runtime";
 function useEquirectTexture(url, anisotropy, generateMipmaps, onLoad, onError) {
   const [texture, setTexture] = useState9(null);
-  const onLoadRef = useRef20(onLoad);
-  const onErrorRef = useRef20(onError);
+  const onLoadRef = useRef21(onLoad);
+  const onErrorRef = useRef21(onError);
   onLoadRef.current = onLoad;
   onErrorRef.current = onError;
   useEffect20(() => {
@@ -9493,7 +9615,7 @@ function Sphere({
 }) {
   const gl = useThree13((state) => state.gl);
   const anisotropy = gl.capabilities.getMaxAnisotropy();
-  const resolvedPreviewUrl = useMemo13(
+  const resolvedPreviewUrl = useMemo14(
     () => resolveUrlAgainstFile(src, previewUrl),
     [previewUrl, src]
   );
@@ -9512,7 +9634,7 @@ function Sphere({
     onPreviewError
   );
   const displayTexture = texture ?? previewTexture;
-  const readyRef = useRef20(false);
+  const readyRef = useRef21(false);
   useEffect20(() => {
     readyRef.current = false;
   }, [resolvedPreviewUrl, src]);
@@ -9553,8 +9675,8 @@ import {
   useContext as useContext20,
   useEffect as useEffect21,
   useLayoutEffect as useLayoutEffect3,
-  useMemo as useMemo14,
-  useRef as useRef21,
+  useMemo as useMemo15,
+  useRef as useRef22,
   useState as useState10
 } from "react";
 import {
@@ -9653,7 +9775,7 @@ function applyEquirectangularLayout(texture, anisotropy) {
 function usePosterTexture(poster, onError) {
   const gl = useThree14((state) => state.gl);
   const [texture, setTexture] = useState10(null);
-  const onErrorRef = useRef21(onError);
+  const onErrorRef = useRef22(onError);
   onErrorRef.current = onError;
   useEffect21(() => {
     let active = true;
@@ -9752,13 +9874,13 @@ function PanoVideo({
   const gl = useThree14((state) => state.gl);
   const host = useContext20(PanoVideoHostContext);
   const overlay = useContext20(PanoChromeOverlayContext);
-  const variants = useMemo14(
+  const variants = useMemo15(
     () => resolvePanoVideoVariants({ poster, src, variants: variantsProp }),
     [poster, src, variantsProp]
   );
   const tracks = tracksProp ?? EMPTY_TRACKS;
   const captionsEnabled = captions !== false;
-  const captionAppearance = useMemo14(
+  const captionAppearance = useMemo15(
     () => resolvePanoVideoCaptionAppearance(
       typeof captions === "object" ? captions : void 0
     ),
@@ -9771,17 +9893,17 @@ function PanoVideo({
     () => captionsEnabled ? defaultPanoVideoTrackId(tracks) : null
   );
   const [ready, setReady] = useState10(false);
-  const autoPlayRef = useRef21(autoPlay);
+  const autoPlayRef = useRef22(autoPlay);
   autoPlayRef.current = autoPlay;
-  const blockedRef = useRef21(false);
-  const captionAppearanceOverrideRef = useRef21(
+  const blockedRef = useRef22(false);
+  const captionAppearanceOverrideRef = useRef22(
     {}
   );
-  const mediaCapabilitiesRef = useRef21({
+  const mediaCapabilitiesRef = useRef22({
     volumeAdjustable: true,
     playbackRates: [...DEFAULT_PANO_VIDEO_PLAYBACK_RATES]
   });
-  const storeRef = useRef21(null);
+  const storeRef = useRef22(null);
   if (!storeRef.current) {
     storeRef.current = {
       snapshot: {
@@ -9791,7 +9913,7 @@ function PanoVideo({
       listeners: /* @__PURE__ */ new Set()
     };
   }
-  const actionsRef = useRef21({
+  const actionsRef = useRef22({
     play: async () => {
     },
     pause: () => {
@@ -9811,19 +9933,19 @@ function PanoVideo({
     setCaptionAppearance: (_appearance) => {
     }
   });
-  const onLoadRef = useRef21(onLoad);
-  const onErrorRef = useRef21(onError);
-  const onPlaybackStateChangeRef = useRef21(onPlaybackStateChange);
-  const onEndedRef = useRef21(onEnded);
-  const onVariantChangeRef = useRef21(onVariantChange);
-  const onTrackChangeRef = useRef21(onTrackChange);
+  const onLoadRef = useRef22(onLoad);
+  const onErrorRef = useRef22(onError);
+  const onPlaybackStateChangeRef = useRef22(onPlaybackStateChange);
+  const onEndedRef = useRef22(onEnded);
+  const onVariantChangeRef = useRef22(onVariantChange);
+  const onTrackChangeRef = useRef22(onTrackChange);
   onLoadRef.current = onLoad;
   onErrorRef.current = onError;
   onPlaybackStateChangeRef.current = onPlaybackStateChange;
   onEndedRef.current = onEnded;
   onVariantChangeRef.current = onVariantChange;
   onTrackChangeRef.current = onTrackChange;
-  const resource = useMemo14(() => {
+  const resource = useMemo15(() => {
     if (typeof document === "undefined") {
       return null;
     }
@@ -9936,7 +10058,7 @@ function PanoVideo({
       captionAppearance
     ]
   );
-  const controller = useMemo14(
+  const controller = useMemo15(
     () => ({
       subscribe: (onStoreChange) => {
         const store = storeRef.current;
@@ -10303,8 +10425,8 @@ import {
   useCallback as useCallback10,
   useContext as useContext22,
   useEffect as useEffect26,
-  useMemo as useMemo19,
-  useRef as useRef25,
+  useMemo as useMemo20,
+  useRef as useRef26,
   useState as useState12
 } from "react";
 import {
@@ -10361,7 +10483,7 @@ function isSnapshotTransition(preset) {
 
 // src/scene-transitions/particle-overlay.tsx
 import { useFrame as useFrame9, useThree as useThree15 } from "@react-three/fiber";
-import { useEffect as useEffect22, useMemo as useMemo15, useRef as useRef22 } from "react";
+import { useEffect as useEffect22, useMemo as useMemo16, useRef as useRef23 } from "react";
 import {
   DoubleSide as DoubleSide2,
   InstancedBufferAttribute,
@@ -10501,12 +10623,12 @@ function ParticleOverlay({
   onFinish
 }) {
   const { camera } = useThree15();
-  const meshRef = useRef22(null);
-  const startRef = useRef22(null);
-  const finishedRef = useRef22(false);
-  const directionRef = useRef22(new Vector39());
-  const geometry = useMemo15(() => createParticleGeometry(), []);
-  const material = useMemo15(
+  const meshRef = useRef23(null);
+  const startRef = useRef23(null);
+  const finishedRef = useRef23(false);
+  const directionRef = useRef23(new Vector39());
+  const geometry = useMemo16(() => createParticleGeometry(), []);
+  const material = useMemo16(
     () => new ShaderMaterial2({
       transparent: true,
       depthTest: false,
@@ -10560,7 +10682,7 @@ function ParticleOverlay({
 
 // src/scene-transitions/snapshot-overlay.tsx
 import { useFrame as useFrame10, useThree as useThree16 } from "@react-three/fiber";
-import { useEffect as useEffect23, useMemo as useMemo16, useRef as useRef23 } from "react";
+import { useEffect as useEffect23, useMemo as useMemo17, useRef as useRef24 } from "react";
 import { Vector3 as Vector310 } from "three";
 
 // src/scene-transitions/snapshot-shaders.ts
@@ -10849,11 +10971,11 @@ function SnapshotOverlay({
   onFinish
 }) {
   const { camera, gl } = useThree16();
-  const meshRef = useRef23(null);
-  const startRef = useRef23(null);
-  const finishedRef = useRef23(false);
-  const directionRef = useRef23(new Vector310());
-  const material = useMemo16(() => {
+  const meshRef = useRef24(null);
+  const startRef = useRef24(null);
+  const finishedRef = useRef24(false);
+  const directionRef = useRef24(new Vector310());
+  const material = useMemo17(() => {
     if (!isSnapshotTransition(transition.preset)) {
       return null;
     }
@@ -10946,7 +11068,7 @@ import {
   createContext as createContext13,
   useContext as useContext21,
   useEffect as useEffect24,
-  useMemo as useMemo17
+  useMemo as useMemo18
 } from "react";
 
 // src/tile/texture-manager.ts
@@ -11187,7 +11309,7 @@ function TileTextureManagerProvider({
 }) {
   const gl = useThree17((state) => state.gl);
   const anisotropy = gl.capabilities.getMaxAnisotropy();
-  const manager = useMemo17(
+  const manager = useMemo18(
     () => new TileTextureManager({
       anisotropy,
       maxBytes: Math.max(1, maxTextureMemoryMb) * 1024 * 1024,
@@ -11211,8 +11333,8 @@ import { useFrame as useFrame11, useThree as useThree18 } from "@react-three/fib
 import {
   memo,
   useEffect as useEffect25,
-  useMemo as useMemo18,
-  useRef as useRef24,
+  useMemo as useMemo19,
+  useRef as useRef25,
   useState as useState11
 } from "react";
 import {
@@ -11419,7 +11541,7 @@ var PREVIEW_RADIUS = CUBE_RADIUS + 0.05;
 var SHARED_TILE_GEOMETRY = new PlaneGeometry4(1, 1);
 function usePreviewTexture(url, anisotropy, onError) {
   const [texture, setTexture] = useState11(null);
-  const onErrorRef = useRef24(onError);
+  const onErrorRef = useRef25(onError);
   onErrorRef.current = onError;
   useEffect25(() => {
     if (!url) {
@@ -11471,7 +11593,7 @@ function PreviewFace({
   texture,
   faceOrder
 }) {
-  const geometry = useMemo18(() => {
+  const geometry = useMemo19(() => {
     const nextGeometry = new PlaneGeometry4(
       PREVIEW_RADIUS * 2,
       PREVIEW_RADIUS * 2
@@ -11757,10 +11879,10 @@ function Tile({
   onLevelChange
 }) {
   const { camera, gl, size } = useThree18();
-  const multiresConfig = useMemo18(() => parseMultires(multires), [multires]);
+  const multiresConfig = useMemo19(() => parseMultires(multires), [multires]);
   const { levels, tileSize } = multiresConfig;
   const multiresToken = `${tileSize}:${levels.join(",")}`;
-  const candidatesByLevel = useMemo18(
+  const candidatesByLevel = useMemo19(
     () => buildTileCandidates(levels, tileSize),
     [levels, tileSize]
   );
@@ -11772,13 +11894,13 @@ function Tile({
     onPreviewError
   );
   const sharedManager = useSharedTileTextureManager();
-  const progressRef = useRef24(onLoadProgress);
-  const errorRef = useRef24(onTileError);
-  const levelChangeRef = useRef24(onLevelChange);
+  const progressRef = useRef25(onLoadProgress);
+  const errorRef = useRef25(onTileError);
+  const levelChangeRef = useRef25(onLevelChange);
   progressRef.current = onLoadProgress;
   errorRef.current = onTileError;
   levelChangeRef.current = onLevelChange;
-  const ownedManager = useMemo18(
+  const ownedManager = useMemo19(
     () => new TileTextureManager({
       anisotropy,
       maxBytes: Math.max(1, maxTextureMemoryMb) * 1024 * 1024,
@@ -11809,7 +11931,7 @@ function Tile({
       queueMicrotask(() => manager.releaseUnused());
     };
   }, [manager, ownedManager]);
-  const readyRef = useRef24(false);
+  const readyRef = useRef25(false);
   useEffect25(() => {
     readyRef.current = false;
   }, [effectivePreviewUrl]);
@@ -11821,7 +11943,7 @@ function Tile({
     onReady?.();
   }, [onReady, previewTexture]);
   const template = urlTemplate ?? buildDefaultTileUrlTemplate();
-  const resolveUrl = useMemo18(
+  const resolveUrl = useMemo19(
     () => (address) => {
       const relativePath = resolveTileUrl ? resolveTileUrl(address) : resolveTemplateUrl(template, address);
       return resolveRelativeTileUrl(baseUrl, relativePath);
@@ -11829,16 +11951,16 @@ function Tile({
     [baseUrl, resolveTileUrl, template]
   );
   const [layers, setLayers] = useState11([]);
-  const layerTokenRef = useRef24("");
-  const currentLevelRef = useRef24(1);
-  const lastUpdateAtRef = useRef24(-Infinity);
-  const visibilityDirtyRef = useRef24(true);
-  const lastVisibilityQuaternionRef = useRef24(camera.quaternion.clone());
-  const lastVisibilityFovRef = useRef24(Number.NaN);
-  const lastViewportRef = useRef24({ width: 0, height: 0, dpr: 0 });
-  const frustumRef = useRef24(new Frustum());
-  const projectionMatrixRef = useRef24(new Matrix4());
-  const visibilityCameraRef = useRef24(new PerspectiveCamera4());
+  const layerTokenRef = useRef25("");
+  const currentLevelRef = useRef25(1);
+  const lastUpdateAtRef = useRef25(-Infinity);
+  const visibilityDirtyRef = useRef25(true);
+  const lastVisibilityQuaternionRef = useRef25(camera.quaternion.clone());
+  const lastVisibilityFovRef = useRef25(Number.NaN);
+  const lastViewportRef = useRef25({ width: 0, height: 0, dpr: 0 });
+  const frustumRef = useRef25(new Frustum());
+  const projectionMatrixRef = useRef25(new Matrix4());
+  const visibilityCameraRef = useRef25(new PerspectiveCamera4());
   useEffect25(() => {
     currentLevelRef.current = 1;
     layerTokenRef.current = "";
@@ -11996,8 +12118,8 @@ function SnapshotCapture({
   onCaptured
 }) {
   const { camera, gl, scene, size } = useThree19();
-  const capturedRequestRef = useRef25(0);
-  const renderTargetRef = useRef25(null);
+  const capturedRequestRef = useRef26(0);
+  const renderTargetRef = useRef26(null);
   useEffect26(
     () => () => {
       renderTargetRef.current?.dispose();
@@ -12056,11 +12178,11 @@ function ScenesController({
 }) {
   const controlsRef = useContext22(PanoramaViewContext);
   const manager = useSharedTileTextureManager();
-  const transition = useMemo19(
+  const transition = useMemo20(
     () => resolveTransition(transitionInput),
     [transitionInput]
   );
-  const sceneMap = useMemo19(
+  const sceneMap = useMemo20(
     () => new Map(scenes.map((scene) => [scene.id, scene])),
     [scenes]
   );
@@ -12077,13 +12199,13 @@ function ScenesController({
   const [transitionRunId, setTransitionRunId] = useState12(0);
   const [snapshot, setSnapshot] = useState12(null);
   const [recoveryKey, setRecoveryKey] = useState12(0);
-  const requestedSceneIdRef = useRef25(activeSceneId);
-  const captureReasonRef = useRef25("start");
-  const interactionReleaseRef = useRef25(null);
-  const slotsRef = useRef25(slots);
-  const phaseRef = useRef25(phase);
-  const liveSlotRef = useRef25(liveSlot);
-  const transitionFromRef = useRef25(initialScene);
+  const requestedSceneIdRef = useRef26(activeSceneId);
+  const captureReasonRef = useRef26("start");
+  const interactionReleaseRef = useRef26(null);
+  const slotsRef = useRef26(slots);
+  const phaseRef = useRef26(phase);
+  const liveSlotRef = useRef26(liveSlot);
+  const transitionFromRef = useRef26(initialScene);
   slotsRef.current = slots;
   phaseRef.current = phase;
   if (externalPhaseRef) {
@@ -12305,12 +12427,12 @@ function Scenes({
     },
     [isControlled, onActiveSceneIdChange]
   );
-  const scenesRef = useRef25(scenes);
+  const scenesRef = useRef26(scenes);
   scenesRef.current = scenes;
-  const resolvedIdRef = useRef25(resolvedId);
+  const resolvedIdRef = useRef26(resolvedId);
   resolvedIdRef.current = resolvedId;
   const host = useContext22(ScenesHostContext);
-  const phaseRef = useRef25("idle");
+  const phaseRef = useRef26("idle");
   useEffect26(() => {
     if (!host) {
       return;
@@ -12381,7 +12503,7 @@ function Scenes({
 
 // src/hotspot/image-hotspot.tsx
 import { useThree as useThree21 } from "@react-three/fiber";
-import { useEffect as useEffect29, useRef as useRef27, useState as useState15 } from "react";
+import { useEffect as useEffect29, useRef as useRef28, useState as useState15 } from "react";
 import {
   ClampToEdgeWrapping as ClampToEdgeWrapping3,
   LinearFilter as LinearFilter6,
@@ -12396,8 +12518,8 @@ import {
   useContext as useContext24,
   useEffect as useEffect28,
   useLayoutEffect as useLayoutEffect4,
-  useMemo as useMemo21,
-  useRef as useRef26,
+  useMemo as useMemo22,
+  useRef as useRef27,
   useState as useState14
 } from "react";
 import {
@@ -12414,7 +12536,7 @@ import {
 } from "three";
 
 // src/hotspot/hotspot-tooltip.tsx
-import { useEffect as useEffect27, useMemo as useMemo20, useState as useState13 } from "react";
+import { useEffect as useEffect27, useMemo as useMemo21, useState as useState13 } from "react";
 
 // src/webvr/stereo-html.tsx
 import { Html } from "@react-three/drei";
@@ -12542,11 +12664,11 @@ function HotspotTooltip({
     setImageFailed(false);
   }, [content.image]);
   const showImage = Boolean(content.image) && !imageFailed;
-  const resolvedAppearance = useMemo20(
+  const resolvedAppearance = useMemo21(
     () => resolveHotspotTooltipAppearance(appearance),
     [appearance]
   );
-  const bubbleStyle = useMemo20(
+  const bubbleStyle = useMemo21(
     () => ({
       background: resolvedAppearance.background,
       border: resolvedAppearance.border,
@@ -12929,14 +13051,14 @@ function HotspotAnchor({
   const eventBus = useContext24(PanoEventBusContext);
   const cursorApi = usePanoCursor();
   const { camera, size } = useThree20();
-  const groupRef = useRef26(null);
-  const tooltipAnchorRef = useRef26(null);
-  const dragStateRef = useRef26(null);
-  const suppressNextClickRef = useRef26(false);
+  const groupRef = useRef27(null);
+  const tooltipAnchorRef = useRef27(null);
+  const dragStateRef = useRef27(null);
+  const suppressNextClickRef = useRef27(false);
   const [hovered, setHovered] = useState14(false);
   const [dragging, setDragging] = useState14(false);
   const [pinned, setPinned] = useState14(false);
-  const tooltipContent = useMemo21(
+  const tooltipContent = useMemo22(
     () => resolveHotspotTooltipContent(tooltip),
     [tooltip]
   );
@@ -12952,17 +13074,17 @@ function HotspotAnchor({
     scaledWidth,
     scaledHeight
   );
-  const worldPosition = useMemo21(
+  const worldPosition = useMemo22(
     () => panoPositionToVector3(normalizedPosition, resolvedDistance),
     [normalizedPosition.pitch, normalizedPosition.yaw, resolvedDistance]
   );
-  const surfaceQuaternion3 = useMemo21(
+  const surfaceQuaternion3 = useMemo22(
     () => createSurfaceQuaternion(normalizedPosition),
     [normalizedPosition.pitch, normalizedPosition.yaw]
   );
   const worldWidth = angularSizeToWorldSize(scaledWidth, resolvedDistance);
   const worldHeight = angularSizeToWorldSize(scaledHeight, resolvedDistance);
-  const focusGeometry = useMemo21(() => {
+  const focusGeometry = useMemo22(() => {
     const planeGeometry = new PlaneGeometry5(1, 1);
     const geometry = new EdgesGeometry(planeGeometry);
     planeGeometry.dispose();
@@ -13384,8 +13506,8 @@ import { jsx as jsx27 } from "react/jsx-runtime";
 function useHotspotImageTexture(src, onLoad, onError) {
   const gl = useThree21((state) => state.gl);
   const [texture, setTexture] = useState15(null);
-  const onLoadRef = useRef27(onLoad);
-  const onErrorRef = useRef27(onError);
+  const onLoadRef = useRef28(onLoad);
+  const onErrorRef = useRef28(onError);
   onLoadRef.current = onLoad;
   onErrorRef.current = onError;
   useEffect29(() => {
@@ -13448,7 +13570,7 @@ function ImageHotspot({
 }
 
 // src/hotspot/polygon-hotspot.tsx
-import { useEffect as useEffect30, useMemo as useMemo22, useRef as useRef29 } from "react";
+import { useEffect as useEffect30, useMemo as useMemo23, useRef as useRef30 } from "react";
 import {
   BufferGeometry,
   DoubleSide as DoubleSide5,
@@ -13463,7 +13585,7 @@ import {
 // src/hotspot/hotspot-stroke-line.tsx
 import { Line } from "@react-three/drei";
 import { useFrame as useFrame14, useThree as useThree22 } from "@react-three/fiber";
-import { useLayoutEffect as useLayoutEffect5, useRef as useRef28 } from "react";
+import { useLayoutEffect as useLayoutEffect5, useRef as useRef29 } from "react";
 import {
   MathUtils as MathUtils8,
   PerspectiveCamera as PerspectiveCamera6,
@@ -13500,7 +13622,7 @@ function HotspotStrokeLine({
   dashSize,
   gapSize
 }) {
-  const lineRef = useRef28(null);
+  const lineRef = useRef29(null);
   const { camera, size } = useThree22();
   const dash = resolveDash(dashSize, gapSize);
   useLayoutEffect5(() => {
@@ -13793,19 +13915,19 @@ function PolygonHotspot({
   onInvalid,
   ...anchorProps
 }) {
-  const issues = useMemo22(() => validatePolygonVertices(vertices), [vertices]);
+  const issues = useMemo23(() => validatePolygonVertices(vertices), [vertices]);
   const valid = issues.length === 0;
-  const center = useMemo22(() => valid ? polygonCenter(vertices) : null, [valid, vertices]);
-  const fillGeometry = useMemo22(
+  const center = useMemo23(() => valid ? polygonCenter(vertices) : null, [valid, vertices]);
+  const fillGeometry = useMemo23(
     () => valid && center ? makeFillGeometry(vertices, center) : null,
     [center, valid, vertices]
   );
-  const strokePoints = useMemo22(
+  const strokePoints = useMemo23(
     () => valid && center ? makeStrokePositions(vertices, center) : null,
     [center, valid, vertices]
   );
   const resolvedStrokeOpacity = Math.max(0, Math.min(strokeOpacity, 1));
-  const startVerticesRef = useRef29(null);
+  const startVerticesRef = useRef30(null);
   const issuesKey = issues.map((issue) => issue.code).join(",");
   useEffect30(() => {
     if (!valid) onInvalid?.(issues);
@@ -13890,7 +14012,7 @@ function PolygonHotspot({
 }
 
 // src/hotspot/polyline-hotspot.tsx
-import { useEffect as useEffect31, useMemo as useMemo23, useRef as useRef30 } from "react";
+import { useEffect as useEffect31, useMemo as useMemo24, useRef as useRef31 } from "react";
 import {
   MathUtils as MathUtils9,
   Matrix4 as Matrix44,
@@ -14014,15 +14136,15 @@ function PolylineHotspot({
   onInvalid,
   ...anchorProps
 }) {
-  const issues = useMemo23(() => validatePolylineVertices(vertices), [vertices]);
+  const issues = useMemo24(() => validatePolylineVertices(vertices), [vertices]);
   const valid = issues.length === 0;
-  const center = useMemo23(() => valid ? polylineCenter(vertices) : null, [valid, vertices]);
-  const linePoints = useMemo23(
+  const center = useMemo24(() => valid ? polylineCenter(vertices) : null, [valid, vertices]);
+  const linePoints = useMemo24(
     () => valid && center ? makeLinePositions(vertices, center) : null,
     [center, valid, vertices]
   );
   const opacity = Math.max(0, Math.min(strokeOpacity, 1));
-  const startVerticesRef = useRef30(null);
+  const startVerticesRef = useRef31(null);
   useEffect31(() => {
     if (!valid) onInvalid?.(issues);
   }, [issues, onInvalid, valid]);
@@ -14089,7 +14211,7 @@ function PolylineHotspot({
 }
 
 // src/hotspot/graphic-hotspot.tsx
-import { useEffect as useEffect32, useRef as useRef31, useState as useState16 } from "react";
+import { useEffect as useEffect32, useRef as useRef32, useState as useState16 } from "react";
 import {
   CanvasTexture,
   ClampToEdgeWrapping as ClampToEdgeWrapping4,
@@ -14287,8 +14409,8 @@ function createGraphicTexture(graphic, aspectWidth, aspectHeight) {
 }
 function useGraphicTexture(graphic, aspectWidth, aspectHeight, onLoad, onError) {
   const [texture, setTexture] = useState16(null);
-  const onLoadRef = useRef31(onLoad);
-  const onErrorRef = useRef31(onError);
+  const onLoadRef = useRef32(onLoad);
+  const onErrorRef = useRef32(onError);
   onLoadRef.current = onLoad;
   onErrorRef.current = onError;
   useEffect32(() => {
@@ -14330,7 +14452,7 @@ function GraphicHotspot(props) {
 
 // src/hotspot/sequence-hotspot.tsx
 import { useFrame as useFrame15, useThree as useThree23 } from "@react-three/fiber";
-import { useEffect as useEffect33, useRef as useRef32, useState as useState17 } from "react";
+import { useEffect as useEffect33, useRef as useRef33, useState as useState17 } from "react";
 import {
   ClampToEdgeWrapping as ClampToEdgeWrapping5,
   LinearFilter as LinearFilter8,
@@ -14354,8 +14476,8 @@ function useSpriteTexture({
 }) {
   const gl = useThree23((state) => state.gl);
   const [texture, setTexture] = useState17(null);
-  const onErrorRef = useRef32(onError);
-  const onLoadProgressRef = useRef32(onLoadProgress);
+  const onErrorRef = useRef33(onError);
+  const onLoadProgressRef = useRef33(onLoadProgress);
   onErrorRef.current = onError;
   onLoadProgressRef.current = onLoadProgress;
   useEffect33(() => {
@@ -14429,13 +14551,13 @@ function SequenceHotspot({
   const frameCount = resolveFrameCount(requestedFrameCount);
   const safeFps = resolveFps(fps);
   const [frameIndex, setFrameIndex] = useState17(0);
-  const elapsedRef = useRef32(0);
-  const frameIndexRef = useRef32(0);
-  const endedRef = useRef32(false);
-  const lastPlaybackStateRef = useRef32(null);
-  const onFrameChangeRef = useRef32(onFrameChange);
-  const onPlaybackStateChangeRef = useRef32(onPlaybackStateChange);
-  const onEndedRef = useRef32(onEnded);
+  const elapsedRef = useRef33(0);
+  const frameIndexRef = useRef33(0);
+  const endedRef = useRef33(false);
+  const lastPlaybackStateRef = useRef33(null);
+  const onFrameChangeRef = useRef33(onFrameChange);
+  const onPlaybackStateChangeRef = useRef33(onPlaybackStateChange);
+  const onEndedRef = useRef33(onEnded);
   onFrameChangeRef.current = onFrameChange;
   onPlaybackStateChangeRef.current = onPlaybackStateChange;
   onEndedRef.current = onEnded;
@@ -14519,7 +14641,7 @@ function SequenceHotspot({
 
 // src/hotspot/video-hotspot.tsx
 import { useThree as useThree24 } from "@react-three/fiber";
-import { useEffect as useEffect34, useRef as useRef33, useState as useState18 } from "react";
+import { useEffect as useEffect34, useRef as useRef34, useState as useState18 } from "react";
 import {
   ClampToEdgeWrapping as ClampToEdgeWrapping6,
   LinearFilter as LinearFilter9,
@@ -14538,7 +14660,7 @@ function clampVolume2(volume) {
 function usePosterTexture2(id, poster, onError) {
   const gl = useThree24((state) => state.gl);
   const [texture, setTexture] = useState18(null);
-  const onErrorRef = useRef33(onError);
+  const onErrorRef = useRef34(onError);
   onErrorRef.current = onError;
   useEffect34(() => {
     let active = true;
@@ -14596,9 +14718,9 @@ function useVideoResource({
   src
 }) {
   const [resource, setResource] = useState18(null);
-  const onEndedRef = useRef33(onEnded);
-  const onErrorRef = useRef33(onError);
-  const onPlaybackStateChangeRef = useRef33(onPlaybackStateChange);
+  const onEndedRef = useRef34(onEnded);
+  const onErrorRef = useRef34(onError);
+  const onPlaybackStateChangeRef = useRef34(onPlaybackStateChange);
   onEndedRef.current = onEnded;
   onErrorRef.current = onError;
   onPlaybackStateChangeRef.current = onPlaybackStateChange;
@@ -14703,8 +14825,8 @@ function VideoHotspot({
     src
   });
   const posterTexture = usePosterTexture2(id, poster, onError);
-  const onPlaybackErrorRef = useRef33(onPlaybackError);
-  const onPlaybackStateChangeRef = useRef33(onPlaybackStateChange);
+  const onPlaybackErrorRef = useRef34(onPlaybackError);
+  const onPlaybackStateChangeRef = useRef34(onPlaybackStateChange);
   onPlaybackErrorRef.current = onPlaybackError;
   onPlaybackStateChangeRef.current = onPlaybackStateChange;
   useEffect34(() => {
@@ -14745,7 +14867,7 @@ function VideoHotspot({
 
 // src/hotspot/audio-hotspot.tsx
 import { useFrame as useFrame16, useThree as useThree25 } from "@react-three/fiber";
-import { useEffect as useEffect35, useRef as useRef34, useState as useState19 } from "react";
+import { useEffect as useEffect35, useRef as useRef35, useState as useState19 } from "react";
 import {
   CanvasTexture as CanvasTexture2,
   ClampToEdgeWrapping as ClampToEdgeWrapping7,
@@ -14837,7 +14959,7 @@ function useSpeakerTextures(enabled) {
 function useIconTexture(icon, enabled, onError, id) {
   const gl = useThree25((state) => state.gl);
   const [texture, setTexture] = useState19(null);
-  const onErrorRef = useRef34(onError);
+  const onErrorRef = useRef35(onError);
   onErrorRef.current = onError;
   useEffect35(() => {
     let active = true;
@@ -14896,12 +15018,12 @@ function useAudioHowl({
   src
 }) {
   const [howl, setHowl] = useState19(null);
-  const playingRef = useRef34(playing);
-  const loopRef = useRef34(loop ?? false);
-  const onEndedRef = useRef34(onEnded);
-  const onErrorRef = useRef34(onError);
-  const onPlaybackErrorRef = useRef34(onPlaybackError);
-  const onPlaybackStateChangeRef = useRef34(onPlaybackStateChange);
+  const playingRef = useRef35(playing);
+  const loopRef = useRef35(loop ?? false);
+  const onEndedRef = useRef35(onEnded);
+  const onErrorRef = useRef35(onError);
+  const onPlaybackErrorRef = useRef35(onPlaybackError);
+  const onPlaybackStateChangeRef = useRef35(onPlaybackStateChange);
   playingRef.current = playing;
   loopRef.current = loop ?? false;
   onEndedRef.current = onEnded;
@@ -14989,11 +15111,11 @@ function AudioHotspot({
   const stoppedIconTexture = useIconTexture(icon, marker, onError, id);
   const playingIconTexture = useIconTexture(playingIcon, marker, onError, id);
   const markerTexture = playing ? playingIconTexture ?? stoppedIconTexture ?? speakerTextures.playing : stoppedIconTexture ?? speakerTextures.stopped;
-  const playingRef = useRef34(playing);
+  const playingRef = useRef35(playing);
   playingRef.current = playing;
-  const mutedRef = useRef34(muted);
-  const volumeRef = useRef34(volume);
-  const rangeRef = useRef34(range);
+  const mutedRef = useRef35(muted);
+  const volumeRef = useRef35(volume);
+  const rangeRef = useRef35(range);
   mutedRef.current = muted;
   volumeRef.current = volume;
   rangeRef.current = range;
@@ -15042,7 +15164,7 @@ function AudioHotspot({
 }
 
 // src/hotspot/text-hotspot.tsx
-import { useEffect as useEffect36, useRef as useRef35, useState as useState20 } from "react";
+import { useEffect as useEffect36, useRef as useRef36, useState as useState20 } from "react";
 import {
   CanvasTexture as CanvasTexture3,
   ClampToEdgeWrapping as ClampToEdgeWrapping8,
@@ -15271,8 +15393,8 @@ function createTextTexture(text, width, height, style) {
 }
 function useTextTexture(text, width, height, style, onLoad, onError) {
   const [texture, setTexture] = useState20(null);
-  const onLoadRef = useRef35(onLoad);
-  const onErrorRef = useRef35(onError);
+  const onLoadRef = useRef36(onLoad);
+  const onErrorRef = useRef36(onError);
   onLoadRef.current = onLoad;
   onErrorRef.current = onError;
   useEffect36(() => {
@@ -15538,6 +15660,7 @@ export {
   resolvePanoContextMenuEntries,
   unwrapPolygonVertices,
   usePanoEvents,
+  usePanoViewer,
   validatePolygonVertices,
   validatePolylineVertices,
   vector3ToPanoPosition