@ericchen1990/pano-view 0.1.6 → 1.0.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode, ComponentPropsWithoutRef } from 'react';
+import { CSSProperties, ReactNode, ComponentPropsWithoutRef, IframeHTMLAttributes } from 'react';
 import { Texture, ColorRepresentation, Vector3 } from 'three';
 
 declare const MAX_HOTSPOT_PITCH = 90;
@@ -29,9 +29,33 @@ type HotspotDragEvent = HotspotInteractionEvent & {
     source: "pointer";
     startPosition: HotspotPosition;
 };
+/** When a hotspot tooltip is shown. Defaults to `"always"`. */
+type HotspotTooltipTrigger = "always" | "hover" | "click";
+/** Where the tooltip sits relative to the hotspot. Defaults to `"top"`. */
+type HotspotTooltipPlacement = "top" | "bottom" | "left" | "right";
+/** Plain-text and/or image content for a hotspot tooltip. */
+type HotspotTooltipContent = {
+    text?: string;
+    image?: string;
+    imageAlt?: string;
+};
 type HotspotCommonProps = {
     id: string;
     position: HotspotPosition;
+    /**
+     * Tooltip shown at the hotspot anchor. A string is treated as `{ text }`.
+     * Defaults to always visible when content is present.
+     */
+    tooltip?: string | HotspotTooltipContent;
+    /** Defaults to `"always"`. `"hover"` and `"click"` require `interactive`. */
+    tooltipTrigger?: HotspotTooltipTrigger;
+    /** Defaults to `"top"`. */
+    tooltipPlacement?: HotspotTooltipPlacement;
+    /**
+     * Screen-space gap in CSS pixels between the hotspot edge and the tooltip.
+     * Defaults to 12.
+     */
+    tooltipOffset?: number;
     /** Angular width in degrees. Defaults to 12. */
     width?: number;
     /** Angular height in degrees. Defaults to 8. */
@@ -56,6 +80,11 @@ type HotspotCommonProps = {
     visible?: boolean;
     /** Whether the hotspot accepts pointer and keyboard interaction. Defaults to true. */
     interactive?: boolean;
+    /**
+     * Canvas cursor while this hotspot is hovered. Defaults to the viewer's
+     * `cursors.hotspot` value (`"pointer"`).
+     */
+    cursor?: CSSProperties["cursor"];
     draggable?: boolean;
     /** Required for keyboard-accessible clickable hotspots. */
     ariaLabel?: string;
@@ -75,7 +104,52 @@ type PanoramaPointerEvent = {
     clientY: number;
 };
 
-type PanoViewState = {
+type KeyboardControlAction = "left" | "right" | "up" | "down" | "zoomIn" | "zoomOut" | "previousScene" | "nextScene" | "reset";
+type KeyboardControlKeys = Partial<Record<KeyboardControlAction, string | readonly string[]>>;
+/** Options for keyboard-driven panorama navigation. */
+type KeyboardControlsProps = {
+    /** Whether keyboard handling is active. Defaults to true. */
+    enabled?: boolean;
+    /**
+     * Custom key bindings. Each action accepts a key, code, or list of either.
+     * Matching is case-insensitive for `event.key` and exact for `event.code`.
+     */
+    keys?: KeyboardControlKeys;
+    /** Yaw/pitch change rate in degrees per second. Defaults to 60. */
+    rotateSpeed?: number;
+    /** FOV change rate in degrees per second. Defaults to 30. */
+    zoomSpeed?: number;
+    /** Speed multiplier while Shift is held. Defaults to 3. */
+    shiftMultiplier?: number;
+    /** Inverts up/down look direction. Defaults to false. */
+    invert?: boolean;
+    /**
+     * Maximum FOV change rate in degrees per second. When omitted, no extra
+     * rate cap is applied. Usually supplied by PanoViewer from `controls.fovSpeed`.
+     */
+    fovSpeed?: number;
+    /** Called once when the previous-scene binding is pressed. */
+    onPreviousScene?: () => void;
+    /** Called once when the next-scene binding is pressed. */
+    onNextScene?: () => void;
+};
+/**
+ * Returns the scene id `step` positions away from `activeSceneId` in
+ * `scenes`, wrapping at both ends. Returns `null` when the list is empty or
+ * the active id is missing.
+ */
+declare function cycleSceneId(scenes: readonly {
+    id: string;
+}[], activeSceneId: string, step: 1 | -1): string | null;
+/**
+ * Adds keyboard navigation to the nearest PanoViewer. Enabled by default;
+ * render this component only to override properties, bindings, or scene
+ * callbacks. Hold movement/zoom keys for continuous motion; scene and reset
+ * bindings fire once per key press.
+ */
+declare function KeyboardControls({ enabled, keys, rotateSpeed, zoomSpeed, shiftMultiplier, invert, fovSpeed, onPreviousScene, onNextScene, }: KeyboardControlsProps): null;
+
+type PanoViewerState = {
     /** Horizontal look angle in degrees. Positive values look right. */
     yaw: number;
     /** Vertical look angle in degrees. Positive values look up. */
@@ -83,13 +157,13 @@ type PanoViewState = {
     /** Vertical perspective field of view in degrees. */
     fov: number;
 };
-type SetPanoViewOptions = {
+type SetPanoViewerOptions = {
     /** Apply the new view immediately instead of preserving current inertia. */
     immediate?: boolean;
 };
-type PanoViewHandle = {
-    getView: () => PanoViewState;
-    setView: (view: Partial<PanoViewState>, options?: SetPanoViewOptions) => void;
+type PanoViewerHandle = {
+    getView: () => PanoViewerState;
+    setView: (view: Partial<PanoViewerState>, options?: SetPanoViewerOptions) => void;
     reset: () => void;
     /** @deprecated Control an AutoRotate component's enabled prop instead. */
     startAutoRotate: () => void;
@@ -97,16 +171,74 @@ type PanoViewHandle = {
     stopAutoRotate: () => void;
     toggleFullscreen: () => Promise<void>;
 };
+type MouseControlButton = "left" | "middle" | "right";
+/** Options for the default mouse control channel (also MouseControls props). */
+type MouseControlsOptions = {
+    /** Whether mouse handling is active. Defaults to true. */
+    enabled?: boolean;
+    /** Pointer drag multiplier. Defaults to 0.35. */
+    rotateSpeed?: number;
+    /** Wheel zoom multiplier. Defaults to 0.08. */
+    zoomSpeed?: number;
+    /** Whether mouse-wheel zoom is enabled. Defaults to true. */
+    wheel?: boolean;
+    /** Inverts drag direction. Defaults to the all-mode `invert` value. */
+    invert?: boolean;
+    /** Mouse buttons that may drag the panorama. Defaults to `["left"]`. */
+    buttons?: readonly MouseControlButton[];
+};
+/** Options for the default touch control channel (also TouchControls props). */
+type TouchControlsOptions = {
+    /** Whether touch handling is active. Defaults to true. */
+    enabled?: boolean;
+    /** Pointer drag multiplier. Defaults to 0.35. */
+    rotateSpeed?: number;
+    /** Inverts drag direction. Defaults to the all-mode `invert` value. */
+    invert?: boolean;
+    /** Whether two-finger pinch zoom is enabled. Defaults to true. */
+    pinchZoom?: boolean;
+};
 type PanoramaControlsOptions = {
+    /**
+     * Master switch for user view controls. Defaults to true. Setting
+     * `controls={false}` on PanoViewer still disables all user input.
+     */
+    enabled?: boolean;
     /** Enables drag and zoom inertia. Defaults to true. */
     inertia?: boolean;
-    /** @deprecated Render <AutoRotate enabled /> inside PanoView instead. */
+    /** @deprecated Render <AutoRotate enabled /> inside PanoViewer instead. */
     autoRotate?: boolean;
     /** @deprecated Use AutoRotate's speed prop instead. */
     autoRotateSpeed?: number;
-    /** Pointer drag multiplier. Defaults to 0.35. */
+    /**
+     * Inverts drag/pan direction for mouse and touch. Defaults to false.
+     * Per-channel `invert` on MouseControls / TouchControls overrides this.
+     */
+    invert?: boolean;
+    /**
+     * Allows pitch and FOV to briefly overshoot hard limits while dragging,
+     * then spring back on release. Defaults to false.
+     */
+    bouncingLimits?: boolean;
+    /**
+     * Maximum FOV change rate in degrees per second for wheel and keyboard
+     * zoom. When omitted, no extra rate cap is applied.
+     */
+    fovSpeed?: number;
+    /**
+     * Relative factor for stopping inertia. Lower values fade out more
+     * smoothly. Defaults to 0.01.
+     */
+    frictionStop?: number;
+    /**
+     * Default pointer drag multiplier for mouse and touch. Defaults to 0.35.
+     * Prefer `controls.mouse` / `controls.touch` for per-channel overrides.
+     */
     rotateSpeed?: number;
-    /** Wheel zoom multiplier. Defaults to 0.08. */
+    /**
+     * Default wheel zoom multiplier for mouse. Defaults to 0.08.
+     * Prefer `controls.mouse.zoomSpeed` for overrides.
+     */
     zoomSpeed?: number;
     /**
      * Rotation target-following speed in seconds^-1. Defaults to 14; use 0 for
@@ -118,36 +250,228 @@ type PanoramaControlsOptions = {
      * immediate response. Must be a non-negative finite number.
      */
     zoomDamping?: number;
-    /** Enables focusable keyboard controls. Defaults to true. */
-    keyboard?: boolean;
+    /**
+     * Mouse channel. `true` / omit mounts defaults; `false` disables the
+     * default instance; an object merges with defaults and supports `enabled`.
+     * Rendering `<MouseControls />` as a child also replaces the default.
+     */
+    mouse?: boolean | MouseControlsOptions;
+    /**
+     * Touch channel. Same shape as `mouse`.
+     */
+    touch?: boolean | TouchControlsOptions;
+    /**
+     * Keyboard channel. Same shape as `mouse`. Rendering `<KeyboardControls />`
+     * as a child replaces the default (no need to set this to false).
+     */
+    keyboard?: boolean | KeyboardControlsProps;
 };
 
-type PanoViewProps = Omit<ComponentPropsWithoutRef<"div">, "children" | "onChange"> & {
+/** Lowest allowed `appearance.opacity` (background only). */
+declare const MIN_PANO_CONTEXT_MENU_BACKGROUND_OPACITY = 0.4;
+type PanoContextMenuSelectContext = {
+    position: PanoramaPointerEvent["position"];
+    view: PanoViewerState;
+    nativeEvent: MouseEvent | PointerEvent;
+    close: () => void;
+};
+type PanoContextMenuActionItem = {
+    type?: "item";
+    id: string;
+    label: string;
+    /** React icon node (inline SVG, icon library component, emoji, etc.). */
+    icon?: ReactNode;
+    /** Image URL; ignored when `icon` is set. */
+    image?: string;
+    imageAlt?: string;
+    disabled?: boolean;
+    hidden?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    onSelect: (context: PanoContextMenuSelectContext) => void;
+};
+type PanoContextMenuSeparatorItem = {
+    type: "separator";
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+};
+type PanoContextMenuItem = PanoContextMenuActionItem | PanoContextMenuSeparatorItem;
+/** Built-in menu entries hosts can reuse without reimplementing behavior. */
+type PanoContextMenuPresetId = "resetView" | "fullscreen" | "separator";
+/**
+ * Reference a built-in preset, optionally overriding presentation fields.
+ * Action wiring (reset / fullscreen toggle and enter/exit label) stays built-in.
+ */
+type PanoContextMenuPresetRef = {
+    preset: PanoContextMenuPresetId;
+    id?: string;
+    label?: string;
+    className?: string;
+    style?: CSSProperties;
+    disabled?: boolean;
+    hidden?: boolean;
+};
+/** A custom action item, a preset id string, or a preset ref with overrides. */
+type PanoContextMenuEntry = PanoContextMenuActionItem | PanoContextMenuPresetId | PanoContextMenuPresetRef;
+type PanoContextMenuAppearance = {
+    background?: string;
+    color?: string;
+    border?: string;
+    borderRadius?: number | string;
+    shadow?: string;
+    /**
+     * Background-only opacity from {@link MIN_PANO_CONTEXT_MENU_BACKGROUND_OPACITY}
+     * to 1. Defaults to 1. Text and icons stay fully opaque.
+     */
+    opacity?: number;
+    fontSize?: number | string;
+    minWidth?: number | string;
+    padding?: number | string;
+    iconSize?: number;
+    itemPadding?: string;
+    itemHoverBackground?: string;
+    itemDisabledColor?: string;
+    separatorColor?: string;
+    separatorMargin?: string;
+};
+type PanoContextMenuRenderProps = {
+    event: PanoramaPointerEvent;
+    view: PanoViewerState;
+    close: () => void;
+};
+type PanoContextMenuProps = {
+    /**
+     * Menu entries. May mix concrete items with built-in presets
+     * (`"resetView"`, `"fullscreen"`, `"separator"`). When omitted, the
+     * default Reset view / Fullscreen list is used (see also `prepend` /
+     * `append`).
+     */
+    items?: readonly PanoContextMenuEntry[];
+    /**
+     * Entries placed before the default menu when `items` is omitted.
+     * Ignored when `items` is provided.
+     */
+    prepend?: readonly PanoContextMenuEntry[];
+    /**
+     * Entries placed after the default menu when `items` is omitted.
+     * Ignored when `items` is provided.
+     */
+    append?: readonly PanoContextMenuEntry[];
+    appearance?: PanoContextMenuAppearance;
+    className?: string;
+    style?: CSSProperties;
+    itemClassName?: string;
+    separatorClassName?: string;
+    /**
+     * Fully custom menu content. When provided, takes precedence over `items`.
+     * Opening, closing, and positioning remain handled by PanoContextMenu.
+     */
+    children?: (props: PanoContextMenuRenderProps) => ReactNode;
+};
+/**
+ * Custom panorama context menu. Must render inside PanoViewer. Prefer
+ * PanoViewer's `contextMenu` prop for the default menu; use this component
+ * when replacing the default instance (`contextMenu={false}`).
+ */
+declare function PanoContextMenu({ items, prepend, append, appearance, className, style, itemClassName, separatorClassName, children, }: PanoContextMenuProps): null;
+type PanoContextMenuPresetActions = {
+    reset: () => void;
+    toggleFullscreen: () => void;
+    /** When true, the fullscreen preset shows Exit fullscreen. */
+    isFullscreen?: boolean;
+};
+type PanoContextMenuPresets = {
+    resetView: PanoContextMenuActionItem;
+    fullscreen: PanoContextMenuActionItem;
+    separator: (id?: string) => PanoContextMenuSeparatorItem;
+    /** Default menu: Reset view, separator, Enter/Exit fullscreen. */
+    defaults: PanoContextMenuItem[];
+};
+/**
+ * Builds reusable built-in context-menu items. Prefer preset id strings
+ * (`"resetView"`, `"fullscreen"`) in `items` / `append` / `prepend` when
+ * configuring `PanoViewer`; use this helper when assembling items manually.
+ */
+declare function createPanoContextMenuPresets(actions: PanoContextMenuPresetActions): PanoContextMenuPresets;
+/** Alias for `createPanoContextMenuPresets(actions).defaults`. */
+declare function createDefaultPanoContextMenuItems(actions: PanoContextMenuPresetActions): PanoContextMenuItem[];
+/**
+ * Expands preset ids / refs into concrete menu items using the given presets.
+ */
+declare function resolvePanoContextMenuEntries(entries: readonly PanoContextMenuEntry[], presets: PanoContextMenuPresets): PanoContextMenuItem[];
+/**
+ * Resolves `items`, or `prepend` + defaults + `append` when `items` is omitted.
+ */
+declare function composePanoContextMenuItems(props: Pick<PanoContextMenuProps, "items" | "prepend" | "append">, presets: PanoContextMenuPresets): PanoContextMenuItem[];
+
+/** A CSS `cursor` value applied to the panorama canvas. */
+type PanoCursor = NonNullable<CSSProperties["cursor"]>;
+/** Canvas cursor values for viewer idle, drag, and hotspot interaction. */
+type PanoCursors = {
+    /** Idle canvas cursor. Defaults to `"grab"`. */
+    default?: PanoCursor;
+    /** Cursor while dragging the panorama with the mouse. Defaults to `"grabbing"`. */
+    dragging?: PanoCursor;
+    /** Cursor while hovering an interactive hotspot. Defaults to `"pointer"`. */
+    hotspot?: PanoCursor;
+    /** Cursor while dragging a hotspot. Defaults to `"move"`. */
+    hotspotDragging?: PanoCursor;
+};
+declare const DEFAULT_PANO_CURSORS: Required<PanoCursors>;
+
+type PanoViewerProps = Omit<ComponentPropsWithoutRef<"div">, "children" | "onChange" | "contextMenu"> & {
     children?: ReactNode;
-    initialView?: Partial<PanoViewState>;
+    initialView?: Partial<PanoViewerState>;
     minFov?: number;
     maxFov?: number;
     controls?: boolean | PanoramaControlsOptions;
-    onViewChange?: (view: PanoViewState) => void;
+    /**
+     * Canvas cursor. `true` / omit uses grab / grabbing / pointer / move;
+     * `false` leaves the canvas cursor unchanged; an object merges with the
+     * defaults (`default`, `dragging`, `hotspot`, `hotspotDragging`).
+     */
+    cursors?: boolean | PanoCursors;
+    /**
+     * Default context menu. `true` / omit mounts Reset view + Fullscreen;
+     * `false` skips the default instance; an object merges appearance and
+     * may use `items` (full replace, supports preset ids), or `prepend` /
+     * `append` to keep the defaults and add entries.
+     */
+    contextMenu?: boolean | PanoContextMenuProps;
+    onViewChange?: (view: PanoViewerState) => void;
     onPanoramaClick?: (event: PanoramaPointerEvent) => void;
     onPanoramaDoubleClick?: (event: PanoramaPointerEvent) => void;
     onPanoramaPointerMove?: (event: PanoramaPointerEvent) => void;
     /** Canvas pixel ratio. Defaults to a capped range of 1–2. */
     dpr?: number | [number, number];
 };
-declare const PanoView: react.ForwardRefExoticComponent<Omit<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "children" | "onChange"> & {
+declare const PanoViewer: react.ForwardRefExoticComponent<Omit<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "children" | "contextMenu" | "onChange"> & {
     children?: ReactNode;
-    initialView?: Partial<PanoViewState>;
+    initialView?: Partial<PanoViewerState>;
     minFov?: number;
     maxFov?: number;
     controls?: boolean | PanoramaControlsOptions;
-    onViewChange?: (view: PanoViewState) => void;
+    /**
+     * Canvas cursor. `true` / omit uses grab / grabbing / pointer / move;
+     * `false` leaves the canvas cursor unchanged; an object merges with the
+     * defaults (`default`, `dragging`, `hotspot`, `hotspotDragging`).
+     */
+    cursors?: boolean | PanoCursors;
+    /**
+     * Default context menu. `true` / omit mounts Reset view + Fullscreen;
+     * `false` skips the default instance; an object merges appearance and
+     * may use `items` (full replace, supports preset ids), or `prepend` /
+     * `append` to keep the defaults and add entries.
+     */
+    contextMenu?: boolean | PanoContextMenuProps;
+    onViewChange?: (view: PanoViewerState) => void;
     onPanoramaClick?: (event: PanoramaPointerEvent) => void;
     onPanoramaDoubleClick?: (event: PanoramaPointerEvent) => void;
     onPanoramaPointerMove?: (event: PanoramaPointerEvent) => void;
     /** Canvas pixel ratio. Defaults to a capped range of 1–2. */
     dpr?: number | [number, number];
-} & react.RefAttributes<PanoViewHandle>>;
+} & react.RefAttributes<PanoViewerHandle>>;
 
 /** Options for automatic horizontal panorama rotation. */
 type AutoRotateProps = {
@@ -164,11 +488,110 @@ type AutoRotateProps = {
     startDelay?: number;
 };
 /**
- * Adds automatic rotation to the nearest PanoView. Render one instance as a
- * child of PanoView, alongside its panorama source.
+ * Adds automatic rotation to the nearest PanoViewer. Render one instance as a
+ * child of PanoViewer, alongside its panorama source.
  */
 declare function AutoRotate({ enabled, speed, acceleration, startDelay, }: AutoRotateProps): null;
 
+type ViewInteractionSource = "mouse" | "touch" | "keyboard";
+type PanoWheelEvent = {
+    /** Signed wheel delta (same sign convention as WheelEvent.deltaY). */
+    delta: number;
+    nativeEvent: WheelEvent;
+};
+type PanoResizeEvent = {
+    width: number;
+    height: number;
+};
+type ViewInteractionEvent = {
+    source: ViewInteractionSource;
+};
+type PanoEventMap = {
+    viewchange: PanoViewerState;
+    viewsettled: PanoViewerState;
+    viewinteractionstart: ViewInteractionEvent;
+    viewinteractionend: ViewInteractionEvent;
+    click: PanoramaPointerEvent;
+    doubleclick: PanoramaPointerEvent;
+    pointerdown: PanoramaPointerEvent;
+    pointerup: PanoramaPointerEvent;
+    pointermove: PanoramaPointerEvent;
+    contextmenu: PanoramaPointerEvent;
+    wheel: PanoWheelEvent;
+    idle: undefined;
+    idleend: undefined;
+    enterfullscreen: undefined;
+    exitfullscreen: undefined;
+    resize: PanoResizeEvent;
+    autorotatestart: undefined;
+    autorotatestop: undefined;
+    autorotateoneround: undefined;
+};
+type PanoEventType = keyof PanoEventMap;
+type PanoEventListener<T extends PanoEventType> = (payload: PanoEventMap[T]) => void;
+type PanoEventBus = {
+    subscribe: <T extends PanoEventType>(type: T, listener: PanoEventListener<T>) => () => void;
+    emit: <T extends PanoEventType>(type: T, payload: PanoEventMap[T]) => void;
+};
+
+type PanoEventsProps = {
+    /**
+     * Milliseconds without user interaction before `onIdle`. Defaults to 2000.
+     * Each PanoEvents instance tracks idle independently.
+     */
+    idleTime?: number;
+    onViewChange?: (view: PanoViewerState) => void;
+    onViewSettled?: (view: PanoViewerState) => void;
+    onViewInteractionStart?: (event: ViewInteractionEvent) => void;
+    onViewInteractionEnd?: (event: ViewInteractionEvent) => void;
+    onClick?: (event: PanoramaPointerEvent) => void;
+    onDoubleClick?: (event: PanoramaPointerEvent) => void;
+    onPointerDown?: (event: PanoramaPointerEvent) => void;
+    onPointerUp?: (event: PanoramaPointerEvent) => void;
+    onPointerMove?: (event: PanoramaPointerEvent) => void;
+    onContextMenu?: (event: PanoramaPointerEvent) => void;
+    onWheel?: (event: PanoWheelEvent) => void;
+    onIdle?: () => void;
+    onIdleEnd?: () => void;
+    onEnterFullscreen?: () => void;
+    onExitFullscreen?: () => void;
+    onResize?: (event: PanoResizeEvent) => void;
+    onAutoRotateStart?: () => void;
+    onAutoRotateStop?: () => void;
+    onAutoRotateOneRound?: () => void;
+};
+/**
+ * Subscribes to viewer-level panorama events. Must run inside PanoViewer.
+ * Prefer the {@link PanoEvents} component for declarative usage.
+ */
+declare function usePanoEvents({ idleTime, onViewChange, onViewSettled, onViewInteractionStart, onViewInteractionEnd, onClick, onDoubleClick, onPointerDown, onPointerUp, onPointerMove, onContextMenu, onWheel, onIdle, onIdleEnd, onEnterFullscreen, onExitFullscreen, onResize, onAutoRotateStart, onAutoRotateStop, onAutoRotateOneRound, }: PanoEventsProps): void;
+/**
+ * Declarative viewer-level event listeners for the nearest PanoViewer.
+ * Multiple instances may coexist; each tracks its own idle timer.
+ */
+declare function PanoEvents(props: PanoEventsProps): null;
+
+type MouseControlsProps = MouseControlsOptions & {
+    /**
+     * Maximum FOV change rate in degrees per second for wheel zoom. When
+     * omitted, no extra rate cap is applied. Usually supplied by PanoViewer from
+     * `controls.fovSpeed`.
+     */
+    fovSpeed?: number;
+};
+/**
+ * Adds mouse (and pen) drag / wheel navigation to the nearest PanoViewer.
+ * Enabled by default; render this component only to override properties.
+ */
+declare function MouseControls({ enabled, rotateSpeed, zoomSpeed, wheel, invert, buttons, fovSpeed, }: MouseControlsProps): null;
+
+type TouchControlsProps = TouchControlsOptions;
+/**
+ * Adds touch drag and pinch-zoom navigation to the nearest PanoViewer.
+ * Enabled by default; render this component only to override properties.
+ */
+declare function TouchControls({ enabled, rotateSpeed, invert, pinchZoom, }: TouchControlsProps): null;
+
 type SphereProps = {
     src: string;
     /** Horizontal image offset in degrees. */
@@ -245,40 +668,40 @@ type TileProps = {
     onLevelChange?: (level: number) => void;
 };
 
-type PanoramaTransitionPreset = "none" | "crossfade" | "zoom" | "blackout" | "whiteFlash" | "slideRightToLeft" | "slideTopToBottom" | "slideDiagonal" | "circleOpen" | "verticalOpen" | "horizontalOpen" | "ellipticZoomOpen";
-type PanoramaTransition = PanoramaTransitionPreset | {
-    preset: PanoramaTransitionPreset;
+type SceneTransitionPreset = "none" | "crossfade" | "zoom" | "blackout" | "whiteFlash" | "slideRightToLeft" | "slideTopToBottom" | "slideDiagonal" | "circleOpen" | "verticalOpen" | "horizontalOpen" | "ellipticZoomOpen";
+type SceneTransition = SceneTransitionPreset | {
+    preset: SceneTransitionPreset;
     /** Overrides the KRpano-compatible default duration in seconds. */
     duration?: number;
 };
-type SpherePanoramaScene = {
+type SphereScene = {
     id: string;
     type: "sphere";
     src: string;
     yawOffset?: number;
 };
-type TilePanoramaScene = Omit<TileProps, "loadMode" | "visible" | "onReady" | "onPreviewError" | "onLoadProgress" | "onTileError" | "onLevelChange"> & {
+type TileScene = Omit<TileProps, "loadMode" | "visible" | "onReady" | "onPreviewError" | "onLoadProgress" | "onTileError" | "onLevelChange"> & {
     id: string;
     type: "tile";
 };
-type PanoramaScene = SpherePanoramaScene | TilePanoramaScene;
-type PanoramaTransitionEndEvent = {
+type Scene = SphereScene | TileScene;
+type SceneTransitionEndEvent = {
     previousSceneId: string;
     sceneId: string;
-    preset: PanoramaTransitionPreset;
+    preset: SceneTransitionPreset;
 };
-type PanoramaTransitionErrorEvent = {
+type SceneTransitionErrorEvent = {
     sceneId: string;
     error: unknown;
 };
-type PanoramaScenesProps = {
-    scenes: readonly PanoramaScene[];
+type ScenesProps = {
+    scenes: readonly Scene[];
     activeSceneId: string;
-    transition?: PanoramaTransition;
+    transition?: SceneTransition;
     /** Rendered only after a scene has finished transitioning in. */
-    renderHotspots?: (scene: PanoramaScene) => ReactNode;
-    onTransitionEnd?: (event: PanoramaTransitionEndEvent) => void;
-    onTransitionError?: (event: PanoramaTransitionErrorEvent) => void;
+    renderHotspots?: (scene: Scene) => ReactNode;
+    onTransitionEnd?: (event: SceneTransitionEndEvent) => void;
+    onTransitionError?: (event: SceneTransitionErrorEvent) => void;
     /** Viewer-wide budget shared by every tile scene. Defaults to 128 MiB. */
     maxTextureMemoryMb?: number;
     /** Viewer-wide tile request limit. Defaults to 4. */
@@ -286,7 +709,7 @@ type PanoramaScenesProps = {
     /** Maximum physical-pixel area of the outgoing GPU snapshot. */
     snapshotMaxPixels?: number;
 };
-declare function PanoramaScenes({ maxTextureMemoryMb, maxConcurrentTileLoads, ...props }: PanoramaScenesProps): react.JSX.Element;
+declare function Scenes({ maxTextureMemoryMb, maxConcurrentTileLoads, ...props }: ScenesProps): react.JSX.Element;
 
 type ImageHotspotProps = HotspotCommonProps & {
     src: string;
@@ -361,8 +784,21 @@ type GraphicPaint = {
 type CircleGraphic = GraphicPaint & {
     kind: "circle";
 };
+type TriangleGraphic = GraphicPaint & {
+    kind: "triangle";
+};
+type DiamondGraphic = GraphicPaint & {
+    kind: "diamond";
+};
+type StarGraphic = GraphicPaint & {
+    kind: "star";
+};
+type ArrowGraphic = GraphicPaint & {
+    kind: "arrow";
+};
 type RectangleGraphic = GraphicPaint & {
     kind: "rectangle";
+    /** Relative radius from 0 (square corners) to 0.5 (maximum rounded corners). */
     cornerRadius?: number;
 };
 type RingGraphic = GraphicPaint & {
@@ -378,7 +814,7 @@ type SvgPathGraphic = GraphicPaint & {
     path: string;
     viewBox: [x: number, y: number, width: number, height: number];
 };
-type GraphicDefinition = CircleGraphic | RectangleGraphic | RingGraphic | SvgGraphic | SvgPathGraphic;
+type GraphicDefinition = CircleGraphic | TriangleGraphic | DiamondGraphic | StarGraphic | ArrowGraphic | RectangleGraphic | RingGraphic | SvgGraphic | SvgPathGraphic;
 type GraphicHotspotProps = HotspotCommonProps & {
     graphic: GraphicDefinition;
     onLoad?: (texture: Texture) => void;
@@ -444,6 +880,59 @@ type VideoHotspotProps = HotspotCommonProps & {
 };
 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 TextHotspotAlign = "left" | "center" | "right";
+type TextHotspotVerticalAlign = "top" | "middle" | "bottom";
+type TextHotspotWhiteSpace = "normal" | "nowrap";
+type TextHotspotFontStyle = "normal" | "italic";
+/** Serializable typography and panel paint for a text hotspot. */
+type TextHotspotStyle = {
+    fontFamily?: string;
+    /** Fraction of the texture height. Defaults to 0.18. */
+    fontSize?: number;
+    fontWeight?: number | string;
+    fontStyle?: TextHotspotFontStyle;
+    color?: string;
+    /** CSS color. An empty string skips the panel fill. */
+    background?: string;
+    backgroundOpacity?: number;
+    /** Fraction of the texture's shorter side. */
+    padding?: number;
+    align?: TextHotspotAlign;
+    verticalAlign?: TextHotspotVerticalAlign;
+    lineHeight?: number;
+    whiteSpace?: TextHotspotWhiteSpace;
+    /** Fraction of the texture's shorter side, from 0 to 0.5. */
+    borderRadius?: number;
+    stroke?: string;
+    strokeWidth?: number;
+};
+type TextHotspotProps = HotspotCommonProps & TextHotspotStyle & {
+    text: string;
+    onLoad?: (texture: Texture) => void;
+    onError?: (error: unknown) => void;
+};
+declare function TextHotspot({ text, width, height, opacity, fontFamily, fontSize, fontWeight, fontStyle, color, background, backgroundOpacity, padding, align, verticalAlign, lineHeight, whiteSpace, borderRadius, stroke, strokeWidth, onLoad, onError, ...anchorProps }: TextHotspotProps): react.JSX.Element;
+
+type IframePointerPolicy = "hotspot" | "content";
+type IframeHotspotProps = HotspotCommonProps & {
+    src: string;
+    /** Accessible iframe title. Falls back to ariaLabel. */
+    title?: string;
+    sandbox?: string;
+    allow?: string;
+    referrerPolicy?: IframeHTMLAttributes<HTMLIFrameElement>["referrerPolicy"];
+    loading?: "eager" | "lazy";
+    /**
+     * `hotspot` lets panorama pointer events hit the WebGL plane.
+     * `content` makes the embedded page interactive.
+     */
+    pointerPolicy?: IframePointerPolicy;
+    background?: string;
+    onLoad?: () => void;
+    onError?: (error: unknown) => void;
+};
+declare function IframeHotspot({ src, title, sandbox, allow, referrerPolicy, loading, pointerPolicy, background, opacity, width, height, onLoad, onError, ...anchorProps }: IframeHotspotProps): react.JSX.Element;
+
 declare function Tile({ baseUrl, multires, previewUrl, previewFaceOrder, urlTemplate, resolveTileUrl, maxTextureMemoryMb, maxConcurrentLoads, retryCount, loadMode, visible, onReady, onPreviewError, onLoadProgress, onTileError, onLevelChange, }: TileProps): react.JSX.Element;
 
 declare function normalizePanoYaw(yaw: number): number;
@@ -452,6 +941,8 @@ declare function normalizePanoPosition(position: HotspotPosition): HotspotPositi
 declare function panoPositionToVector3(position: HotspotPosition, radius?: number): Vector3;
 declare function vector3ToPanoPosition(vector: Pick<Vector3, "x" | "y" | "z">): HotspotPosition;
 
+declare const DEFAULT_HOTSPOT_TOOLTIP_OFFSET = 12;
+
 /** Shared serializable fields for every saved hotspot definition. */
 type HotspotDefinitionBase = {
     id: string;
@@ -459,7 +950,13 @@ type HotspotDefinitionBase = {
     label?: string;
     visible?: boolean;
     interactive?: boolean;
+    /** Canvas cursor while this hotspot is hovered. */
+    cursor?: CSSProperties["cursor"];
     renderOrder?: number;
+    tooltip?: string | HotspotTooltipContent;
+    tooltipTrigger?: HotspotTooltipTrigger;
+    tooltipPlacement?: HotspotTooltipPlacement;
+    tooltipOffset?: number;
 };
 /** Shared serializable fields for a hotspot anchored at one yaw/pitch point. */
 type PointHotspotDefinitionBase = HotspotDefinitionBase & {
@@ -503,6 +1000,21 @@ type VideoHotspotDefinition = PointHotspotDefinitionBase & {
     preload?: "none" | "metadata" | "auto";
     crossOrigin?: "" | "anonymous" | "use-credentials";
 };
+type TextHotspotDefinition = PointHotspotDefinitionBase & TextHotspotStyle & {
+    type: "text";
+    text: string;
+};
+type IframeHotspotDefinition = PointHotspotDefinitionBase & {
+    type: "iframe";
+    src: string;
+    title?: string;
+    sandbox?: string;
+    allow?: string;
+    referrerPolicy?: string;
+    loading?: "eager" | "lazy";
+    pointerPolicy?: IframePointerPolicy;
+    background?: string;
+};
 type PolygonHotspotDefinition = HotspotDefinitionBase & {
     type: "polygon";
     vertices: HotspotPosition[];
@@ -512,7 +1024,7 @@ type PolygonHotspotDefinition = HotspotDefinitionBase & {
     strokeWidth?: number;
     strokeOpacity?: number;
 };
-/** An open path. This extends the original five hotspot categories. */
+/** An open path. This extends the original point and polygon hotspot categories. */
 type PolylineHotspotDefinition = HotspotDefinitionBase & {
     type: "polyline";
     vertices: HotspotPosition[];
@@ -520,8 +1032,8 @@ type PolylineHotspotDefinition = HotspotDefinitionBase & {
     strokeWidth?: number;
     strokeOpacity?: number;
 };
-type PointHotspotDefinition = ImageHotspotDefinition | GraphicHotspotDefinition | SequenceHotspotDefinition | VideoHotspotDefinition;
+type PointHotspotDefinition = ImageHotspotDefinition | GraphicHotspotDefinition | SequenceHotspotDefinition | VideoHotspotDefinition | TextHotspotDefinition | IframeHotspotDefinition;
 /** A serializable, discriminated hotspot collection item. */
 type HotspotDefinition = PointHotspotDefinition | PolygonHotspotDefinition | PolylineHotspotDefinition;
 
-export { AutoRotate, type AutoRotateProps, type CircleGraphic, type CubeFaceCode, type GraphicDefinition, GraphicHotspot, type GraphicHotspotDefinition, type GraphicHotspotProps, type HotspotCommonProps, type HotspotDefinition, type HotspotDefinitionBase, type HotspotDragEvent, type HotspotInputSource, type HotspotInteractionEvent, type HotspotMode, type HotspotPosition, type HotspotScaleMode, ImageHotspot, type ImageHotspotDefinition, type ImageHotspotProps, MAX_HOTSPOT_PITCH, PanoView, type PanoViewHandle, type PanoViewProps, type PanoViewState, type PanoramaControlsOptions, type PanoramaPointerEvent, type PanoramaScene, PanoramaScenes, type PanoramaScenesProps, type PanoramaTransition, type PanoramaTransitionEndEvent, type PanoramaTransitionErrorEvent, type PanoramaTransitionPreset, 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 RectangleGraphic, type RingGraphic, type SequenceFrameDirection, type SequenceFrameEvent, SequenceHotspot, type SequenceHotspotDefinition, type SequenceHotspotErrorEvent, type SequenceHotspotProps, type SequenceLoadProgress, type SequencePlaybackState, type SetPanoViewOptions, Sphere, type SpherePanoramaScene, type SphereProps, type SvgGraphic, type SvgPathGraphic, Tile, type TileAddress, type TileLoadError, type TileLoadProgress, type TileMultiresConfig, type TilePanoramaScene, type TileProps, VideoHotspot, type VideoHotspotDefinition, type VideoHotspotErrorEvent, type VideoHotspotProps, type VideoPlaybackState, clampPanoPitch, normalizePanoPosition, normalizePanoYaw, panoPositionToVector3, unwrapPolygonVertices, validatePolygonVertices, validatePolylineVertices, vector3ToPanoPosition };
+export { type ArrowGraphic, AutoRotate, type AutoRotateProps, type CircleGraphic, type CubeFaceCode, DEFAULT_HOTSPOT_TOOLTIP_OFFSET, DEFAULT_PANO_CURSORS, type DiamondGraphic, type GraphicDefinition, GraphicHotspot, type GraphicHotspotDefinition, type GraphicHotspotProps, type HotspotCommonProps, type HotspotDefinition, type HotspotDefinitionBase, type HotspotDragEvent, type HotspotInputSource, type HotspotInteractionEvent, type HotspotMode, type HotspotPosition, type HotspotScaleMode, type HotspotTooltipContent, type HotspotTooltipPlacement, type HotspotTooltipTrigger, IframeHotspot, type IframeHotspotDefinition, type IframeHotspotProps, type IframePointerPolicy, ImageHotspot, type ImageHotspotDefinition, type ImageHotspotProps, type KeyboardControlAction, type KeyboardControlKeys, KeyboardControls, type KeyboardControlsProps, MAX_HOTSPOT_PITCH, MIN_PANO_CONTEXT_MENU_BACKGROUND_OPACITY, type MouseControlButton, MouseControls, type MouseControlsOptions, type MouseControlsProps, 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, type PanoEventBus, type PanoEventListener, type PanoEventMap, type PanoEventType, PanoEvents, type PanoEventsProps, type PanoResizeEvent, 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 RectangleGraphic, type RingGraphic, type Scene, type SceneTransition, type SceneTransitionEndEvent, type SceneTransitionErrorEvent, type SceneTransitionPreset, Scenes, type ScenesProps, type SequenceFrameDirection, type SequenceFrameEvent, SequenceHotspot, type SequenceHotspotDefinition, type SequenceHotspotErrorEvent, type SequenceHotspotProps, type SequenceLoadProgress, type SequencePlaybackState, type SetPanoViewerOptions, Sphere, type SphereProps, type SphereScene, 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, VideoHotspot, type VideoHotspotDefinition, type VideoHotspotErrorEvent, type VideoHotspotProps, type VideoPlaybackState, type ViewInteractionEvent, type ViewInteractionSource, clampPanoPitch, composePanoContextMenuItems, createDefaultPanoContextMenuItems, createPanoContextMenuPresets, cycleSceneId, normalizePanoPosition, normalizePanoYaw, panoPositionToVector3, resolvePanoContextMenuEntries, unwrapPolygonVertices, usePanoEvents, validatePolygonVertices, validatePolylineVertices, vector3ToPanoPosition };