@ericchen1990/pano-view 4.0.1 → 5.0.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { CSSProperties, ReactNode, ComponentPropsWithoutRef, IframeHTMLAttributes, RefObject } from 'react';
+import { CSSProperties, ReactNode, Ref, RefObject, ComponentPropsWithoutRef, IframeHTMLAttributes, ComponentProps } from 'react';
 import { Texture, ColorRepresentation, Vector3 } from 'three';
 
 /** Camera-center limits in degrees. A yaw min greater than max crosses ±180°. */
@@ -34,6 +34,7 @@ type HotspotPosition = {
 type HotspotMode = "surface" | "billboard";
 /** Whether a hotspot grows with panorama zoom or preserves its screen size. */
 type HotspotScaleMode = "fov" | "fixed";
+type HotspotTooltipScaleMode = "inherit" | HotspotScaleMode;
 type HotspotInputSource = "pointer" | "keyboard";
 type HotspotInteractionEvent = {
     id: string;
@@ -87,6 +88,10 @@ type HotspotCommonProps = {
     tooltipTrigger?: HotspotTooltipTrigger;
     /** Screen direction for the tooltip. Defaults to `"top"`. */
     tooltipPlacement?: HotspotTooltipPlacement;
+    /** Defaults to billboard, independently of the hotspot orientation. */
+    tooltipMode?: HotspotMode;
+    /** Defaults to inherit. Surface tooltips always scale with FOV. */
+    tooltipScaleMode?: HotspotTooltipScaleMode;
     /**
      * Screen-space gap in CSS pixels between the hotspot edge and the tooltip.
      * Defaults to 12.
@@ -107,9 +112,9 @@ type HotspotCommonProps = {
      * when needed so the full hotspot remains inside the panorama shell.
      */
     distance?: number;
-    /** FOV grows/shrinks with zoom; fixed preserves the reference screen size. */
+    /** Billboard defaults to fixed. Surface always uses fov, ignoring fixed. */
     scaleMode?: HotspotScaleMode;
-    /** Reference FOV in degrees used when scaleMode is "fixed". Defaults to 75. */
+    /** Reference FOV for fixed hotspot size and tooltip styling. Defaults to 75. */
     referenceFov?: number;
     /** Clockwise rotation around the hotspot normal in degrees. */
     rotation?: number;
@@ -234,117 +239,11 @@ declare function cycleSceneId(scenes: readonly {
  */
 declare function KeyboardControls({ enabled, keys, rotateSpeed, zoomSpeed, shiftMultiplier, invert, fovSpeed, onPreviousScene, onNextScene, }: KeyboardControlsProps): null;
 
-type VideoPlaybackState = "playing" | "paused" | "ended" | "blocked";
-type VideoHotspotErrorEvent = {
-    id: string;
-    source: "poster" | "video";
-    error: unknown;
-};
-type VideoHotspotProps = HotspotCommonProps & {
-    src: string;
-    playing: boolean;
-    poster?: string;
-    loop?: boolean;
-    muted?: boolean;
-    volume?: number;
-    /**
-     * Keep playback in the page. Defaults to true, including the WebKit and
-     * X5 attributes for iPhone Safari, WeChat, QQ, and UC.
-     */
-    playsInline?: boolean;
-    preload?: "none" | "metadata" | "auto";
-    crossOrigin?: "" | "anonymous" | "use-credentials";
-    onPlaybackStateChange?: (state: VideoPlaybackState) => void;
-    onPlaybackError?: (error: unknown) => void;
-    onEnded?: () => void;
-    onError?: (event: VideoHotspotErrorEvent) => void;
-};
-declare function VideoHotspot({ id, src, playing, poster, loop, muted, volume, playsInline, preload, crossOrigin, width, height, opacity, onPlaybackStateChange, onPlaybackError, onEnded, onError, ...anchorProps }: VideoHotspotProps): react.JSX.Element;
-
-type PanoVideoSource = {
-    src: string;
-    type?: string;
-};
-type PanoVideoVariant = {
-    id: string;
-    label: string;
-    poster?: string;
-    sources: readonly PanoVideoSource[];
-};
-type PanoVideoTrackKind = "subtitles" | "captions";
-type PanoVideoTrack = {
-    /** Defaults to `srcLang`. */
-    id?: string;
-    src: string;
-    srcLang: string;
-    label: string;
-    kind?: PanoVideoTrackKind;
-    default?: boolean;
-};
-type PanoVideoCaptionAppearance = {
-    color?: string;
-    background?: string;
-    fontSize?: number | string;
-    fontFamily?: string;
-    fontWeight?: CSSProperties["fontWeight"];
-    textShadow?: string;
-    padding?: string;
-    borderRadius?: number | string;
-    maxWidth?: number | string;
-    bottom?: number | string;
-    lineHeight?: number | string;
-};
-type PanoVideoControlsAppearance = {
-    background?: string;
-    color?: string;
-    accent?: string;
-    borderRadius?: number | string;
-    fontSize?: number | string;
-    padding?: string;
-};
-type PanoVideoErrorSource = "poster" | "video" | "track";
-type PanoVideoErrorEvent = {
-    source: PanoVideoErrorSource;
-    error: unknown;
-};
-type PanoVideoPlaybackSnapshot = {
-    ready: boolean;
-    playing: boolean;
-    blocked: boolean;
-    ended: boolean;
-    currentTime: number;
-    duration: number;
-    volume: number;
-    /** False when the element ignores `volume` (iOS Safari). Mute still works. */
-    volumeAdjustable: boolean;
-    muted: boolean;
-    playbackRate: number;
-    variantId: string;
-    variants: readonly PanoVideoVariant[];
-    trackId: string | null;
-    tracks: readonly PanoVideoTrack[];
-    captionText: string;
-    captionAppearance: Required<PanoVideoCaptionAppearance>;
-    captionsEnabled: boolean;
-    playbackRates: readonly number[];
-    playbackState: VideoPlaybackState;
-};
-type PanoVideoController = {
-    subscribe: (onStoreChange: () => void) => () => void;
-    getSnapshot: () => PanoVideoPlaybackSnapshot;
-    play: () => Promise<void>;
-    pause: () => void;
-    togglePlay: () => void;
-    seek: (time: number) => void;
-    setVolume: (volume: number) => void;
-    setMuted: (muted: boolean) => void;
-    toggleMuted: () => void;
-    setPlaybackRate: (rate: number) => void;
-    setVariantId: (id: string) => void;
-    setTrackId: (id: string | null) => void;
-    setCaptionAppearance: (appearance: Partial<PanoVideoCaptionAppearance>) => void;
-};
-
+type WebVRInteractionMode = "auto" | "gaze" | "pointer";
+type WebVRInputState = Readonly<{
+    mode: "gaze" | "pointer" | "paused" | null;
+    source: "head" | "controller" | "hand" | "system" | null;
+}>;
 type WebVRMode = "webxr" | "mobilevr" | "fake";
 type WebVRProfileId = "none" | "cardboard-v1" | "cardboard-v2" | "gear-vr" | "daydream";
 type WebVRProfile = {
@@ -377,11 +276,14 @@ type WebVRChromeAppearance = {
 };
 type WebVRChrome = boolean | WebVRChromeAppearance;
 type WebVRState = {
+    input?: WebVRInputState;
     available: boolean;
     enabled: boolean;
     mode: WebVRMode | null;
 };
 type WebVRProps = {
+    /** Input policy; auto uses explicit selection in WebXR and dwell in fallback VR. */
+    interactionMode?: WebVRInteractionMode;
     /**
      * Mount the built-in session chrome (Exit VR / MobileVR Setup). Defaults to
      * true. Enter VR is not rendered; host apps drive entry through the handle
@@ -451,7 +353,8 @@ type WebVRProps = {
     wakelock?: boolean;
     /**
      * Lock the mouse in simulated desktop VR so movement looks around with
-     * no visible cursor. Click the view to re-lock after Escape. Defaults to true.
+     * no visible cursor. Right-click to release; left-click the view to re-lock.
+     * While unlocked, the reticle and gaze actions are paused. Defaults to true.
      */
     mousePointerLock?: boolean;
     onAvailable?: () => void;
@@ -471,7 +374,7 @@ type WebVRHandle = {
     getState: () => WebVRState;
     subscribe: (onStoreChange: () => void) => () => void;
     requestPermission: () => Promise<boolean>;
-    /** Clear stored MobileVR settings and restore prop / built-in defaults. */
+    /** Reset the active fallback mode, or both modes outside VR; explicit props still apply. */
     resetSettings: () => void;
 };
 type WebVRSettings = {
@@ -479,6 +382,147 @@ type WebVRSettings = {
     profileId: WebVRProfileId;
 };
 
+type PanoSpatialControlAdapter = {
+    /** Degrees. Update the existing model viewing controls, not the panorama camera. */
+    rotateBy?: (yaw: number, pitch: number) => void;
+    /** Multiplicative viewing scale; values above one zoom in. */
+    zoomBy?: (factor: number) => void;
+    resetView?: () => void;
+    canExecute?: (action: string) => boolean;
+    /** Canvas frames must be copied after the host renderer finishes rendering. */
+    subscribeFrame?: (invalidate: () => void) => () => void;
+    /** A texture must belong to this viewer's WebGL context. */
+    texture?: Texture;
+};
+
+type PanoMediaController = Pick<PanoVideoController, "subscribe" | "play" | "pause" | "seek" | "setVolume" | "setMuted"> & {
+    getSnapshot: () => Pick<PanoVideoPlaybackSnapshot, "ready" | "playing" | "currentTime" | "duration" | "volume" | "volumeAdjustable" | "muted">;
+};
+type PanoControlAction = {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    disabled?: boolean;
+    enabled?: () => boolean;
+    activate?: () => void;
+    update?: (seconds: number) => void;
+    repeatIntervalMs?: number;
+    end?: () => void;
+};
+
+type VideoPlaybackState = "playing" | "paused" | "ended" | "blocked";
+type VideoHotspotErrorEvent = {
+    id: string;
+    source: "poster" | "video";
+    error: unknown;
+};
+type VideoHotspotProps = HotspotCommonProps & {
+    ref?: Ref<PanoMediaController>;
+    src: string;
+    playing: boolean;
+    poster?: string;
+    loop?: boolean;
+    /** Defaults to false so manually started playback includes audio. */
+    muted?: boolean;
+    volume?: number;
+    /**
+     * Keep playback in the page. Defaults to true, including the WebKit and
+     * X5 attributes for iPhone Safari, WeChat, QQ, and UC.
+     */
+    playsInline?: boolean;
+    preload?: "none" | "metadata" | "auto";
+    crossOrigin?: "" | "anonymous" | "use-credentials";
+    onPlaybackStateChange?: (state: VideoPlaybackState) => void;
+    onPlaybackError?: (error: unknown) => void;
+    onEnded?: () => void;
+    onError?: (event: VideoHotspotErrorEvent) => void;
+};
+declare function VideoHotspot({ ref, id, src, playing, poster, loop, muted, volume, playsInline, preload, crossOrigin, width, height, opacity, onPlaybackStateChange, onPlaybackError, onEnded, onError, ...anchorProps }: VideoHotspotProps): react.JSX.Element;
+
+type PanoVideoSource = {
+    src: string;
+    type?: string;
+};
+type PanoVideoVariant = {
+    id: string;
+    label: string;
+    poster?: string;
+    sources: readonly PanoVideoSource[];
+};
+type PanoVideoTrackKind = "subtitles" | "captions";
+type PanoVideoTrack = {
+    /** Defaults to `srcLang`. */
+    id?: string;
+    src: string;
+    srcLang: string;
+    label: string;
+    kind?: PanoVideoTrackKind;
+    default?: boolean;
+};
+type PanoVideoCaptionAppearance = {
+    color?: string;
+    background?: string;
+    fontSize?: number | string;
+    fontFamily?: string;
+    fontWeight?: CSSProperties["fontWeight"];
+    textShadow?: string;
+    padding?: string;
+    borderRadius?: number | string;
+    maxWidth?: number | string;
+    bottom?: number | string;
+    lineHeight?: number | string;
+};
+type PanoVideoControlsAppearance = {
+    background?: string;
+    color?: string;
+    accent?: string;
+    borderRadius?: number | string;
+    fontSize?: number | string;
+    padding?: string;
+};
+type PanoVideoErrorSource = "poster" | "video" | "track";
+type PanoVideoErrorEvent = {
+    source: PanoVideoErrorSource;
+    error: unknown;
+};
+type PanoVideoPlaybackSnapshot = {
+    ready: boolean;
+    playing: boolean;
+    blocked: boolean;
+    ended: boolean;
+    currentTime: number;
+    duration: number;
+    volume: number;
+    /** False when the element ignores `volume` (iOS Safari). Mute still works. */
+    volumeAdjustable: boolean;
+    muted: boolean;
+    playbackRate: number;
+    variantId: string;
+    variants: readonly PanoVideoVariant[];
+    trackId: string | null;
+    tracks: readonly PanoVideoTrack[];
+    captionText: string;
+    captionAppearance: Required<PanoVideoCaptionAppearance>;
+    captionsEnabled: boolean;
+    playbackRates: readonly number[];
+    playbackState: VideoPlaybackState;
+};
+type PanoVideoController = {
+    subscribe: (onStoreChange: () => void) => () => void;
+    getSnapshot: () => PanoVideoPlaybackSnapshot;
+    play: () => Promise<void>;
+    pause: () => void;
+    togglePlay: () => void;
+    seek: (time: number) => void;
+    setVolume: (volume: number) => void;
+    setMuted: (muted: boolean) => void;
+    toggleMuted: () => void;
+    setPlaybackRate: (rate: number) => void;
+    setVariantId: (id: string) => void;
+    setTrackId: (id: string | null) => void;
+    setCaptionAppearance: (appearance: Partial<PanoVideoCaptionAppearance>) => void;
+};
+
 type PanoViewerState = {
     /** Horizontal look angle in degrees. Positive values look right. */
     yaw: number;
@@ -837,7 +881,9 @@ type PanoOverlayProps = {
 /**
  * Screen-plane DOM UI for PanoViewer. Place it as a direct child of PanoViewer
  * (or inside a Fragment under PanoViewer). It stays outside the panorama sphere
- * and remains visible in fullscreen. Interactive children need `pointerEvents: "auto"`.
+ * and remains visible in fullscreen, but is hidden during VR sessions. Dialogs
+ * portaled to the viewer host can still render spatially. Interactive children
+ * need `pointerEvents: "auto"`.
  */
 declare function PanoOverlay({ children }: PanoOverlayProps): react.JSX.Element;
 /** Read inside PanoOverlay, renderOverlay, or their DOM descendants. */
@@ -849,6 +895,61 @@ declare function PanoOverlayPortalProvider({ container, children, }: {
     container: HTMLDivElement | null;
     children: ReactNode;
 }): react.JSX.Element;
+/** Shared portal/ref adapter for package and third-party dialogs. */
+declare function usePanoDialogSurface({ open, onOpenChange, scrollTargetRef, }: {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    scrollTargetRef?: RefObject<HTMLElement | null>;
+}): {
+    presentation: "screen" | "spatial";
+    contentRef: (node: HTMLElement | null) => void;
+    onInteractOutside: (event: {
+        detail: {
+            originalEvent: Event;
+        };
+        preventDefault: () => void;
+    }) => void;
+    visibleRect: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    /** Stable viewer-local portal target; null until the DOM has mounted. */
+    portalContainer: HTMLDivElement | null;
+    /** Available viewer space in CSS pixels, independent of nested portal targets. */
+    size: {
+        width: number;
+        height: number;
+    };
+    isFullscreen: boolean;
+};
+declare function usePanoSpatialControls(ref: RefObject<HTMLElement | null>, adapter: PanoSpatialControlAdapter): void;
+/** @internal Shared by ESM/CJS dialog parts; owned by the viewer runtime. */
+declare const PanoDialogSurfaceContext: react.Context<{
+    presentation: "screen" | "spatial";
+    contentRef: (node: HTMLElement | null) => void;
+    onInteractOutside: (event: {
+        detail: {
+            originalEvent: Event;
+        };
+        preventDefault: () => void;
+    }) => void;
+    visibleRect: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    /** Stable viewer-local portal target; null until the DOM has mounted. */
+    portalContainer: HTMLDivElement | null;
+    /** Available viewer space in CSS pixels, independent of nested portal targets. */
+    size: {
+        width: number;
+        height: number;
+    };
+    isFullscreen: boolean;
+} | null>;
 
 type PanoViewerProps = Omit<ComponentPropsWithoutRef<"div">, "children" | "onChange" | "contextMenu"> & {
     children?: ReactNode;
@@ -888,7 +989,7 @@ type PanoViewerProps = Omit<ComponentPropsWithoutRef<"div">, "children" | "onCha
     /** Canvas pixel ratio. Defaults to a capped range of 1–2. */
     dpr?: number | [number, number];
 };
-declare const PanoViewer: react.ForwardRefExoticComponent<Omit<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "children" | "onChange" | "contextMenu"> & {
+declare const PanoViewer: react.ForwardRefExoticComponent<Omit<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "children" | "contextMenu" | "onChange"> & {
     children?: ReactNode;
     /** Viewer-local DOM UI, rendered outside the Three.js tree, including in fullscreen. */
     renderOverlay?: (context: PanoOverlayRenderContext) => ReactNode;
@@ -1353,6 +1454,10 @@ type HotspotDefinitionBase = {
     tooltip?: string | HotspotTooltipContent;
     tooltipTrigger?: HotspotTooltipTrigger;
     tooltipPlacement?: HotspotTooltipPlacement;
+    /** Defaults to billboard, independently of the hotspot orientation. */
+    tooltipMode?: HotspotMode;
+    /** Defaults to inherit. Surface tooltips always scale with FOV. */
+    tooltipScaleMode?: HotspotTooltipScaleMode;
     tooltipOffset?: number;
     tooltipAppearance?: HotspotTooltipAppearance;
 };
@@ -1948,6 +2053,9 @@ type PanoSceneMenuAppearance = {
     gap?: number | string;
     borderRadius?: number | string;
     selectionColor?: string;
+    /** Hover and keyboard-focus border color. Defaults to `"#7dd3fc"`. */
+    focusColor?: string;
+    /** Shared active/hover/focus border width in pixels. Defaults to 2. */
     selectionWidth?: number;
     labelBackground?: string;
     labelColor?: string;
@@ -1961,6 +2069,10 @@ type PanoSceneMenuProps = {
     items: readonly PanoSceneMenuItem[];
     activeId?: string | null;
     onSelect?: (id: string) => void;
+    /** Show an icon for scenes successfully displayed by this viewer. Defaults to false. */
+    showVisited?: boolean;
+    /** Accessible description for visited scenes; never rendered as visible text. */
+    visitedLabel?: string;
     /**
      * Screen anchor. Defaults to bottom, centered on that edge, with a 12px inset.
      * Corner `axis` chooses a horizontal or vertical strip.
@@ -2004,7 +2116,7 @@ type PanoSceneMenuProps = {
     toggle?: PanoOverlayToggle;
 };
 declare const DEFAULT_PANO_SCENE_MENU_APPEARANCE: Required<PanoSceneMenuAppearance>;
-declare function PanoSceneMenu({ items, activeId, onSelect, anchor, width, height, collapsible, defaultExpanded, expanded: expandedProp, onExpandedChange, showArrows, loop, dragMotion: dragMotionProp, appearance, className, style, label, previousLabel, nextLabel, expandLabel, collapseLabel, toggle, }: PanoSceneMenuProps): react.JSX.Element;
+declare function PanoSceneMenu({ items, activeId, onSelect, showVisited, visitedLabel, anchor, width, height, collapsible, defaultExpanded, expanded: expandedProp, onExpandedChange, showArrows, loop, dragMotion: dragMotionProp, appearance, className, style, label, previousLabel, nextLabel, expandLabel, collapseLabel, toggle, }: PanoSceneMenuProps): react.JSX.Element;
 
 type ViewInteractionSource = "mouse" | "touch" | "keyboard";
 type PanoWheelEvent = {
@@ -2484,4 +2596,91 @@ declare function containerPointToImage(point: MapPoint, viewport: MapViewport):
 /** Clockwise degrees from image up for a vector in container space. */
 declare function headingFromVector(dx: number, dy: number): number;
 
-export { type ArrowGraphic, type AssetUrlContext, type AssetUrlResolver, AudioHotspot, type AudioHotspotDefinition, type AudioHotspotErrorEvent, type AudioHotspotProps, type AudioPlaybackState, AutoRotate, type AutoRotateProps, BackgroundAudio, type BackgroundAudioController, type BackgroundAudioErrorEvent, type BackgroundAudioProps, type BackgroundAudioSnapshot, type BackgroundAudioSource, type CircleGraphic, type CubeFaceCode, type CubemapViewerConfig, DEFAULT_HOTSPOT_TOOLTIP_APPEARANCE, DEFAULT_HOTSPOT_TOOLTIP_OFFSET, DEFAULT_PANO_CURSORS, DEFAULT_PANO_SCENE_MENU_APPEARANCE, DEFAULT_PANO_VIDEO_CAPTION_APPEARANCE, DEFAULT_PANO_VIDEO_CONTROLS_APPEARANCE, DEFAULT_PANO_VIDEO_PLAYBACK_RATES, DEFAULT_WEBVR_CHROME_APPEARANCE, DEFAULT_WEBVR_CURSOR_DWELL_MS, type DiamondGraphic, EMPTY_WEBVR_STATE, type GraphicDefinition, GraphicHotspot, type GraphicHotspotDefinition, type GraphicHotspotProps, Gyro, type GyroHandle, type GyroProps, type GyroTouchMode, type HotspotCommonProps, type HotspotDefinition, type HotspotDefinitionBase, type HotspotDragEvent, type HotspotInputSource, type HotspotInteractionEvent, type HotspotMode, type HotspotPointerEvents, type HotspotPosition, type HotspotScaleMode, type HotspotTooltipAppearance, type HotspotTooltipContent, type HotspotTooltipPlacement, type HotspotTooltipTrigger, IframeHotspot, type IframeHotspotDefinition, type IframeHotspotProps, type IframePointerPolicy, ImageHotspot, type ImageHotspotDefinition, type ImageHotspotProps, type JsonObject, type JsonRequestOptions, type JsonValue, type KeyboardControlAction, type KeyboardControlKeys, KeyboardControls, type KeyboardControlsProps, type LoadPanoProjectOptions, type LoadSceneFromJsonOptions, type LoadedPanoProject, type LoadedProjectScene, MAX_HOTSPOT_PITCH, MIN_PANO_CONTEXT_MENU_BACKGROUND_OPACITY, type MouseControlButton, MouseControls, type MouseControlsOptions, type MouseControlsProps, PANO_FILTER_PRESETS, PANO_OVERLAY_ALIGNS, type PanoColorMatrix, PanoContextMenu, type PanoContextMenuActionItem, type PanoContextMenuAppearance, type PanoContextMenuEntry, type PanoContextMenuItem, type PanoContextMenuPresetActions, type PanoContextMenuPresetId, type PanoContextMenuPresetRef, type PanoContextMenuPresets, type PanoContextMenuProps, type PanoContextMenuRenderProps, type PanoContextMenuSelectContext, type PanoContextMenuSeparatorItem, type PanoCursor, type PanoCursors, PanoDataError, type PanoDataErrorCode, type PanoDragMotion, type PanoEventBus, type PanoEventListener, type PanoEventMap, type PanoEventType, PanoEvents, type PanoEventsProps, PanoFilter, type PanoFilterPreset, type PanoFilterProps, PanoMap, type PanoMapControlsDefinition, type PanoMapDefinition, type PanoMapDialogPresentation, type PanoMapEditChange, type PanoMapGradientStop, PanoMapOverlay, type PanoMapOverlayProps, type PanoMapPanelPresentation, type PanoMapPresentation, type PanoMapProps, type PanoMapSectorDefinition, type PanoMapSectorGradient, type PanoMapSpotDefinition, type PanoMediaActivationControls, type PanoMediaActivationOptions, PanoOverlay, type PanoOverlayAlign, type PanoOverlayAnchor, type PanoOverlayAxis, type PanoOverlayChevron, type PanoOverlayCollapseEdge, type PanoOverlayContentAlign, type PanoOverlayInset, PanoOverlayPortalProvider, type PanoOverlayProps, type PanoOverlayRenderContext, type PanoOverlayToggle, type PanoOverlayToggleState, type PanoProjectDefinition, type PanoProjectSceneDefinition, type PanoResizeEvent, PanoSceneMenu, type PanoSceneMenuAppearance, type PanoSceneMenuItem, type PanoSceneMenuLabelAlign, type PanoSceneMenuProps, PanoVideo, type PanoVideoCaptionAppearance, type PanoVideoController, PanoVideoControls, type PanoVideoControlsAppearance, type PanoVideoControlsProps, type PanoVideoErrorEvent, type PanoVideoErrorSource, type PanoVideoPlaybackSnapshot, type PanoVideoProps, type PanoVideoSource, type PanoVideoTrack, type PanoVideoTrackKind, type PanoVideoVariant, type PanoViewEasing, type PanoViewLimits, type PanoViewLookToOptions, type PanoViewNavigationOptions, type PanoViewNavigationResult, PanoViewer, type PanoViewerHandle, type PanoViewerProps, type PanoViewerState, type PanoWheelEvent, type PanoramaControlsOptions, type PanoramaPointerEvent, type PointHotspotDefinition, type PointHotspotDefinitionBase, PolygonHotspot, type PolygonHotspotDefinition, type PolygonHotspotProps, type PolygonValidationCode, type PolygonValidationIssue, type PolygonVerticesChangeEvent, PolylineHotspot, type PolylineHotspotDefinition, type PolylineHotspotProps, type PolylineValidationIssue, type PolylineVerticesChangeEvent, type PopupAssetUrlContext, type PopupAssetUrlResolver, type ProjectCustomActionEvent, type ProjectCustomHotspotAction, type ProjectHotspotAction, type ProjectHotspotClickEvent, type ProjectHotspotDefinition, type ProjectHotspotErrorEvent, type ProjectHotspotEvent, type ProjectHotspotRenderContext, type ProjectHotspotTrigger, type ProjectPopupBlock, type ProjectPopupDefinition, type ProjectPopupRequestEvent, ProjectScenes, type ProjectScenesProps, type RectangleGraphic, type ResolvedOverlayAnchor, type RingGraphic, type Scene, type SceneFromViewerConfigOptions, type SceneTransition, type SceneTransitionEndEvent, type SceneTransitionErrorEvent, type SceneTransitionPreset, Scenes, type ScenesController, type ScenesProps, type SequenceFrameDirection, type SequenceFrameEvent, SequenceHotspot, type SequenceHotspotDefinition, type SequenceHotspotErrorEvent, type SequenceHotspotProps, type SequenceLoadProgress, type SequencePlaybackState, type SetPanoViewerOptions, Sphere, type SphereProps, type SphereScene, SphereTile, type SphereTileAddress, type SphereTileLevel, type SphereTileLoadError, type SphereTileMultiresConfig, type SphereTileProps, type SphereTileScene, type SphereViewerConfig, type StarGraphic, type SvgGraphic, type SvgPathGraphic, TextHotspot, type TextHotspotAlign, type TextHotspotDefinition, type TextHotspotFontStyle, type TextHotspotProps, type TextHotspotStyle, type TextHotspotVerticalAlign, type TextHotspotWhiteSpace, Tile, type TileAddress, type TileLoadError, type TileLoadProgress, type TileMultiresConfig, type TileProps, type TileScene, TouchControls, type TouchControlsOptions, type TouchControlsProps, type TriangleGraphic, type UsePanoViewerResult, VideoHotspot, type VideoHotspotDefinition, type VideoHotspotErrorEvent, type VideoHotspotProps, type VideoPlaybackState, type ViewInteractionEvent, type ViewInteractionSource, type ViewerConfig, type ViewerDocument, WEBVR_PROFILES, WEBVR_PROFILE_IDS, WebVR, type WebVRChrome, type WebVRChromeAppearance, type WebVRFrameRate, type WebVRHandle, type WebVRMode, type WebVRProfile, type WebVRProfileId, type WebVRProps, type WebVRSettings, type WebVRState, clampPanoPitch, composePanoContextMenuItems, containRect, containerPointToImage, createDefaultPanoContextMenuItems, createPanoContextMenuPresets, cycleSceneId, headingFromVector, horizontalFov, hotspotAction, imagePointToContainer, isOverlayCorner, loadPanoProject, loadSceneFromJson, normalizePanoPosition, normalizePanoYaw, panoPositionToVector3, parseOverlayAnchor, parsePanoMap, parsePanoProject, projectHotspotTriggers, resolveOverlayAnchor, resolveOverlayToggleIcon, resolvePanoContextMenuEntries, resolvePanoMapAssets, resolveHotspotAssets as resolveProjectHotspotAssets, resolveProjectPopupAssets, sceneFromViewerConfig, sectorRotation, setHotspotAction, unwrapPolygonVertices, usePanoEvents, usePanoModal, usePanoOverlay, usePanoViewer, validatePolygonVertices, validatePolylineVertices, vector3ToPanoPosition };
+declare function PanoControlButton({ action, children, ...props }: Omit<ComponentProps<"button">, "ref"> & {
+    action: PanoControlAction;
+}): react.JSX.Element | null;
+type PanoControlGroupProps = Omit<ComponentProps<"div">, "children"> & {
+    actions: readonly PanoControlAction[];
+    children?: (actions: readonly PanoControlAction[]) => ReactNode;
+};
+declare function PanoControlGroup({ actions, children, ...props }: PanoControlGroupProps): react.JSX.Element | null;
+type Options = Omit<PanoControlGroupProps, "actions"> & {
+    actions?: readonly (string | PanoControlAction)[];
+};
+declare function PanoMediaControls({ controller, seekSpeed, volumeSpeed, actions, ...props }: Options & {
+    controller: PanoMediaController | null;
+    seekSpeed?: number;
+    volumeSpeed?: number;
+}): react.JSX.Element;
+declare function PanoModelControls({ adapter, rotateSpeed, zoomSpeed, actions, ...props }: Options & {
+    adapter: PanoSpatialControlAdapter;
+    rotateSpeed?: number;
+    zoomSpeed?: number;
+}): react.JSX.Element;
+declare function PanoScrollControls({ targetRef, speed, repeatIntervalMs, actions, ...props }: Options & {
+    targetRef: RefObject<HTMLElement | null>;
+    speed?: number;
+    repeatIntervalMs?: number;
+}): react.ReactPortal | null;
+type PanoSpatialControlsProps = {
+    children: ReactNode;
+    position?: {
+        yaw: number;
+        pitch: number;
+    };
+    width?: number;
+    distance?: number;
+    className?: string;
+    style?: ComponentProps<"div">["style"];
+};
+/** Render inside PanoOverlay. The measured DOM stays in the viewer's fullscreen host. */
+declare function PanoSpatialControls({ children, position, width, distance, className, style, }: PanoSpatialControlsProps): react.ReactPortal | null;
+
+/** Adapts an existing media element without owning its source or playback lifetime. */
+declare function usePanoMediaController(ref: RefObject<HTMLMediaElement | null>): PanoMediaController;
+
+type WebVRSceneMenuAppearance = {
+    controlColor?: string;
+    controlBackground?: string;
+    controlOpacity?: number;
+    selectionColor?: string;
+    focusColor?: string;
+    /** Shared selected/gaze/focus outline width in reference pixels. Defaults to 4; range 0–8. */
+    selectionWidth?: number;
+    borderRadius?: number;
+    labelColor?: string;
+    labelBackground?: string;
+    fontSize?: number;
+    labelPlacement?: "center" | "bottom";
+};
+declare const DEFAULT_WEBVR_SCENE_MENU_APPEARANCE: Required<WebVRSceneMenuAppearance>;
+type WebVRSceneMenuProps = {
+    items: readonly PanoSceneMenuItem[];
+    activeId?: string | null;
+    onSelect?: (id: string) => void;
+    /** Show an icon for scenes successfully displayed by this viewer. Defaults to false. */
+    showVisited?: boolean;
+    /** Accessible description for visited scenes; never rendered as visible text. */
+    visitedLabel?: string;
+    /** Defaults to the original compact curved grid. */
+    layout?: "compact" | "flat" | "arc";
+    /** All mode grows the row count and ignores rows. Defaults to paged. */
+    displayMode?: "paged" | "all";
+    /** Arc coverage in degrees, 60–360. Defaults to 180. */
+    arcAngle?: number;
+    columns?: number;
+    rows?: number;
+    loop?: boolean;
+    closeOnSelect?: boolean;
+    follow?: boolean;
+    navigationPitch?: number;
+    distance?: number;
+    scale?: number;
+    fadeDurationMs?: number;
+    showTitles?: boolean;
+    appearance?: WebVRSceneMenuAppearance;
+};
+/** Native spatial UI. Mount beside WebVR and Scenes inside PanoViewer. */
+declare function WebVRSceneMenu(props: WebVRSceneMenuProps): react.JSX.Element | null;
+
+export { type ArrowGraphic, type AssetUrlContext, type AssetUrlResolver, AudioHotspot, type AudioHotspotDefinition, type AudioHotspotErrorEvent, type AudioHotspotProps, type AudioPlaybackState, AutoRotate, type AutoRotateProps, BackgroundAudio, type BackgroundAudioController, type BackgroundAudioErrorEvent, type BackgroundAudioProps, type BackgroundAudioSnapshot, type BackgroundAudioSource, type CircleGraphic, type CubeFaceCode, type CubemapViewerConfig, DEFAULT_HOTSPOT_TOOLTIP_APPEARANCE, DEFAULT_HOTSPOT_TOOLTIP_OFFSET, DEFAULT_PANO_CURSORS, DEFAULT_PANO_SCENE_MENU_APPEARANCE, DEFAULT_PANO_VIDEO_CAPTION_APPEARANCE, DEFAULT_PANO_VIDEO_CONTROLS_APPEARANCE, DEFAULT_PANO_VIDEO_PLAYBACK_RATES, DEFAULT_WEBVR_CHROME_APPEARANCE, DEFAULT_WEBVR_CURSOR_DWELL_MS, DEFAULT_WEBVR_SCENE_MENU_APPEARANCE, type DiamondGraphic, EMPTY_WEBVR_STATE, type GraphicDefinition, GraphicHotspot, type GraphicHotspotDefinition, type GraphicHotspotProps, Gyro, type GyroHandle, type GyroProps, type GyroTouchMode, type HotspotCommonProps, type HotspotDefinition, type HotspotDefinitionBase, type HotspotDragEvent, type HotspotInputSource, type HotspotInteractionEvent, type HotspotMode, type HotspotPointerEvents, type HotspotPosition, type HotspotScaleMode, type HotspotTooltipAppearance, type HotspotTooltipContent, type HotspotTooltipPlacement, type HotspotTooltipScaleMode, type HotspotTooltipTrigger, IframeHotspot, type IframeHotspotDefinition, type IframeHotspotProps, type IframePointerPolicy, ImageHotspot, type ImageHotspotDefinition, type ImageHotspotProps, type JsonObject, type JsonRequestOptions, type JsonValue, type KeyboardControlAction, type KeyboardControlKeys, KeyboardControls, type KeyboardControlsProps, type LoadPanoProjectOptions, type LoadSceneFromJsonOptions, type LoadedPanoProject, type LoadedProjectScene, MAX_HOTSPOT_PITCH, MIN_PANO_CONTEXT_MENU_BACKGROUND_OPACITY, type MouseControlButton, MouseControls, type MouseControlsOptions, type MouseControlsProps, PANO_FILTER_PRESETS, PANO_OVERLAY_ALIGNS, type PanoColorMatrix, PanoContextMenu, type PanoContextMenuActionItem, type PanoContextMenuAppearance, type PanoContextMenuEntry, type PanoContextMenuItem, type PanoContextMenuPresetActions, type PanoContextMenuPresetId, type PanoContextMenuPresetRef, type PanoContextMenuPresets, type PanoContextMenuProps, type PanoContextMenuRenderProps, type PanoContextMenuSelectContext, type PanoContextMenuSeparatorItem, type PanoControlAction, PanoControlButton, PanoControlGroup, type PanoControlGroupProps, type PanoCursor, type PanoCursors, PanoDataError, type PanoDataErrorCode, PanoDialogSurfaceContext, type PanoDragMotion, type PanoEventBus, type PanoEventListener, type PanoEventMap, type PanoEventType, PanoEvents, type PanoEventsProps, PanoFilter, type PanoFilterPreset, type PanoFilterProps, PanoMap, type PanoMapControlsDefinition, type PanoMapDefinition, type PanoMapDialogPresentation, type PanoMapEditChange, type PanoMapGradientStop, PanoMapOverlay, type PanoMapOverlayProps, type PanoMapPanelPresentation, type PanoMapPresentation, type PanoMapProps, type PanoMapSectorDefinition, type PanoMapSectorGradient, type PanoMapSpotDefinition, type PanoMediaActivationControls, type PanoMediaActivationOptions, type PanoMediaController, PanoMediaControls, PanoModelControls, PanoOverlay, type PanoOverlayAlign, type PanoOverlayAnchor, type PanoOverlayAxis, type PanoOverlayChevron, type PanoOverlayCollapseEdge, type PanoOverlayContentAlign, type PanoOverlayInset, PanoOverlayPortalProvider, type PanoOverlayProps, type PanoOverlayRenderContext, type PanoOverlayToggle, type PanoOverlayToggleState, type PanoProjectDefinition, type PanoProjectSceneDefinition, type PanoResizeEvent, PanoSceneMenu, type PanoSceneMenuAppearance, type PanoSceneMenuItem, type PanoSceneMenuLabelAlign, type PanoSceneMenuProps, PanoScrollControls, type PanoSpatialControlAdapter, PanoSpatialControls, type PanoSpatialControlsProps, PanoVideo, type PanoVideoCaptionAppearance, type PanoVideoController, PanoVideoControls, type PanoVideoControlsAppearance, type PanoVideoControlsProps, type PanoVideoErrorEvent, type PanoVideoErrorSource, type PanoVideoPlaybackSnapshot, type PanoVideoProps, type PanoVideoSource, type PanoVideoTrack, type PanoVideoTrackKind, type PanoVideoVariant, type PanoViewEasing, type PanoViewLimits, type PanoViewLookToOptions, type PanoViewNavigationOptions, type PanoViewNavigationResult, PanoViewer, type PanoViewerHandle, type PanoViewerProps, type PanoViewerState, type PanoWheelEvent, type PanoramaControlsOptions, type PanoramaPointerEvent, type PointHotspotDefinition, type PointHotspotDefinitionBase, PolygonHotspot, type PolygonHotspotDefinition, type PolygonHotspotProps, type PolygonValidationCode, type PolygonValidationIssue, type PolygonVerticesChangeEvent, PolylineHotspot, type PolylineHotspotDefinition, type PolylineHotspotProps, type PolylineValidationIssue, type PolylineVerticesChangeEvent, type PopupAssetUrlContext, type PopupAssetUrlResolver, type ProjectCustomActionEvent, type ProjectCustomHotspotAction, type ProjectHotspotAction, type ProjectHotspotClickEvent, type ProjectHotspotDefinition, type ProjectHotspotErrorEvent, type ProjectHotspotEvent, type ProjectHotspotRenderContext, type ProjectHotspotTrigger, type ProjectPopupBlock, type ProjectPopupDefinition, type ProjectPopupRequestEvent, ProjectScenes, type ProjectScenesProps, type RectangleGraphic, type ResolvedOverlayAnchor, type RingGraphic, type Scene, type SceneFromViewerConfigOptions, type SceneTransition, type SceneTransitionEndEvent, type SceneTransitionErrorEvent, type SceneTransitionPreset, Scenes, type ScenesController, type ScenesProps, type SequenceFrameDirection, type SequenceFrameEvent, SequenceHotspot, type SequenceHotspotDefinition, type SequenceHotspotErrorEvent, type SequenceHotspotProps, type SequenceLoadProgress, type SequencePlaybackState, type SetPanoViewerOptions, Sphere, type SphereProps, type SphereScene, SphereTile, type SphereTileAddress, type SphereTileLevel, type SphereTileLoadError, type SphereTileMultiresConfig, type SphereTileProps, type SphereTileScene, type SphereViewerConfig, type StarGraphic, type SvgGraphic, type SvgPathGraphic, TextHotspot, type TextHotspotAlign, type TextHotspotDefinition, type TextHotspotFontStyle, type TextHotspotProps, type TextHotspotStyle, type TextHotspotVerticalAlign, type TextHotspotWhiteSpace, Tile, type TileAddress, type TileLoadError, type TileLoadProgress, type TileMultiresConfig, type TileProps, type TileScene, TouchControls, type TouchControlsOptions, type TouchControlsProps, type TriangleGraphic, type UsePanoViewerResult, VideoHotspot, type VideoHotspotDefinition, type VideoHotspotErrorEvent, type VideoHotspotProps, type VideoPlaybackState, type ViewInteractionEvent, type ViewInteractionSource, type ViewerConfig, type ViewerDocument, WEBVR_PROFILES, WEBVR_PROFILE_IDS, WebVR, type WebVRChrome, type WebVRChromeAppearance, type WebVRFrameRate, type WebVRHandle, type WebVRInputState, type WebVRInteractionMode, type WebVRMode, type WebVRProfile, type WebVRProfileId, type WebVRProps, WebVRSceneMenu, type WebVRSceneMenuAppearance, type WebVRSceneMenuProps, type WebVRSettings, type WebVRState, clampPanoPitch, composePanoContextMenuItems, containRect, containerPointToImage, createDefaultPanoContextMenuItems, createPanoContextMenuPresets, cycleSceneId, headingFromVector, horizontalFov, hotspotAction, imagePointToContainer, isOverlayCorner, loadPanoProject, loadSceneFromJson, normalizePanoPosition, normalizePanoYaw, panoPositionToVector3, parseOverlayAnchor, parsePanoMap, parsePanoProject, projectHotspotTriggers, resolveOverlayAnchor, resolveOverlayToggleIcon, resolvePanoContextMenuEntries, resolvePanoMapAssets, resolveHotspotAssets as resolveProjectHotspotAssets, resolveProjectPopupAssets, sceneFromViewerConfig, sectorRotation, setHotspotAction, unwrapPolygonVertices, usePanoDialogSurface, usePanoEvents, usePanoMediaController, usePanoModal, usePanoOverlay, usePanoSpatialControls, usePanoViewer, validatePolygonVertices, validatePolylineVertices, vector3ToPanoPosition };