@ericchen1990/pano-view 2.3.0 → 2.5.0

package/dist/index.mjs

@@ -2252,6 +2252,29 @@ import {
   useState as useState5
 } from "react";
 
+// src/background-audio-host.ts
+import { createContext } from "react";
+var BackgroundAudioHostContext = createContext(null);
+function createBackgroundAudioHost() {
+  return {
+    controller: null,
+    revision: 0,
+    listeners: /* @__PURE__ */ new Set()
+  };
+}
+function notifyBackgroundAudioHost(host) {
+  host.revision += 1;
+  for (const listener of host.listeners) {
+    listener();
+  }
+}
+function subscribeBackgroundAudioHost(host, listener) {
+  host.listeners.add(listener);
+  return () => {
+    host.listeners.delete(listener);
+  };
+}
+
 // src/cn.ts
 function cn(...values) {
   return values.filter(Boolean).join(" ");
@@ -2262,7 +2285,7 @@ import { useFrame as useFrame2 } from "@react-three/fiber";
 import { useContext, useEffect as useEffect2, useRef as useRef2 } from "react";
 
 // src/pano-event-bus.ts
-import { createContext } from "react";
+import { createContext as createContext2 } from "react";
 function createPanoEventBus() {
   const listeners = /* @__PURE__ */ new Map();
   return {
@@ -2291,13 +2314,13 @@ function createPanoEventBus() {
     }
   };
 }
-var PanoEventBusContext = createContext(null);
+var PanoEventBusContext = createContext2(null);
 
 // src/panorama-view-runtime.tsx
 import { useFrame, useThree } from "@react-three/fiber";
 import { useXR } from "@react-three/xr";
 import {
-  createContext as createContext2,
+  createContext as createContext3,
   forwardRef,
   useEffect,
   useImperativeHandle,
@@ -2313,7 +2336,7 @@ var DEFAULT_ROTATE_DAMPING = 14;
 var DEFAULT_ZOOM_DAMPING = 16;
 var DEFAULT_FRICTION_STOP = 0.01;
 var VIEW_SETTLE_EPSILON = 1e-3;
-var PanoramaViewContext = createContext2(null);
+var PanoramaViewContext = createContext3(null);
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
 }
@@ -2790,9 +2813,9 @@ function AutoRotate({
 }
 
 // src/control-claims.ts
-import { createContext as createContext3, useContext as useContext2 } from "react";
-var ControlClaimsContext = createContext3(null);
-var DefaultControlChannelContext = createContext3(false);
+import { createContext as createContext4, useContext as useContext2 } from "react";
+var ControlClaimsContext = createContext4(null);
+var DefaultControlChannelContext = createContext4(false);
 var CHANNEL_COMPONENT = {
   mouse: "MouseControls",
   touch: "TouchControls",
@@ -2874,7 +2897,7 @@ function subscribeFullscreenChange(onChange) {
 
 // src/hotspot/accessibility.tsx
 import {
-  createContext as createContext4,
+  createContext as createContext5,
   useCallback,
   useContext as useContext3,
   useEffect as useEffect3,
@@ -2883,7 +2906,7 @@ import {
   useState
 } from "react";
 import { jsx } from "react/jsx-runtime";
-var HotspotAccessibilityContext = createContext4(null);
+var HotspotAccessibilityContext = createContext5(null);
 function warnAboutMissingLabel(id) {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   if (nodeEnv !== "production") {
@@ -3393,7 +3416,7 @@ function MouseControls({
 }
 
 // src/pano-filter/host.ts
-import { createContext as createContext5, useContext as useContext6, useSyncExternalStore } from "react";
+import { createContext as createContext6, useContext as useContext6, useSyncExternalStore } from "react";
 
 // src/pano-filter/presets.ts
 var PANO_FILTER_PRESETS = [
@@ -3434,7 +3457,7 @@ function isPanoFilterActive(snapshot) {
 }
 
 // src/pano-filter/host.ts
-var PanoFilterHostContext = createContext5(null);
+var PanoFilterHostContext = createContext6(null);
 function createPanoFilterHost() {
   return {
     snapshot: { ...DEFAULT_PANO_FILTER_SNAPSHOT },
@@ -3504,7 +3527,7 @@ function isProduction2() {
 
 // src/pano-context-menu.tsx
 import {
-  createContext as createContext6,
+  createContext as createContext7,
   useCallback as useCallback2,
   useContext as useContext7,
   useEffect as useEffect6,
@@ -3518,7 +3541,7 @@ import { jsx as jsx2, jsxs } from "react/jsx-runtime";
 var DEFAULT_ICON_SIZE = 16;
 var MENU_EDGE_PADDING = 8;
 var MIN_PANO_CONTEXT_MENU_BACKGROUND_OPACITY = 0.4;
-var PanoContextMenuOverlayContext = createContext6(null);
+var PanoContextMenuOverlayContext = createContext7(null);
 var DEFAULT_APPEARANCE = {
   background: "#161616",
   color: "#f4f4f4",
@@ -4183,12 +4206,12 @@ function composePanoContextMenuItems(props, presets) {
     ...resolvePanoContextMenuEntries(props.append ?? [], presets)
   ];
 }
-var PanoContextMenuActionsContext = createContext6(null);
+var PanoContextMenuActionsContext = createContext7(null);
 
 // src/pano-cursor.tsx
 import { useThree as useThree4 } from "@react-three/fiber";
 import {
-  createContext as createContext7,
+  createContext as createContext8,
   useCallback as useCallback3,
   useContext as useContext8,
   useEffect as useEffect7,
@@ -4209,7 +4232,7 @@ var LAYER_PRIORITY = {
   hotspotDragging: 3,
   hidden: 4
 };
-var PanoCursorContext = createContext7(null);
+var PanoCursorContext = createContext8(null);
 function usePanoCursor() {
   return useContext8(PanoCursorContext);
 }
@@ -4783,6 +4806,23 @@ function PanoramaEventSurface() {
   );
 }
 
+// src/scenes-host.ts
+import { createContext as createContext9 } from "react";
+var ScenesHostContext = createContext9(null);
+function createScenesHost() {
+  return {
+    controller: null,
+    revision: 0,
+    listeners: /* @__PURE__ */ new Set()
+  };
+}
+function notifyScenesHost(host) {
+  host.revision += 1;
+  for (const listener of host.listeners) {
+    listener();
+  }
+}
+
 // src/touch-controls.tsx
 import { useThree as useThree7 } from "@react-three/fiber";
 import { useContext as useContext11, useEffect as useEffect10, useRef as useRef9 } from "react";
@@ -4931,9 +4971,9 @@ function TouchControls({
 }
 
 // src/video/chrome-overlay.tsx
-import { createContext as createContext8, useCallback as useCallback4, useMemo as useMemo5, useState as useState3 } from "react";
+import { createContext as createContext10, useCallback as useCallback4, useMemo as useMemo5, useState as useState3 } from "react";
 import { jsx as jsx5 } from "react/jsx-runtime";
-var PanoChromeOverlayContext = createContext8(null);
+var PanoChromeOverlayContext = createContext10(null);
 function usePanoChromeOverlay() {
   const [overlayElement, setOverlayElement] = useState3(
     null
@@ -4957,9 +4997,9 @@ function usePanoChromeOverlay() {
 }
 
 // src/video/host.ts
-import { createContext as createContext9, useContext as useContext12 } from "react";
-var PanoVideoHostContext = createContext9(null);
-var DefaultPanoVideoControlsContext = createContext9(false);
+import { createContext as createContext11, useContext as useContext12 } from "react";
+var PanoVideoHostContext = createContext11(null);
+var DefaultPanoVideoControlsContext = createContext11(false);
 function createPanoVideoHost() {
   return {
     controller: null,
@@ -6216,8 +6256,8 @@ function PanoVideoChromeBridge({
 import { useSyncExternalStore as useSyncExternalStore5 } from "react";
 
 // src/webvr/host.ts
-import { createContext as createContext10 } from "react";
-var WebVRRuntimeContext = createContext10(null);
+import { createContext as createContext12 } from "react";
+var WebVRRuntimeContext = createContext12(null);
 function createWebVRHost() {
   return {
     controller: null,
@@ -6698,6 +6738,8 @@ var PanoViewer = forwardRef2(
     const videoHost = useMemo7(() => createPanoVideoHost(), []);
     const filterHost = useMemo7(() => createPanoFilterHost(), []);
     const webVRHost = useMemo7(() => createWebVRHost(), []);
+    const scenesHost = useMemo7(() => createScenesHost(), []);
+    const bgmHost = useMemo7(() => createBackgroundAudioHost(), []);
     const stereoView = useMemo7(() => createWebVRStereoView(), []);
     const xrStore = useMemo7(
       () => createXRStore({
@@ -6781,6 +6823,28 @@ var PanoViewer = forwardRef2(
       }),
       [controlOptions.keyboard]
     );
+    const enterFullscreen = useCallback6(async () => {
+      if (typeof document === "undefined") {
+        return;
+      }
+      if (getFullscreenElement()) {
+        return;
+      }
+      const root = rootRef.current;
+      if (!root) {
+        return;
+      }
+      await requestElementFullscreen(root);
+    }, []);
+    const exitFullscreen = useCallback6(async () => {
+      if (typeof document === "undefined") {
+        return;
+      }
+      if (!getFullscreenElement()) {
+        return;
+      }
+      await exitElementFullscreen();
+    }, []);
     const toggleFullscreen = useCallback6(async () => {
       if (typeof document === "undefined") {
         return;
@@ -6854,9 +6918,12 @@ var PanoViewer = forwardRef2(
     useEffect12(() => {
       setLegacyAutoRotate(legacyAutoRotateOptions.autoRotate ?? false);
     }, [legacyAutoRotateOptions.autoRotate]);
+    const isFullscreenRef = useRef12(false);
+    isFullscreenRef.current = isViewerFullscreen;
     useImperativeHandle2(
       ref,
       () => ({
+        // -- View --
         getView: () => controlsRef.current?.getView() ?? { ...fallbackViewRef.current },
         setView: (view, options) => {
           controlsRef.current?.setView(view, options);
@@ -6864,15 +6931,65 @@ var PanoViewer = forwardRef2(
         reset: () => {
           controlsRef.current?.reset();
         },
+        // -- Fullscreen --
+        enterFullscreen,
+        exitFullscreen,
+        toggleFullscreen,
+        isFullscreen: () => isFullscreenRef.current,
+        // -- Scenes --
+        setScene: (id) => scenesHost.controller?.setScene(id) ?? false,
+        nextScene: () => scenesHost.controller?.nextScene() ?? false,
+        previousScene: () => scenesHost.controller?.previousScene() ?? false,
+        getActiveSceneId: () => scenesHost.controller?.getActiveSceneId() ?? null,
+        getSceneIds: () => scenesHost.controller?.getSceneIds() ?? [],
+        isSceneTransitioning: () => scenesHost.controller?.isTransitioning() ?? false,
+        // -- WebVR --
+        enterVR: () => webVRHost.controller?.enterVR() ?? Promise.resolve(false),
+        exitVR: () => webVRHost.controller?.exitVR() ?? Promise.resolve(),
+        toggleVR: () => webVRHost.controller?.toggleVR() ?? Promise.resolve(false),
+        isVRAvailable: () => webVRHost.snapshot.available,
+        isVREnabled: () => webVRHost.snapshot.mode !== null,
+        getVRMode: () => webVRHost.snapshot.mode,
+        requestVRPermission: () => webVRHost.controller?.requestPermission() ?? Promise.resolve(false),
+        // -- Video --
+        getVideo: () => videoHost.controller,
+        subscribeVideo: (onStoreChange) => subscribePanoVideoHost(videoHost, onStoreChange),
+        playVideo: () => videoHost.controller?.play() ?? Promise.resolve(),
+        pauseVideo: () => videoHost.controller?.pause(),
+        toggleVideo: () => videoHost.controller?.togglePlay(),
+        seekVideo: (time) => videoHost.controller?.seek(time),
+        setVideoVolume: (vol) => videoHost.controller?.setVolume(vol),
+        setVideoMuted: (m) => videoHost.controller?.setMuted(m),
+        toggleVideoMuted: () => videoHost.controller?.toggleMuted(),
+        // -- Background Audio --
+        getBackgroundAudio: () => bgmHost.controller,
+        subscribeBackgroundAudio: (onStoreChange) => subscribeBackgroundAudioHost(bgmHost, onStoreChange),
+        playBackgroundAudio: () => {
+          bgmHost.controller?.play();
+          return Promise.resolve();
+        },
+        pauseBackgroundAudio: () => bgmHost.controller?.pause(),
+        toggleBackgroundAudio: () => bgmHost.controller?.togglePlay(),
+        setBackgroundAudioVolume: (vol) => bgmHost.controller?.setVolume(vol),
+        setBackgroundAudioMuted: (m) => bgmHost.controller?.setMuted(m),
+        toggleBackgroundAudioMuted: () => bgmHost.controller?.toggleMuted(),
+        // -- Deprecated --
         startAutoRotate: () => {
           setLegacyAutoRotate(true);
         },
         stopAutoRotate: () => {
           setLegacyAutoRotate(false);
-        },
-        toggleFullscreen
+        }
       }),
-      [toggleFullscreen]
+      [
+        bgmHost,
+        enterFullscreen,
+        exitFullscreen,
+        scenesHost,
+        toggleFullscreen,
+        videoHost,
+        webVRHost
+      ]
     );
     const rootStyle = useMemo7(
       () => ({
@@ -6924,11 +7041,11 @@ var PanoViewer = forwardRef2(
                       PanoContextMenuOverlayContext.Provider,
                       {
                         value: contextMenuOverlayApi,
-                        children: /* @__PURE__ */ jsx11(PanoChromeOverlayContext.Provider, { value: chromeOverlayApi, children: /* @__PURE__ */ jsx11(PanoVideoHostContext.Provider, { value: videoHost, children: /* @__PURE__ */ jsx11(PanoFilterHostContext.Provider, { value: filterHost, children: /* @__PURE__ */ jsxs6(
+                        children: /* @__PURE__ */ jsx11(PanoChromeOverlayContext.Provider, { value: chromeOverlayApi, children: /* @__PURE__ */ jsx11(PanoVideoHostContext.Provider, { value: videoHost, children: /* @__PURE__ */ jsx11(PanoFilterHostContext.Provider, { value: filterHost, children: /* @__PURE__ */ jsx11(
                           PanoContextMenuActionsContext.Provider,
                           {
                             value: contextMenuActions,
-                            children: [
+                            children: /* @__PURE__ */ jsx11(ScenesHostContext.Provider, { value: scenesHost, children: /* @__PURE__ */ jsxs6(BackgroundAudioHostContext.Provider, { value: bgmHost, children: [
                               /* @__PURE__ */ jsx11(PanoVideoHostReset, {}),
                               /* @__PURE__ */ jsx11(
                                 PanoramaViewRuntime,
@@ -6972,7 +7089,7 @@ var PanoViewer = forwardRef2(
                                   }
                                 )
                               ] })
-                            ]
+                            ] }) })
                           }
                         ) }) }) })
                       }
@@ -7010,7 +7127,7 @@ var PanoViewer = forwardRef2(
 );
 
 // src/background-audio.tsx
-import { useContext as useContext15, useEffect as useEffect13, useRef as useRef13 } from "react";
+import { useContext as useContext15, useEffect as useEffect13, useMemo as useMemo8, useRef as useRef13, useState as useState6 } from "react";
 
 // src/audio/howl.ts
 var import_howler = __toESM(require_howler());
@@ -7180,7 +7297,8 @@ function BackgroundAudio({
   src,
   sources,
   sceneId,
-  playing,
+  playing: controlledPlaying,
+  defaultPlaying = false,
   loop = true,
   muted = false,
   volume = 1,
@@ -7196,6 +7314,9 @@ function BackgroundAudio({
   if (!controlsRef) {
     throw new Error("<BackgroundAudio> must be rendered inside <PanoViewer>.");
   }
+  const isControlled = controlledPlaying !== void 0;
+  const [internalPlaying, setInternalPlaying] = useState6(defaultPlaying);
+  const playing = isControlled ? controlledPlaying : internalPlaying;
   const urls = resolveBackgroundAudioUrls(src, sources, sceneId);
   const trackKey = urls.join("\0");
   const currentRef = useRef13(null);
@@ -7220,6 +7341,99 @@ function BackgroundAudio({
   onPlaybackErrorRef.current = onPlaybackError;
   onEndedRef.current = onEnded;
   onErrorRef.current = onError;
+  const snapshotRef = useRef13({
+    ready: false,
+    playing: false,
+    blocked: false,
+    ended: false,
+    muted,
+    volume
+  });
+  const snapshotListenersRef = useRef13(/* @__PURE__ */ new Set());
+  const notifySnapshot = (patch) => {
+    const prev = snapshotRef.current;
+    snapshotRef.current = { ...prev, ...patch };
+    for (const listener of snapshotListenersRef.current) {
+      listener();
+    }
+  };
+  const isControlledRef = useRef13(isControlled);
+  isControlledRef.current = isControlled;
+  const controller = useMemo8(
+    () => ({
+      subscribe: (onStoreChange) => {
+        snapshotListenersRef.current.add(onStoreChange);
+        return () => {
+          snapshotListenersRef.current.delete(onStoreChange);
+        };
+      },
+      getSnapshot: () => snapshotRef.current,
+      play: () => {
+        if (isControlledRef.current) {
+          return;
+        }
+        setInternalPlaying(true);
+      },
+      pause: () => {
+        if (isControlledRef.current) {
+          return;
+        }
+        setInternalPlaying(false);
+      },
+      togglePlay: () => {
+        if (isControlledRef.current) {
+          return;
+        }
+        setInternalPlaying((prev) => !prev);
+      },
+      setVolume: (vol) => {
+        if (isControlledRef.current) {
+          return;
+        }
+        const howl = currentRef.current?.handle.howl;
+        if (howl) {
+          howl.volume(clampAudioVolume(vol));
+        }
+        notifySnapshot({ volume: clampAudioVolume(vol) });
+      },
+      setMuted: (m) => {
+        if (isControlledRef.current) {
+          return;
+        }
+        const howl = currentRef.current?.handle.howl;
+        if (howl) {
+          howl.mute(m);
+        }
+        notifySnapshot({ muted: m });
+      },
+      toggleMuted: () => {
+        if (isControlledRef.current) {
+          return;
+        }
+        const next = !snapshotRef.current.muted;
+        const howl = currentRef.current?.handle.howl;
+        if (howl) {
+          howl.mute(next);
+        }
+        notifySnapshot({ muted: next });
+      }
+    }),
+    []
+  );
+  const bgmHost = useContext15(BackgroundAudioHostContext);
+  useEffect13(() => {
+    if (!bgmHost) {
+      return;
+    }
+    bgmHost.controller = controller;
+    notifyBackgroundAudioHost(bgmHost);
+    return () => {
+      if (bgmHost.controller === controller) {
+        bgmHost.controller = null;
+        notifyBackgroundAudioHost(bgmHost);
+      }
+    };
+  }, [bgmHost, controller]);
   useEffect13(() => {
     return () => {
       fadingInRef.current = false;
@@ -7266,6 +7480,7 @@ function BackgroundAudio({
           isActive: () => currentRef.current?.key === trackKey,
           shouldRetryPlay: () => currentRef.current?.key === trackKey && playingRef.current,
           onEnded: () => {
+            notifySnapshot({ playing: false, ended: true });
             onPlaybackStateChangeRef.current?.("ended");
             onEndedRef.current?.();
           },
@@ -7277,15 +7492,18 @@ function BackgroundAudio({
                 durationMs
               );
             }
+            notifySnapshot({ ready: true, playing: true, blocked: false, ended: false });
             onPlaybackStateChangeRef.current?.("playing");
           },
           onPause: () => {
+            notifySnapshot({ playing: false });
             onPlaybackStateChangeRef.current?.("paused");
           },
           onLoadError: (error) => {
             onErrorRef.current?.({ error });
           },
           onPlayError: (error) => {
+            notifySnapshot({ blocked: true });
             onPlaybackStateChangeRef.current?.("blocked");
             onPlaybackErrorRef.current?.(error);
           }
@@ -7354,6 +7572,7 @@ function BackgroundAudio({
     if (!fadingInRef.current) {
       slot.handle.howl.volume(clampAudioVolume(volume));
     }
+    notifySnapshot({ muted, volume: clampAudioVolume(volume) });
   }, [loop, muted, trackKey, volume]);
   useEffect13(() => {
     if (!pauseWhenHidden) {
@@ -7381,7 +7600,7 @@ function BackgroundAudio({
 }
 
 // src/pano-filter/pano-filter.tsx
-import { useContext as useContext16, useEffect as useEffect14, useMemo as useMemo8 } from "react";
+import { useContext as useContext16, useEffect as useEffect14, useMemo as useMemo9 } from "react";
 function PanoFilter({
   preset = "none",
   intensity,
@@ -7391,7 +7610,7 @@ function PanoFilter({
   if (!host) {
     throw new Error("<PanoFilter> must be rendered inside <PanoViewer>.");
   }
-  const snapshot = useMemo8(
+  const snapshot = useMemo9(
     () => resolvePanoFilterSnapshot({ preset, intensity, enabled }),
     [enabled, intensity, preset]
   );
@@ -7416,7 +7635,7 @@ import {
   useEffect as useEffect15,
   useImperativeHandle as useImperativeHandle3,
   useRef as useRef14,
-  useState as useState6
+  useState as useState7
 } from "react";
 
 // src/gyro-orientation.ts
@@ -7520,7 +7739,7 @@ var Gyro = forwardRef3(function Gyro2({
   const controlsRef = useContext17(PanoramaViewContext);
   const eventBus = useContext17(PanoEventBusContext);
   const { gl } = useThree9();
-  const [internallyDisabled, setInternallyDisabled] = useState6(false);
+  const [internallyDisabled, setInternallyDisabled] = useState7(false);
   const availableRef = useRef14(false);
   const availabilityReportedRef = useRef14(null);
   const activeRef = useRef14(false);
@@ -7876,9 +8095,9 @@ import {
   useContext as useContext19,
   useEffect as useEffect19,
   useImperativeHandle as useImperativeHandle4,
-  useMemo as useMemo10,
+  useMemo as useMemo11,
   useRef as useRef18,
-  useState as useState7
+  useState as useState8
 } from "react";
 
 // src/webvr/detect.ts
@@ -8162,7 +8381,7 @@ function WebVRReticle({
 
 // src/webvr/stereo.tsx
 import { useFrame as useFrame8, useThree as useThree11 } from "@react-three/fiber";
-import { useContext as useContext18, useEffect as useEffect16, useMemo as useMemo9, useRef as useRef16 } from "react";
+import { useContext as useContext18, useEffect as useEffect16, useMemo as useMemo10, useRef as useRef16 } from "react";
 import {
   Mesh as Mesh2,
   OrthographicCamera,
@@ -8256,7 +8475,7 @@ function WebVRStereoRenderer({
   const stereo = runtime?.stereoView.stereo ?? fallbackStereoRef.current;
   const stereoRef = useRef16(stereo);
   stereoRef.current = stereo;
-  const resources = useMemo9(createDistortionResources, []);
+  const resources = useMemo10(createDistortionResources, []);
   const drawingSizeRef = useRef16(new Vector23());
   const viewportRef = useRef16(new Vector4());
   const scissorRef = useRef16(new Vector4());
@@ -8635,8 +8854,8 @@ var WebVR = forwardRef4(function WebVR2({
   const availableRef = useRef18(false);
   const modeRef = useRef18(null);
   const webXRSessionRef = useRef18(null);
-  const [mode, setMode] = useState7(null);
-  const [settings, setSettings] = useState7(
+  const [mode, setMode] = useState8(null);
+  const [settings, setSettings] = useState8(
     () => initializeSettings(screensize, profile)
   );
   const callbacksRef = useRef18({
@@ -8659,7 +8878,7 @@ var WebVR = forwardRef4(function WebVR2({
     throw new Error("<WebVR> must be rendered inside <PanoViewer>.");
   }
   const { host, xrStore } = runtime;
-  const resolvedProfile = useMemo10(
+  const resolvedProfile = useMemo11(
     () => resolveWebVRProfile(profile, settings.profileId),
     [profile, settings.profileId]
   );
@@ -8824,16 +9043,17 @@ var WebVR = forwardRef4(function WebVR2({
     setSettings(normalized);
     saveWebVRSettings(normalized);
   }, []);
-  const controller = useMemo10(
+  const controller = useMemo11(
     () => ({
       closeSetup: () => updateWebVRHost(host, { setupOpen: false }),
       enterVR,
       exitVR,
       openSetup: () => updateWebVRHost(host, { setupOpen: true }),
+      requestPermission,
       toggleVR,
       updateSettings
     }),
-    [enterVR, exitVR, host, toggleVR, updateSettings]
+    [enterVR, exitVR, host, requestPermission, toggleVR, updateSettings]
   );
   useImperativeHandle4(
     ref,
@@ -8958,9 +9178,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 useMemo12, useRef as useRef20, useState as useState8 } from "react";
+import { useEffect as useEffect20, useMemo as useMemo14, useRef as useRef21, useState as useState9 } from "react";
 import {
   BackSide as BackSide2,
   LinearFilter,
@@ -8993,7 +9296,7 @@ function resolveUrlAgainstFile(fileUrl, path) {
 }
 
 // src/pano-filter/pano-basic-material.tsx
-import { useLayoutEffect as useLayoutEffect2, useMemo as useMemo11, 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 = `
@@ -9153,13 +9456,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 = useMemo11(() => {
+  const onBeforeCompile = useMemo13(() => {
     if (!active || preset === "none") {
       return void 0;
     }
@@ -9209,9 +9512,9 @@ function PanoBasicMaterial({
 // src/sphere.tsx
 import { jsx as jsx15, jsxs as jsxs9 } from "react/jsx-runtime";
 function useEquirectTexture(url, anisotropy, generateMipmaps, onLoad, onError) {
-  const [texture, setTexture] = useState8(null);
-  const onLoadRef = useRef20(onLoad);
-  const onErrorRef = useRef20(onError);
+  const [texture, setTexture] = useState9(null);
+  const onLoadRef = useRef21(onLoad);
+  const onErrorRef = useRef21(onError);
   onLoadRef.current = onLoad;
   onErrorRef.current = onError;
   useEffect20(() => {
@@ -9273,7 +9576,7 @@ function Sphere({
 }) {
   const gl = useThree13((state) => state.gl);
   const anisotropy = gl.capabilities.getMaxAnisotropy();
-  const resolvedPreviewUrl = useMemo12(
+  const resolvedPreviewUrl = useMemo14(
     () => resolveUrlAgainstFile(src, previewUrl),
     [previewUrl, src]
   );
@@ -9292,7 +9595,7 @@ function Sphere({
     onPreviewError
   );
   const displayTexture = texture ?? previewTexture;
-  const readyRef = useRef20(false);
+  const readyRef = useRef21(false);
   useEffect20(() => {
     readyRef.current = false;
   }, [resolvedPreviewUrl, src]);
@@ -9333,9 +9636,9 @@ import {
   useContext as useContext20,
   useEffect as useEffect21,
   useLayoutEffect as useLayoutEffect3,
-  useMemo as useMemo13,
-  useRef as useRef21,
-  useState as useState9
+  useMemo as useMemo15,
+  useRef as useRef22,
+  useState as useState10
 } from "react";
 import {
   BackSide as BackSide3,
@@ -9432,8 +9735,8 @@ function applyEquirectangularLayout(texture, anisotropy) {
 }
 function usePosterTexture(poster, onError) {
   const gl = useThree14((state) => state.gl);
-  const [texture, setTexture] = useState9(null);
-  const onErrorRef = useRef21(onError);
+  const [texture, setTexture] = useState10(null);
+  const onErrorRef = useRef22(onError);
   onErrorRef.current = onError;
   useEffect21(() => {
     let active = true;
@@ -9532,36 +9835,36 @@ function PanoVideo({
   const gl = useThree14((state) => state.gl);
   const host = useContext20(PanoVideoHostContext);
   const overlay = useContext20(PanoChromeOverlayContext);
-  const variants = useMemo13(
+  const variants = useMemo15(
     () => resolvePanoVideoVariants({ poster, src, variants: variantsProp }),
     [poster, src, variantsProp]
   );
   const tracks = tracksProp ?? EMPTY_TRACKS;
   const captionsEnabled = captions !== false;
-  const captionAppearance = useMemo13(
+  const captionAppearance = useMemo15(
     () => resolvePanoVideoCaptionAppearance(
       typeof captions === "object" ? captions : void 0
     ),
     [captions]
   );
-  const [variantId, setVariantId] = useState9(
+  const [variantId, setVariantId] = useState10(
     () => resolvePanoVideoVariantId(variants, defaultVariantId)
   );
-  const [trackId, setTrackId] = useState9(
+  const [trackId, setTrackId] = useState10(
     () => captionsEnabled ? defaultPanoVideoTrackId(tracks) : null
   );
-  const [ready, setReady] = useState9(false);
-  const autoPlayRef = useRef21(autoPlay);
+  const [ready, setReady] = useState10(false);
+  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: {
@@ -9571,7 +9874,7 @@ function PanoVideo({
       listeners: /* @__PURE__ */ new Set()
     };
   }
-  const actionsRef = useRef21({
+  const actionsRef = useRef22({
     play: async () => {
     },
     pause: () => {
@@ -9591,19 +9894,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 = useMemo13(() => {
+  const resource = useMemo15(() => {
     if (typeof document === "undefined") {
       return null;
     }
@@ -9716,7 +10019,7 @@ function PanoVideo({
       captionAppearance
     ]
   );
-  const controller = useMemo13(
+  const controller = useMemo15(
     () => ({
       subscribe: (onStoreChange) => {
         const store = storeRef.current;
@@ -10083,9 +10386,9 @@ import {
   useCallback as useCallback10,
   useContext as useContext22,
   useEffect as useEffect26,
-  useMemo as useMemo18,
-  useRef as useRef25,
-  useState as useState11
+  useMemo as useMemo20,
+  useRef as useRef26,
+  useState as useState12
 } from "react";
 import {
   LinearSRGBColorSpace,
@@ -10141,7 +10444,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 useMemo14, useRef as useRef22 } from "react";
+import { useEffect as useEffect22, useMemo as useMemo16, useRef as useRef23 } from "react";
 import {
   DoubleSide as DoubleSide2,
   InstancedBufferAttribute,
@@ -10281,12 +10584,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 = useMemo14(() => createParticleGeometry(), []);
-  const material = useMemo14(
+  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,
@@ -10340,7 +10643,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 useMemo15, 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
@@ -10629,11 +10932,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 = useMemo15(() => {
+  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;
     }
@@ -10723,10 +11026,10 @@ function TransitionOverlay(props) {
 // src/tile/texture-manager-context.tsx
 import { useThree as useThree17 } from "@react-three/fiber";
 import {
-  createContext as createContext11,
+  createContext as createContext13,
   useContext as useContext21,
   useEffect as useEffect24,
-  useMemo as useMemo16
+  useMemo as useMemo18
 } from "react";
 
 // src/tile/texture-manager.ts
@@ -10957,7 +11260,7 @@ var TileTextureManager = class {
 
 // src/tile/texture-manager-context.tsx
 import { jsx as jsx20 } from "react/jsx-runtime";
-var TileTextureManagerContext = createContext11(
+var TileTextureManagerContext = createContext13(
   null
 );
 function TileTextureManagerProvider({
@@ -10967,7 +11270,7 @@ function TileTextureManagerProvider({
 }) {
   const gl = useThree17((state) => state.gl);
   const anisotropy = gl.capabilities.getMaxAnisotropy();
-  const manager = useMemo16(
+  const manager = useMemo18(
     () => new TileTextureManager({
       anisotropy,
       maxBytes: Math.max(1, maxTextureMemoryMb) * 1024 * 1024,
@@ -10991,9 +11294,9 @@ import { useFrame as useFrame11, useThree as useThree18 } from "@react-three/fib
 import {
   memo,
   useEffect as useEffect25,
-  useMemo as useMemo17,
-  useRef as useRef24,
-  useState as useState10
+  useMemo as useMemo19,
+  useRef as useRef25,
+  useState as useState11
 } from "react";
 import {
   ClampToEdgeWrapping as ClampToEdgeWrapping2,
@@ -11198,8 +11501,8 @@ var VISIBILITY_FOV_PADDING_DEGREES = 8;
 var PREVIEW_RADIUS = CUBE_RADIUS + 0.05;
 var SHARED_TILE_GEOMETRY = new PlaneGeometry4(1, 1);
 function usePreviewTexture(url, anisotropy, onError) {
-  const [texture, setTexture] = useState10(null);
-  const onErrorRef = useRef24(onError);
+  const [texture, setTexture] = useState11(null);
+  const onErrorRef = useRef25(onError);
   onErrorRef.current = onError;
   useEffect25(() => {
     if (!url) {
@@ -11251,7 +11554,7 @@ function PreviewFace({
   texture,
   faceOrder
 }) {
-  const geometry = useMemo17(() => {
+  const geometry = useMemo19(() => {
     const nextGeometry = new PlaneGeometry4(
       PREVIEW_RADIUS * 2,
       PREVIEW_RADIUS * 2
@@ -11310,7 +11613,7 @@ function PreviewCube({
   ));
 }
 function useManagedTexture(manager, key, url, address) {
-  const [managedState, setManagedState] = useState10(() => ({
+  const [managedState, setManagedState] = useState11(() => ({
     manager,
     key,
     url,
@@ -11537,10 +11840,10 @@ function Tile({
   onLevelChange
 }) {
   const { camera, gl, size } = useThree18();
-  const multiresConfig = useMemo17(() => parseMultires(multires), [multires]);
+  const multiresConfig = useMemo19(() => parseMultires(multires), [multires]);
   const { levels, tileSize } = multiresConfig;
   const multiresToken = `${tileSize}:${levels.join(",")}`;
-  const candidatesByLevel = useMemo17(
+  const candidatesByLevel = useMemo19(
     () => buildTileCandidates(levels, tileSize),
     [levels, tileSize]
   );
@@ -11552,13 +11855,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 = useMemo17(
+  const ownedManager = useMemo19(
     () => new TileTextureManager({
       anisotropy,
       maxBytes: Math.max(1, maxTextureMemoryMb) * 1024 * 1024,
@@ -11589,7 +11892,7 @@ function Tile({
       queueMicrotask(() => manager.releaseUnused());
     };
   }, [manager, ownedManager]);
-  const readyRef = useRef24(false);
+  const readyRef = useRef25(false);
   useEffect25(() => {
     readyRef.current = false;
   }, [effectivePreviewUrl]);
@@ -11601,24 +11904,24 @@ function Tile({
     onReady?.();
   }, [onReady, previewTexture]);
   const template = urlTemplate ?? buildDefaultTileUrlTemplate();
-  const resolveUrl = useMemo17(
+  const resolveUrl = useMemo19(
     () => (address) => {
       const relativePath = resolveTileUrl ? resolveTileUrl(address) : resolveTemplateUrl(template, address);
       return resolveRelativeTileUrl(baseUrl, relativePath);
     },
     [baseUrl, resolveTileUrl, template]
   );
-  const [layers, setLayers] = useState10([]);
-  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 [layers, setLayers] = useState11([]);
+  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 = "";
@@ -11776,8 +12079,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();
@@ -11831,40 +12134,44 @@ function ScenesController({
   renderHotspots,
   onTransitionEnd,
   onTransitionError,
-  snapshotMaxPixels = 3686400
+  snapshotMaxPixels = 3686400,
+  phaseRef: externalPhaseRef
 }) {
   const controlsRef = useContext22(PanoramaViewContext);
   const manager = useSharedTileTextureManager();
-  const transition = useMemo18(
+  const transition = useMemo20(
     () => resolveTransition(transitionInput),
     [transitionInput]
   );
-  const sceneMap = useMemo18(
+  const sceneMap = useMemo20(
     () => new Map(scenes.map((scene) => [scene.id, scene])),
     [scenes]
   );
   const initialScene = sceneMap.get(activeSceneId) ?? null;
-  const [slots, setSlots] = useState11([
+  const [slots, setSlots] = useState12([
     initialScene,
     null
   ]);
-  const [activeSlot, setActiveSlot] = useState11(0);
-  const [liveSlot, setLiveSlot] = useState11(0);
-  const [pendingSlot, setPendingSlot] = useState11(null);
-  const [phase, setPhase] = useState11(initialScene ? "idle" : "preloading");
-  const [captureRequestId, setCaptureRequestId] = useState11(0);
-  const [transitionRunId, setTransitionRunId] = useState11(0);
-  const [snapshot, setSnapshot] = useState11(null);
-  const [recoveryKey, setRecoveryKey] = useState11(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 [activeSlot, setActiveSlot] = useState12(0);
+  const [liveSlot, setLiveSlot] = useState12(0);
+  const [pendingSlot, setPendingSlot] = useState12(null);
+  const [phase, setPhase] = useState12(initialScene ? "idle" : "preloading");
+  const [captureRequestId, setCaptureRequestId] = useState12(0);
+  const [transitionRunId, setTransitionRunId] = useState12(0);
+  const [snapshot, setSnapshot] = useState12(null);
+  const [recoveryKey, setRecoveryKey] = useState12(0);
+  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) {
+    externalPhaseRef.current = phase;
+  }
   liveSlotRef.current = liveSlot;
   const releaseInteraction = useCallback10(() => {
     interactionReleaseRef.current?.();
@@ -12060,21 +12367,104 @@ function ScenesController({
 function Scenes({
   maxTextureMemoryMb,
   maxConcurrentTileLoads,
-  ...props
+  activeSceneId: controlledId,
+  defaultActiveSceneId,
+  onActiveSceneIdChange,
+  scenes,
+  ...rest
 }) {
+  const isControlled = controlledId !== void 0;
+  const [internalId, setInternalId] = useState12(
+    () => controlledId ?? defaultActiveSceneId ?? scenes[0]?.id ?? ""
+  );
+  const resolvedId = isControlled ? controlledId : internalId;
+  const requestSceneChange = useCallback10(
+    (id) => {
+      if (isControlled) {
+        onActiveSceneIdChange?.(id);
+      } else {
+        setInternalId(id);
+      }
+    },
+    [isControlled, onActiveSceneIdChange]
+  );
+  const scenesRef = useRef26(scenes);
+  scenesRef.current = scenes;
+  const resolvedIdRef = useRef26(resolvedId);
+  resolvedIdRef.current = resolvedId;
+  const host = useContext22(ScenesHostContext);
+  const phaseRef = useRef26("idle");
+  useEffect26(() => {
+    if (!host) {
+      return;
+    }
+    const controller = {
+      setScene: (id) => {
+        const match = scenesRef.current.find((s) => s.id === id);
+        if (!match) {
+          return false;
+        }
+        requestSceneChange(id);
+        return true;
+      },
+      nextScene: () => {
+        const next = cycleSceneId(
+          scenesRef.current,
+          resolvedIdRef.current,
+          1
+        );
+        if (next === null) {
+          return false;
+        }
+        requestSceneChange(next);
+        return true;
+      },
+      previousScene: () => {
+        const next = cycleSceneId(
+          scenesRef.current,
+          resolvedIdRef.current,
+          -1
+        );
+        if (next === null) {
+          return false;
+        }
+        requestSceneChange(next);
+        return true;
+      },
+      getActiveSceneId: () => resolvedIdRef.current,
+      getSceneIds: () => scenesRef.current.map((s) => s.id),
+      isTransitioning: () => phaseRef.current !== "idle"
+    };
+    host.controller = controller;
+    notifyScenesHost(host);
+    return () => {
+      if (host.controller === controller) {
+        host.controller = null;
+        notifyScenesHost(host);
+      }
+    };
+  }, [host, requestSceneChange]);
   return /* @__PURE__ */ jsx22(
     TileTextureManagerProvider,
     {
       maxTextureMemoryMb,
       maxConcurrentLoads: maxConcurrentTileLoads,
-      children: /* @__PURE__ */ jsx22(ScenesController, { ...props })
+      children: /* @__PURE__ */ jsx22(
+        ScenesController,
+        {
+          ...rest,
+          scenes,
+          activeSceneId: resolvedId,
+          phaseRef
+        }
+      )
     }
   );
 }
 
 // src/hotspot/image-hotspot.tsx
 import { useThree as useThree21 } from "@react-three/fiber";
-import { useEffect as useEffect29, useRef as useRef27, useState as useState14 } from "react";
+import { useEffect as useEffect29, useRef as useRef28, useState as useState15 } from "react";
 import {
   ClampToEdgeWrapping as ClampToEdgeWrapping3,
   LinearFilter as LinearFilter6,
@@ -12089,9 +12479,9 @@ import {
   useContext as useContext24,
   useEffect as useEffect28,
   useLayoutEffect as useLayoutEffect4,
-  useMemo as useMemo20,
-  useRef as useRef26,
-  useState as useState13
+  useMemo as useMemo22,
+  useRef as useRef27,
+  useState as useState14
 } from "react";
 import {
   Box3 as Box33,
@@ -12107,7 +12497,7 @@ import {
 } from "three";
 
 // src/hotspot/hotspot-tooltip.tsx
-import { useEffect as useEffect27, useMemo as useMemo19, useState as useState12 } 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";
@@ -12230,16 +12620,16 @@ function HotspotTooltip({
   offset = DEFAULT_HOTSPOT_TOOLTIP_OFFSET,
   appearance
 }) {
-  const [imageFailed, setImageFailed] = useState12(false);
+  const [imageFailed, setImageFailed] = useState13(false);
   useEffect27(() => {
     setImageFailed(false);
   }, [content.image]);
   const showImage = Boolean(content.image) && !imageFailed;
-  const resolvedAppearance = useMemo19(
+  const resolvedAppearance = useMemo21(
     () => resolveHotspotTooltipAppearance(appearance),
     [appearance]
   );
-  const bubbleStyle = useMemo19(
+  const bubbleStyle = useMemo21(
     () => ({
       background: resolvedAppearance.background,
       border: resolvedAppearance.border,
@@ -12622,14 +13012,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 [hovered, setHovered] = useState13(false);
-  const [dragging, setDragging] = useState13(false);
-  const [pinned, setPinned] = useState13(false);
-  const tooltipContent = useMemo20(
+  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 = useMemo22(
     () => resolveHotspotTooltipContent(tooltip),
     [tooltip]
   );
@@ -12645,17 +13035,17 @@ function HotspotAnchor({
     scaledWidth,
     scaledHeight
   );
-  const worldPosition = useMemo20(
+  const worldPosition = useMemo22(
     () => panoPositionToVector3(normalizedPosition, resolvedDistance),
     [normalizedPosition.pitch, normalizedPosition.yaw, resolvedDistance]
   );
-  const surfaceQuaternion3 = useMemo20(
+  const surfaceQuaternion3 = useMemo22(
     () => createSurfaceQuaternion(normalizedPosition),
     [normalizedPosition.pitch, normalizedPosition.yaw]
   );
   const worldWidth = angularSizeToWorldSize(scaledWidth, resolvedDistance);
   const worldHeight = angularSizeToWorldSize(scaledHeight, resolvedDistance);
-  const focusGeometry = useMemo20(() => {
+  const focusGeometry = useMemo22(() => {
     const planeGeometry = new PlaneGeometry5(1, 1);
     const geometry = new EdgesGeometry(planeGeometry);
     planeGeometry.dispose();
@@ -13076,9 +13466,9 @@ function HotspotPlane({
 import { jsx as jsx27 } from "react/jsx-runtime";
 function useHotspotImageTexture(src, onLoad, onError) {
   const gl = useThree21((state) => state.gl);
-  const [texture, setTexture] = useState14(null);
-  const onLoadRef = useRef27(onLoad);
-  const onErrorRef = useRef27(onError);
+  const [texture, setTexture] = useState15(null);
+  const onLoadRef = useRef28(onLoad);
+  const onErrorRef = useRef28(onError);
   onLoadRef.current = onLoad;
   onErrorRef.current = onError;
   useEffect29(() => {
@@ -13141,7 +13531,7 @@ function ImageHotspot({
 }
 
 // src/hotspot/polygon-hotspot.tsx
-import { useEffect as useEffect30, useMemo as useMemo21, useRef as useRef29 } from "react";
+import { useEffect as useEffect30, useMemo as useMemo23, useRef as useRef30 } from "react";
 import {
   BufferGeometry,
   DoubleSide as DoubleSide5,
@@ -13156,7 +13546,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,
@@ -13193,7 +13583,7 @@ function HotspotStrokeLine({
   dashSize,
   gapSize
 }) {
-  const lineRef = useRef28(null);
+  const lineRef = useRef29(null);
   const { camera, size } = useThree22();
   const dash = resolveDash(dashSize, gapSize);
   useLayoutEffect5(() => {
@@ -13486,19 +13876,19 @@ function PolygonHotspot({
   onInvalid,
   ...anchorProps
 }) {
-  const issues = useMemo21(() => validatePolygonVertices(vertices), [vertices]);
+  const issues = useMemo23(() => validatePolygonVertices(vertices), [vertices]);
   const valid = issues.length === 0;
-  const center = useMemo21(() => valid ? polygonCenter(vertices) : null, [valid, vertices]);
-  const fillGeometry = useMemo21(
+  const center = useMemo23(() => valid ? polygonCenter(vertices) : null, [valid, vertices]);
+  const fillGeometry = useMemo23(
     () => valid && center ? makeFillGeometry(vertices, center) : null,
     [center, valid, vertices]
   );
-  const strokePoints = useMemo21(
+  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);
@@ -13583,7 +13973,7 @@ function PolygonHotspot({
 }
 
 // src/hotspot/polyline-hotspot.tsx
-import { useEffect as useEffect31, useMemo as useMemo22, useRef as useRef30 } from "react";
+import { useEffect as useEffect31, useMemo as useMemo24, useRef as useRef31 } from "react";
 import {
   MathUtils as MathUtils9,
   Matrix4 as Matrix44,
@@ -13707,15 +14097,15 @@ function PolylineHotspot({
   onInvalid,
   ...anchorProps
 }) {
-  const issues = useMemo22(() => validatePolylineVertices(vertices), [vertices]);
+  const issues = useMemo24(() => validatePolylineVertices(vertices), [vertices]);
   const valid = issues.length === 0;
-  const center = useMemo22(() => valid ? polylineCenter(vertices) : null, [valid, vertices]);
-  const linePoints = useMemo22(
+  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]);
@@ -13782,7 +14172,7 @@ function PolylineHotspot({
 }
 
 // src/hotspot/graphic-hotspot.tsx
-import { useEffect as useEffect32, useRef as useRef31, useState as useState15 } from "react";
+import { useEffect as useEffect32, useRef as useRef32, useState as useState16 } from "react";
 import {
   CanvasTexture,
   ClampToEdgeWrapping as ClampToEdgeWrapping4,
@@ -13979,9 +14369,9 @@ function createGraphicTexture(graphic, aspectWidth, aspectHeight) {
   return texture;
 }
 function useGraphicTexture(graphic, aspectWidth, aspectHeight, onLoad, onError) {
-  const [texture, setTexture] = useState15(null);
-  const onLoadRef = useRef31(onLoad);
-  const onErrorRef = useRef31(onError);
+  const [texture, setTexture] = useState16(null);
+  const onLoadRef = useRef32(onLoad);
+  const onErrorRef = useRef32(onError);
   onLoadRef.current = onLoad;
   onErrorRef.current = onError;
   useEffect32(() => {
@@ -14023,7 +14413,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 useState16 } from "react";
+import { useEffect as useEffect33, useRef as useRef33, useState as useState17 } from "react";
 import {
   ClampToEdgeWrapping as ClampToEdgeWrapping5,
   LinearFilter as LinearFilter8,
@@ -14046,9 +14436,9 @@ function useSpriteTexture({
   onLoadProgress
 }) {
   const gl = useThree23((state) => state.gl);
-  const [texture, setTexture] = useState16(null);
-  const onErrorRef = useRef32(onError);
-  const onLoadProgressRef = useRef32(onLoadProgress);
+  const [texture, setTexture] = useState17(null);
+  const onErrorRef = useRef33(onError);
+  const onLoadProgressRef = useRef33(onLoadProgress);
   onErrorRef.current = onError;
   onLoadProgressRef.current = onLoadProgress;
   useEffect33(() => {
@@ -14121,14 +14511,14 @@ function SequenceHotspot({
   const texture = useSpriteTexture({ id, src, onError, onLoadProgress });
   const frameCount = resolveFrameCount(requestedFrameCount);
   const safeFps = resolveFps(fps);
-  const [frameIndex, setFrameIndex] = useState16(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 [frameIndex, setFrameIndex] = useState17(0);
+  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;
@@ -14212,7 +14602,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 useState17 } from "react";
+import { useEffect as useEffect34, useRef as useRef34, useState as useState18 } from "react";
 import {
   ClampToEdgeWrapping as ClampToEdgeWrapping6,
   LinearFilter as LinearFilter9,
@@ -14230,8 +14620,8 @@ function clampVolume2(volume) {
 }
 function usePosterTexture2(id, poster, onError) {
   const gl = useThree24((state) => state.gl);
-  const [texture, setTexture] = useState17(null);
-  const onErrorRef = useRef33(onError);
+  const [texture, setTexture] = useState18(null);
+  const onErrorRef = useRef34(onError);
   onErrorRef.current = onError;
   useEffect34(() => {
     let active = true;
@@ -14288,10 +14678,10 @@ function useVideoResource({
   poster,
   src
 }) {
-  const [resource, setResource] = useState17(null);
-  const onEndedRef = useRef33(onEnded);
-  const onErrorRef = useRef33(onError);
-  const onPlaybackStateChangeRef = useRef33(onPlaybackStateChange);
+  const [resource, setResource] = useState18(null);
+  const onEndedRef = useRef34(onEnded);
+  const onErrorRef = useRef34(onError);
+  const onPlaybackStateChangeRef = useRef34(onPlaybackStateChange);
   onEndedRef.current = onEnded;
   onErrorRef.current = onError;
   onPlaybackStateChangeRef.current = onPlaybackStateChange;
@@ -14396,8 +14786,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(() => {
@@ -14438,7 +14828,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 useState18 } from "react";
+import { useEffect as useEffect35, useRef as useRef35, useState as useState19 } from "react";
 import {
   CanvasTexture as CanvasTexture2,
   ClampToEdgeWrapping as ClampToEdgeWrapping7,
@@ -14511,7 +14901,7 @@ function createSpeakerTexture(state) {
   return texture;
 }
 function useSpeakerTextures(enabled) {
-  const [textures, setTextures] = useState18({ playing: null, stopped: null });
+  const [textures, setTextures] = useState19({ playing: null, stopped: null });
   useEffect35(() => {
     if (!enabled) {
       setTextures({ playing: null, stopped: null });
@@ -14529,8 +14919,8 @@ function useSpeakerTextures(enabled) {
 }
 function useIconTexture(icon, enabled, onError, id) {
   const gl = useThree25((state) => state.gl);
-  const [texture, setTexture] = useState18(null);
-  const onErrorRef = useRef34(onError);
+  const [texture, setTexture] = useState19(null);
+  const onErrorRef = useRef35(onError);
   onErrorRef.current = onError;
   useEffect35(() => {
     let active = true;
@@ -14588,13 +14978,13 @@ function useAudioHowl({
   playing,
   src
 }) {
-  const [howl, setHowl] = useState18(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 [howl, setHowl] = useState19(null);
+  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;
@@ -14682,11 +15072,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;
@@ -14735,7 +15125,7 @@ function AudioHotspot({
 }
 
 // src/hotspot/text-hotspot.tsx
-import { useEffect as useEffect36, useRef as useRef35, useState as useState19 } from "react";
+import { useEffect as useEffect36, useRef as useRef36, useState as useState20 } from "react";
 import {
   CanvasTexture as CanvasTexture3,
   ClampToEdgeWrapping as ClampToEdgeWrapping8,
@@ -14963,9 +15353,9 @@ function createTextTexture(text, width, height, style) {
   return texture;
 }
 function useTextTexture(text, width, height, style, onLoad, onError) {
-  const [texture, setTexture] = useState19(null);
-  const onLoadRef = useRef35(onLoad);
-  const onErrorRef = useRef35(onError);
+  const [texture, setTexture] = useState20(null);
+  const onLoadRef = useRef36(onLoad);
+  const onErrorRef = useRef36(onError);
   onLoadRef.current = onLoad;
   onErrorRef.current = onError;
   useEffect36(() => {
@@ -15231,6 +15621,7 @@ export {
   resolvePanoContextMenuEntries,
   unwrapPolygonVertices,
   usePanoEvents,
+  usePanoViewer,
   validatePolygonVertices,
   validatePolylineVertices,
   vector3ToPanoPosition