@ericchen1990/pano-view 0.1.6 → 1.0.0

package/README.md

@@ -15,32 +15,134 @@ compatible with that tile output format but is not affiliated with krpano.
 ## Install
 
 ```bash
-npm install @ericchen1990/pano-view react react-dom three @react-three/fiber
+npm install @ericchen1990/pano-view
 ```
 
-React 19, React DOM 19, `@react-three/fiber` 9, and Three.js are peer dependencies.
+React 19, React DOM 19, Three.js, `@react-three/fiber` 9, and `@react-three/drei` 10 are peer dependencies. npm 7+ and pnpm install them automatically; they must be a single copy in the host app.
 
-## Sphere panorama
+## Exported components
 
-`PanoView` owns the canvas, perspective camera, and controls. Give its container an explicit size and place one panorama source inside it.
+### Viewer
+
+- [`PanoViewer`](#panoviewer) — canvas shell, camera, default controls, and imperative view API
+- [`Sphere`](#sphere) — single 2:1 equirectangular image
+- [`Tile`](#tile) — krpano-style multires cube tiles
+- [`Scenes`](#scenes) — controlled multi-scene transitions
+
+### Controls
+
+- [`MouseControls`](#mousecontrols) — drag look and wheel zoom
+- [`TouchControls`](#touchcontrols) — one-finger drag and pinch zoom
+- [`KeyboardControls`](#keyboardcontrols) — arrow-key look, FOV, and scene cycling
+- [`AutoRotate`](#autorotate) — automatic yaw rotation
+
+### Events and chrome
+
+- [`PanoEvents`](#panoevents) — viewer-level lifecycle and interaction callbacks
+- [`PanoContextMenu`](#panocontextmenu) — right-click reset / fullscreen menu
+
+### Hotspots
+
+- [`ImageHotspot`](#imagehotspot) — image texture at a spherical position
+- [`GraphicHotspot`](#graphichotspot) — built-in shapes or SVG at a position
+- [`SequenceHotspot`](#sequencehotspot) — sprite-sheet animation
+- [`VideoHotspot`](#videohotspot) — HTML video texture
+- [`TextHotspot`](#texthotspot) — rasterized plain text at a position
+- [`IframeHotspot`](#iframehotspot) — embedded document overlay at a position
+- [`PolygonHotspot`](#polygonhotspot) — closed spherical area
+- [`PolylineHotspot`](#polylinehotspot) — open spherical path
+
+### Hooks and helpers
+
+- `usePanoEvents` — subscribe to viewer events inside a custom child ([`PanoEvents`](#panoevents))
+- Coordinate helpers — `normalizePanoPosition`, `normalizePanoYaw`, `clampPanoPitch`, `panoPositionToVector3`, `vector3ToPanoPosition` ([Panorama coordinate events](#panorama-coordinate-events))
+- `cycleSceneId` — wrap previous/next scene ids ([`KeyboardControls`](#keyboardcontrols))
+- Context menu helpers — `createPanoContextMenuPresets`, `composePanoContextMenuItems`, and related APIs ([`PanoContextMenu`](#panocontextmenu))
+- Polygon / polyline validation — `validatePolygonVertices`, `validatePolylineVertices`, `unwrapPolygonVertices`
+
+## PanoViewer
+
+`PanoViewer` owns the canvas, perspective camera, and controls. Give its container an explicit size and place one panorama source inside it.
+
+Angles are public degrees. Positive yaw looks right and positive pitch looks up.
+
+```tsx
+import { useRef } from "react";
+import {
+  PanoViewer,
+  Sphere,
+  AutoRotate,
+  type PanoViewerHandle,
+} from "@ericchen1990/pano-view";
+
+export function ControlledExample() {
+  const ref = useRef<PanoViewerHandle>(null);
+
+  return (
+    <>
+      <button onClick={() => ref.current?.setView({ yaw: 90, fov: 55 })}>
+        Look right
+      </button>
+      <PanoViewer
+        ref={ref}
+        controls={{
+          inertia: true,
+          rotateDamping: 14,
+          zoomDamping: 16,
+        }}
+        initialView={{ yaw: 0, pitch: 0, fov: 75 }}
+        minFov={30}
+        maxFov={100}
+        onViewChange={(view) => console.log(view)}
+        style={{ height: 560 }}
+      >
+        <AutoRotate enabled speed={18} acceleration={18} startDelay={1_000} />
+        <Sphere src="/panoramas/room.webp" />
+      </PanoViewer>
+    </>
+  );
+}
+```
+
+The handle exposes `getView`, `setView`, `reset`, `startAutoRotate`, `stopAutoRotate`, and `toggleFullscreen`. Mouse, touch, and keyboard input are enabled by default — you do not need to render control components for ordinary viewing. Render `MouseControls`, `TouchControls`, or `KeyboardControls` only to override properties (the child replaces that channel's default instance). Tune shared behaviour through `controls` (`inertia`, `invert`, `bouncingLimits`, `fovSpeed`, `frictionStop`, `rotateDamping`, `zoomDamping`, and top-level `rotateSpeed` / `zoomSpeed`). Disable a channel with `controls.mouse` / `touch` / `keyboard` set to `false`, or pass an options object (including `enabled`) to override defaults without mounting a child. Auto-rotation is off until you render `AutoRotate`. The two auto-rotation handle methods remain supported for compatibility. A default context menu (Reset view / Enter fullscreen) is also mounted — see [`PanoContextMenu`](#panocontextmenu).
+
+Drag and zoom update a target view that the camera follows smoothly. `rotateDamping` and `zoomDamping` control that following speed in seconds^-1 (defaults: `14` and `16` respectively); lower values feel softer, while `0` disables smoothing for that axis. Both values must be non-negative finite numbers. Imperative `setView()` and `reset()` remain immediate.
+
+The canvas cursor defaults to `grab`, becomes `grabbing` while dragging with the mouse, `pointer` over an interactive hotspot, and `move` while dragging a hotspot. Override those values with `cursors` (`default`, `dragging`, `hotspot`, `hotspotDragging`), or pass `cursors={false}` to leave the canvas cursor unchanged. A hotspot may set `cursor` to replace the hover cursor for that hotspot only.
+
+```tsx
+<PanoViewer
+  cursors={{ default: "grab", dragging: "grabbing", hotspot: "pointer" }}
+  style={{ height: 560 }}
+>
+  <ImageHotspot
+    id="door"
+    cursor="zoom-in"
+    position={{ yaw: 24, pitch: -6 }}
+    src="/hotspots/door.webp"
+  />
+</PanoViewer>
+```
+
+## Sphere
+
+`Sphere` expects a 2:1 equirectangular image. Use `yawOffset` when the source's forward direction needs horizontal adjustment.
 
 ```tsx
 "use client";
 
-import { PanoView, Sphere } from "@ericchen1990/pano-view";
+import { PanoViewer, Sphere } from "@ericchen1990/pano-view";
 
 export function SphereExample() {
   return (
-    <PanoView style={{ width: "100%", height: 560 }}>
+    <PanoViewer style={{ width: "100%", height: 560 }}>
       <Sphere src="/panoramas/room.webp" />
-    </PanoView>
+    </PanoViewer>
   );
 }
 ```
 
-`Sphere` expects a 2:1 equirectangular image. Use `yawOffset` when the source's forward direction needs horizontal adjustment.
-
-## Cube Tile panorama
+## Tile
 
 `Tile` renders six inward-facing cube faces and loads only tiles around the current view. The default layout matches krpano-style output:
 
@@ -51,16 +153,16 @@ tiles/{face}/l{level}/{row}/l{level}_{face}_{col}_{row}.webp
 Faces are `f`, `r`, `b`, `l`, `u`, and `d`; rows and columns are 1-based.
 
 ```tsx
-import { PanoView, Tile } from "@ericchen1990/pano-view";
+import { PanoViewer, Tile } from "@ericchen1990/pano-view";
 
 export function TileExample() {
   return (
-    <PanoView style={{ width: "100%", height: 560 }}>
+    <PanoViewer style={{ width: "100%", height: 560 }}>
       <Tile
         baseUrl="https://cdn.example.com/panoramas/room"
         multires="512,500,1000,2000"
       />
-    </PanoView>
+    </PanoViewer>
   );
 }
 ```
@@ -103,9 +205,9 @@ horizontal index and `%00v` produces a three-digit vertical index. The stereo
 `%t` and frame `%f` placeholders are not applicable to `Tile`, which represents
 a single non-stereo cube panorama.
 
-## Scene transitions
+## Scenes
 
-`PanoramaScenes` switches controlled sphere and cube-tile scenes with GPU-only
+`Scenes` switches controlled sphere and cube-tile scenes with GPU-only
 snapshot blending. The target scene loads its sphere image or tile preview first;
 once ready, the current framebuffer becomes a temporary GPU texture, its source
 textures are released, and the target scene blends in. This avoids holding two
@@ -113,12 +215,12 @@ high-resolution tile scenes in WebGL memory at once.
 
 ```tsx
 import {
-  PanoramaScenes,
-  PanoView,
-  type PanoramaScene,
+  Scenes,
+  PanoViewer,
+  type Scene,
 } from "@ericchen1990/pano-view";
 
-const scenes: PanoramaScene[] = [
+const scenes: Scene[] = [
   { id: "lobby", type: "sphere", src: "/panoramas/lobby.webp" },
   {
     id: "terrace",
@@ -128,15 +230,15 @@ const scenes: PanoramaScene[] = [
   },
 ];
 
-<PanoView style={{ height: 560 }}>
-  <PanoramaScenes
+<PanoViewer style={{ height: 560 }}>
+  <Scenes
     scenes={scenes}
     activeSceneId={activeSceneId}
     transition="ellipticZoomOpen"
     renderHotspots={(scene) => <SceneHotspots sceneId={scene.id} />}
     onTransitionError={({ sceneId }) => console.warn("Could not load", sceneId)}
   />
-</PanoView>;
+</PanoViewer>;
 ```
 
 Available presets are `none`, `crossfade`, `zoom`, `blackout`, `whiteFlash`,
@@ -147,51 +249,104 @@ Available presets are `none`, `crossfade`, `zoom`, `blackout`, `whiteFlash`,
 While a transition runs, panorama drag/zoom input is locked and
 `renderHotspots` is hidden. New `activeSceneId` values supersede a target that
 is still being prepared. `maxTextureMemoryMb` and `maxConcurrentTileLoads`
-apply to the whole `PanoramaScenes` viewer rather than to each tile scene.
+apply to the whole `Scenes` viewer rather than to each tile scene.
 
-## Controls and imperative API
+## AutoRotate
 
-Angles are public degrees. Positive yaw looks right and positive pitch looks up.
+Auto-rotation is off by default. Render `AutoRotate` inside `PanoViewer` to enable it and keep rotation configuration separate from user-input controls. `speed` is measured in degrees per second; use a negative value to rotate left. `acceleration` is measured in degrees per second squared and smoothly ramps from zero to `speed` (default: `18`, so the default speed takes one second to reach). Set it to `0` for an immediate fixed speed. `startDelay` is measured in milliseconds from when `enabled` becomes true. While the user is dragging, or while drag inertia is still settling, rotation pauses and resumes from zero speed automatically.
 
 ```tsx
-import { useRef } from "react";
+<PanoViewer style={{ height: 560 }}>
+  <AutoRotate enabled speed={12} acceleration={6} startDelay={2_000} />
+  <Sphere src="/panoramas/room.webp" />
+</PanoViewer>
+```
+
+## Mouse, touch, and keyboard controls
+
+`PanoViewer` enables `MouseControls`, `TouchControls`, and `KeyboardControls` by default. Configure shared options through `controls`; render a control component only to override that channel's properties. A child instance replaces the default — you do not need to set the channel to `false` first. Set `controls.mouse` / `touch` / `keyboard` to `false` to turn a channel off.
+
+```tsx
+<PanoViewer
+  controls={{
+    invert: false,
+    bouncingLimits: false,
+    mouse: { zoomSpeed: 0.12, wheel: true, buttons: ["left"] },
+    touch: { pinchZoom: true },
+    keyboard: { enabled: true, rotateSpeed: 90 },
+  }}
+  style={{ height: 560 }}
+>
+  <Sphere src="/panoramas/room.webp" />
+</PanoViewer>
+```
+
+**Mouse** (pointer types `mouse` / `pen`): drag look and optional wheel zoom. Defaults: `rotateSpeed` `0.35`, `zoomSpeed` `0.08`, `wheel` `true`, `buttons` `["left"]`.
+
+### MouseControls
+
+See the defaults above. Override through `controls.mouse` or by rendering `<MouseControls />` as a child.
+
+### TouchControls
+
+One-finger drag and optional two-finger pinch zoom (`pinchZoom`, default `true`). Override through `controls.touch` or by rendering `<TouchControls />` as a child.
+
+### KeyboardControls
+
+Hold arrows (or custom bindings) for continuous look / FOV; `0` resets; optional scene bindings. Defaults: `rotateSpeed` `60`, `zoomSpeed` `30`, `shiftMultiplier` `3`. Set `invert` to flip up/down only. Override through `controls.keyboard` or by rendering `<KeyboardControls />` as a child.
+
+Shared all-mode options on `controls`: `enabled`, `invert` (drag direction for mouse/touch), `bouncingLimits`, `fovSpeed`, `frictionStop` (default `0.01`), plus existing damping / inertia.
+
+### Overriding a control channel
+
+Render the component with the props you need. The default instance for that channel is skipped:
+
+```tsx
+import { useState } from "react";
 import {
-  PanoView,
-  Sphere,
-  AutoRotate,
-  type PanoViewHandle,
+  KeyboardControls,
+  Scenes,
+  PanoViewer,
+  cycleSceneId,
+  type Scene,
 } from "@ericchen1990/pano-view";
 
-export function ControlledExample() {
-  const ref = useRef<PanoViewHandle>(null);
+export function KeyboardExample({ scenes }: { scenes: Scene[] }) {
+  const [activeSceneId, setActiveSceneId] = useState(scenes[0]!.id);
 
   return (
-    <>
-      <button onClick={() => ref.current?.setView({ yaw: 90, fov: 55 })}>
-        Look right
-      </button>
-      <PanoView
-        ref={ref}
-        controls={{
-          inertia: true,
-          rotateDamping: 14,
-          zoomDamping: 16,
+    <PanoViewer style={{ height: 560 }}>
+      <KeyboardControls
+        keys={{
+          left: ["ArrowLeft", "a"],
+          right: ["ArrowRight", "d"],
+          up: ["ArrowUp", "w"],
+          down: ["ArrowDown", "s"],
+          zoomIn: ["=", "+"],
+          zoomOut: ["-", "_"],
+          previousScene: ["[", "PageUp"],
+          nextScene: ["]", "PageDown"],
         }}
-        initialView={{ yaw: 0, pitch: 0, fov: 75 }}
-        minFov={30}
-        maxFov={100}
-        onViewChange={(view) => console.log(view)}
-        style={{ height: 560 }}
-      >
-        <AutoRotate enabled speed={18} acceleration={18} startDelay={1_000} />
-        <Sphere src="/panoramas/room.webp" />
-      </PanoView>
-    </>
+        rotateSpeed={60}
+        zoomSpeed={30}
+        onPreviousScene={() => {
+          const next = cycleSceneId(scenes, activeSceneId, -1);
+          if (next) setActiveSceneId(next);
+        }}
+        onNextScene={() => {
+          const next = cycleSceneId(scenes, activeSceneId, 1);
+          if (next) setActiveSceneId(next);
+        }}
+      />
+      <Scenes scenes={scenes} activeSceneId={activeSceneId} />
+    </PanoViewer>
   );
 }
 ```
 
-The handle exposes `getView`, `setView`, `reset`, `startAutoRotate`, `stopAutoRotate`, and `toggleFullscreen`. Built-in input supports pointer drag, touch drag, pinch, wheel, arrow keys, `+/-`, and `0` to reset. The two auto-rotation handle methods remain supported for compatibility; prefer rendering `AutoRotate` for new code.
+Hold movement and zoom keys for continuous motion in degrees per second (`rotateSpeed` / `zoomSpeed`). Hold Shift to multiply those rates (`shiftMultiplier`, default `3`). Scene and reset bindings fire once per press. The canvas must be focused to receive keys (click the viewer first).
+
+Default bindings: arrows for look, `+/-` for FOV, `0` for reset, plus `[`/`PageUp` and `]`/`PageDown` for previous/next scene when callbacks are provided. The same child-override pattern works with `MouseControls` and `TouchControls`. Set `controls.mouse={false}` / `controls.touch={false}` / `controls.keyboard={false}` only when you want that channel off.
 
 ## Panorama coordinate events
 
@@ -201,7 +356,7 @@ convention as the camera: positive yaw looks right and positive pitch looks up.
 
 ```tsx
 import {
-  PanoView,
+  PanoViewer,
   Sphere,
   panoPositionToVector3,
   type HotspotPosition,
@@ -214,14 +369,14 @@ export function PlacementExample() {
   };
 
   return (
-    <PanoView
+    <PanoViewer
       onPanoramaClick={({ position }) => place(position)}
       onPanoramaDoubleClick={({ position }) => console.log("double", position)}
       onPanoramaPointerMove={({ position }) => console.log("move", position)}
       style={{ height: 560 }}
     >
       <Sphere src="/panoramas/room.webp" />
-    </PanoView>
+    </PanoViewer>
   );
 }
 ```
@@ -231,6 +386,166 @@ export function PlacementExample() {
 is normalized to `[-180, 180)`. Pitch is clamped to `[-90, 90]`; at either
 pole, yaw is normalized to `0` because it does not identify a unique point.
 
+## PanoEvents
+
+`PanoEvents` is the React counterpart to krpano's global `<events>` element.
+Render one or more instances inside `PanoViewer` to subscribe to viewer-level
+lifecycle and interaction callbacks. Multiple instances coexist (like named
+krpano events); each tracks its own `idleTime`. For composition inside a custom
+child, use `usePanoEvents` instead.
+
+### usePanoEvents
+
+```tsx
+import {
+  AutoRotate,
+  PanoEvents,
+  PanoViewer,
+  Sphere,
+} from "@ericchen1990/pano-view";
+
+<PanoViewer style={{ height: 560 }}>
+  <PanoEvents
+    idleTime={3000}
+    onIdle={() => console.log("idle")}
+    onIdleEnd={() => console.log("active again")}
+    onViewSettled={(view) => console.log("settled", view)}
+    onViewInteractionStart={({ source }) => console.log("drag", source)}
+    onClick={({ position }) => console.log("pano click", position)}
+    onEnterFullscreen={() => console.log("fullscreen")}
+    onAutoRotateOneRound={() => console.log("full turn")}
+  />
+  <AutoRotate enabled />
+  <Sphere src="/panoramas/room.webp" />
+</PanoViewer>;
+```
+
+Supported callbacks (krpano names in parentheses where applicable):
+
+- View: `onViewChange` (`onviewchange`), `onViewSettled`, `onViewInteractionStart` / `onViewInteractionEnd`
+- Pointer on the panorama shell (not hotspots): `onClick`, `onDoubleClick`, `onPointerDown`, `onPointerUp`, `onPointerMove`, `onContextMenu`
+- `onWheel` — mouse wheel only; touch pinch does not synthesize a wheel event
+- Idle: `onIdle` / `onIdleEnd` with per-instance `idleTime` (ms, default `2000`)
+- Fullscreen: `onEnterFullscreen` / `onExitFullscreen`
+- `onResize` — canvas content-box size via `ResizeObserver`
+- Auto-rotate: `onAutoRotateStart` / `onAutoRotateStop` / `onAutoRotateOneRound`
+
+`PanoViewer`'s existing `onViewChange` / `onPanoramaClick` / `onPanoramaDoubleClick` /
+`onPanoramaPointerMove` props remain supported and share the same event bus.
+
+Resource loading and scene blending stay on their owners: use `Sphere` /
+`Tile` `onLoad` / `onError` / `onLoadProgress`, and `Scenes`
+`onTransitionEnd` / `onTransitionError`. This package does not mirror krpano
+xml/VR/gyro/frame-render events.
+
+## PanoContextMenu
+
+`PanoViewer` mounts a default context menu that replaces the browser menu on
+right-click. Default items: **Reset view** and **Enter fullscreen** / **Exit
+fullscreen** (label and icon follow the current fullscreen state), with a
+separator between them.
+
+```tsx
+<PanoViewer style={{ height: 560 }}>
+  <Sphere src="/panoramas/room.webp" />
+</PanoViewer>
+```
+
+Disable the default menu (restore the browser menu, or mount your own):
+
+```tsx
+<PanoViewer contextMenu={false}>
+  <Sphere src="/panoramas/room.webp" />
+</PanoViewer>
+```
+
+Tune appearance while keeping the default items:
+
+```tsx
+<PanoViewer contextMenu={{ appearance: { opacity: 0.92, borderRadius: 8 } }}>
+  <Sphere src="/panoramas/room.webp" />
+</PanoViewer>
+```
+
+### Adding items without rebuilding defaults
+
+Use `append` or `prepend` to keep the built-in Reset / Fullscreen entries and
+only add your own:
+
+```tsx
+<PanoViewer
+  contextMenu={{
+    append: [
+      "separator",
+      {
+        id: "copy",
+        label: "Copy yaw / pitch",
+        onSelect: ({ position }) => {
+          void navigator.clipboard.writeText(
+            `${position.yaw.toFixed(1)}, ${position.pitch.toFixed(1)}`,
+          );
+        },
+      },
+    ],
+  }}
+  style={{ height: 560 }}
+>
+  <Sphere src="/panoramas/room.webp" />
+</PanoViewer>
+```
+
+### Built-in presets
+
+When you need a custom order, reuse built-in presets by id instead of
+reimplementing fullscreen enter/exit state:
+
+- `"resetView"` — resets the view
+- `"fullscreen"` — Enter / Exit fullscreen with the matching icon
+- `"separator"` — a horizontal rule
+
+```tsx
+<PanoViewer
+  contextMenu={{
+    items: [
+      "resetView",
+      "separator",
+      {
+        id: "copy",
+        label: "Copy yaw / pitch",
+        onSelect: ({ position }) => {
+          void navigator.clipboard.writeText(
+            `${position.yaw.toFixed(1)}, ${position.pitch.toFixed(1)}`,
+          );
+        },
+      },
+      "separator",
+      "fullscreen",
+    ],
+  }}
+  style={{ height: 560 }}
+>
+  <Sphere src="/panoramas/room.webp" />
+</PanoViewer>
+```
+
+Override presentation on a preset with `{ preset: "fullscreen", label: "…" }`.
+For fully manual assembly outside the prop (for example a custom
+`PanoContextMenu` child), call `createPanoContextMenuPresets({ reset,
+toggleFullscreen, isFullscreen })` and use `.resetView` / `.fullscreen` /
+`.defaults`.
+
+Concrete items may use an `icon` React node or an `image` URL. Separators
+always come from the `"separator"` preset. Appearance covers background, text
+color, border, radius, shadow, background-only `opacity` (clamped from
+`MIN_PANO_CONTEXT_MENU_BACKGROUND_OPACITY` / `0.4` to `1`; labels and icons
+stay opaque), hover/disabled colors, and icon size. For an explicit translucent
+fill without using `opacity`, you can still pass `background: "rgba(...)"`.
+
+For a fully custom DOM menu, set `contextMenu={false}` and render
+`PanoContextMenu` as a child. Do not mount both the default menu and a child
+`PanoContextMenu` at once. Avoid combining the context menu with
+`controls.mouse.buttons: ["right"]` — both claim the right mouse button.
+
 ## Shared hotspot contract and saved definitions
 
 Every hotspot has an `id`, optional `visible`, `interactive`, `renderOrder`,
@@ -238,6 +553,8 @@ and semantic interaction callbacks. Point hotspots additionally use a
 controlled `position`, angular `width`/`height`, hotspot mode, and the zoom
 options described below. `interactive={false}` keeps a hotspot visible while
 letting a drawing tool receive the panorama pointer events beneath it.
+Interactive hotspots set the canvas cursor to `pointer` while hovered, or to
+the hotspot's `cursor` prop when that is set.
 
 `onClick` and `onHoverChange` receive a position and input source (`"pointer"`
 or `"keyboard"`). Point hotspots can use `draggable`, `onDragStart`,
@@ -245,9 +562,43 @@ or `"keyboard"`). Point hotspots can use `draggable`, `onDragStart`,
 back to its state. Polygon and polyline hotspots report the corresponding
 controlled `vertices` through `onVerticesChange`.
 
+Every hotspot can show a DOM tooltip at its anchor. Pass a string or
+`{ text?, image?, imageAlt? }` as `tooltip`. The default `tooltipTrigger` is
+`"always"`: if content is present and the hotspot is visible, the bubble stays
+on screen. Clicking the hotspot does not toggle it. Optional
+`tooltipTrigger="hover"` shows the bubble on pointer hover or keyboard focus;
+`"click"` pins it until the hotspot is clicked again or the empty panorama is
+clicked. Hover and click triggers need `interactive`.
+
+`tooltipPlacement` is `"top"` (default), `"bottom"`, `"left"`, or `"right"`.
+The bubble sits outside that edge of the hotspot. `tooltipOffset` is the
+screen-space gap in CSS pixels (default `12` / `DEFAULT_HOTSPOT_TOOLTIP_OFFSET`).
+
+```tsx
+<ImageHotspot
+  id="gallery"
+  ariaLabel="Open gallery"
+  position={{ yaw: 28, pitch: -4 }}
+  src="/hotspots/gallery.webp"
+  tooltip={{ text: "Courtyard gallery", image: "/hotspots/gallery-thumb.webp" }}
+  tooltipPlacement="top"
+  tooltipOffset={16}
+/>
+<GraphicHotspot
+  id="marker"
+  ariaLabel="Signal"
+  position={{ yaw: -18, pitch: 9 }}
+  graphic={{ kind: "ring" }}
+  tooltip="Hover for details"
+  tooltipTrigger="hover"
+  tooltipPlacement="right"
+/>
+```
+
 For persistence or a host-owned editor, use the exported discriminated
-`HotspotDefinition` union. It contains the original five categories plus the
-open `polyline` extension:
+`HotspotDefinition` union. Adding a variant is a TypeScript breaking change for
+exhaustive switches; handle `text` and `iframe` alongside the existing point
+and path categories:
 
 ```ts
 import type { HotspotDefinition } from "@ericchen1990/pano-view";
@@ -257,6 +608,8 @@ const hotspots: HotspotDefinition[] = [
   { type: "graphic", id: "marker", position: { yaw: -18, pitch: 9 }, graphic: { kind: "ring" } },
   { type: "sequence", id: "pulse", position: { yaw: -42, pitch: -7 }, src: "/hotspots/pulse.png", frameCount: 20 },
   { type: "video", id: "clip", position: { yaw: 48, pitch: 6 }, src: "/hotspots/clip.webm" },
+  { type: "text", id: "caption", position: { yaw: 0, pitch: -16 }, text: "Courtyard overlook" },
+  { type: "iframe", id: "guide", position: { yaw: -62, pitch: 4 }, src: "/hotspots/embed.html" },
   { type: "polygon", id: "zone", vertices: [{ yaw: 12, pitch: 4 }, { yaw: 22, pitch: 4 }, { yaw: 18, pitch: 14 }] },
   { type: "polyline", id: "route", vertices: [{ yaw: -8, pitch: 1 }, { yaw: 4, pitch: 8 }] },
 ];
@@ -266,15 +619,15 @@ Definitions intentionally contain data only. Render them with a switch in the
 host, where application-specific click actions, controlled media state, and
 error reporting belong.
 
-## Image and graphic hotspots
+## ImageHotspot
 
 `ImageHotspot` renders an image at a controlled spherical position. Dimensions
 are angular degrees, so they remain independent of the canvas resolution.
 
 ```tsx
-import { ImageHotspot, PanoView, Sphere } from "@ericchen1990/pano-view";
+import { ImageHotspot, PanoViewer, Sphere } from "@ericchen1990/pano-view";
 
-<PanoView style={{ height: 560 }}>
+<PanoViewer style={{ height: 560 }}>
   <Sphere src="/panoramas/room.webp" />
   <ImageHotspot
     id="gallery"
@@ -286,13 +639,23 @@ import { ImageHotspot, PanoView, Sphere } from "@ericchen1990/pano-view";
     src="/hotspots/gallery.webp"
     onClick={({ position }) => console.log("gallery", position)}
   />
-</PanoView>;
+</PanoViewer>;
 ```
 
-`GraphicHotspot` accepts built-in `circle`, `rectangle`, and `ring` graphics,
-an SVG URL, or safe SVG path data with an explicit viewBox. Built-in graphics
-support `fill`, `stroke`, and `strokeWidth`; rectangles also support
-`cornerRadius` and rings support `innerRadius`.
+Set `draggable` and update the controlled position from `onPositionChange` to
+move a selected hotspot. Clickable hotspots need `ariaLabel`: PanoViewer creates
+an internal semantic control for Tab, Enter, and Space activation, with a
+visible WebGL focus outline.
+
+`ImageHotspot` calls `onLoad(texture)` and `onError(error)`.
+
+## GraphicHotspot
+
+`GraphicHotspot` accepts built-in `circle`, `triangle`, `diamond`, `star`,
+`arrow`, `rectangle`, and `ring` graphics, an SVG URL, or safe SVG path data
+with an explicit viewBox. Built-in graphics support `fill`, `stroke`, and
+`strokeWidth`; rectangles support a relative `cornerRadius` from `0` to `0.5`,
+and rings support `innerRadius`.
 
 ```tsx
 import { GraphicHotspot } from "@ericchen1990/pano-view";
@@ -314,13 +677,33 @@ import { GraphicHotspot } from "@ericchen1990/pano-view";
 />
 ```
 
-Set `draggable` and update the controlled position from `onPositionChange` to
-move a selected hotspot. Clickable hotspots need `ariaLabel`: PanoView creates
-an internal semantic control for Tab, Enter, and Space activation, with a
-visible WebGL focus outline.
+Triangle, diamond, star, and arrow graphics use the same paint properties. The
+triangle and arrow point upward at `rotation={0}`; use the hotspot's `rotation`
+property to orient them in another direction.
 
-`ImageHotspot` calls `onLoad(texture)` and `onError(error)`. `GraphicHotspot`
-uses the same callbacks. Built-in paths are rasterized locally; only an SVG URL
+```tsx
+<GraphicHotspot
+  id="direction"
+  ariaLabel="Open next scene"
+  position={{ yaw: 8, pitch: 2 }}
+  rotation={45}
+  width={8}
+  height={8}
+  graphic={{
+    kind: "arrow",
+    fill: "#df6b42",
+    stroke: "#f5fbfc",
+    strokeWidth: 8,
+  }}
+/>
+```
+
+`cornerRadius` is relative to the rendered graphic's shorter side: `0` keeps
+square corners and `0.5` produces the maximum rounded corners. This replaces
+the previous Canvas-texture pixel interpretation.
+
+`GraphicHotspot` uses the same `onLoad(texture)` and `onError(error)` callbacks
+as `ImageHotspot`. Built-in paths are rasterized locally; only an SVG URL
 or SVG `path` data plus an explicit `viewBox` is accepted, never arbitrary SVG
 markup.
 
@@ -337,9 +720,10 @@ placement properties:
 - `scaleMode="fov"` (default) lets a hotspot grow when the user zooms in.
   `scaleMode="fixed"` compensates for FOV changes and keeps its screen size
   close to the size at `referenceFov` (default `75`).
-- `rotation` rotates the hotspot around its own normal in degrees. `scale`
-  applies an overall positive multiplier to its angular width and height and
-  defaults to `1`.
+- `rotation` rotates the hotspot around its own normal in degrees; positive
+  values rotate clockwise and negative values rotate counterclockwise.
+  `scale` applies an overall positive multiplier to its angular width and
+  height and defaults to `1`.
 
 ```tsx
 <ImageHotspot
@@ -357,7 +741,7 @@ placement properties:
 />
 ```
 
-## Polygon hotspots
+## PolygonHotspot
 
 `PolygonHotspot` renders a local spherical area from three or more controlled
 yaw/pitch vertices. Concave polygons and the `-180°/180°` seam are supported.
@@ -396,7 +780,7 @@ Set `fillOpacity={0}` for a closed outline-only polygon. The fill and outline
 share the same spherical edge sampling, so there is no intentional seam
 between them.
 
-## Polyline hotspots
+## PolylineHotspot
 
 `PolylineHotspot` is an open path of at least two yaw/pitch vertices. It uses
 the same CSS-pixel `strokeWidth`, visibility, semantic interaction, controlled
@@ -420,7 +804,7 @@ import { PolylineHotspot } from "@ericchen1990/pano-view";
 
 `onInvalid` reports the only invalid runtime shape: fewer than two vertices.
 
-## Sequence and video hotspots
+## SequenceHotspot
 
 `SequenceHotspot` animates a sprite sheet: one image containing equally sized
 frames in a vertical or horizontal strip. This matches the common krpano
@@ -448,6 +832,12 @@ import { SequenceHotspot } from "@ericchen1990/pano-view";
 />;
 ```
 
+Sequence loading uses `onLoadProgress` and `onError`. The component does not
+change `playing` by itself: update that prop in response to your UI, click
+handler, `onEnded`, or playback error.
+
+## VideoHotspot
+
 `VideoHotspot` uses an `HTMLVideoElement` and `VideoTexture`. Its `playing`
 prop is likewise controlled: toggle it from your click handler or application
 state. On source change or unmount, the element is paused and its texture is
@@ -481,24 +871,72 @@ Browsers can reject unmuted or otherwise non-gesture playback. In that case
 the browser error; retain control of `playing` in the host and offer an
 explicit user action.
 
-Sequence loading uses `onLoadProgress` and `onError`; video reports media and
-poster failures through `onError`. Neither component changes `playing` by
-itself: update that prop in response to your UI, click handler, `onEnded`, or
-playback error. This keeps source changes, unmounts, and React StrictMode
-lifecycles deterministic.
+Video reports media and poster failures through `onError`. Like
+`SequenceHotspot`, it does not change `playing` by itself. This keeps source
+changes, unmounts, and React StrictMode lifecycles deterministic.
 
-## Automatic rotation
+## TextHotspot
 
-Render `AutoRotate` inside `PanoView` to keep rotation configuration separate from user-input controls. `speed` is measured in degrees per second; use a negative value to rotate left. `acceleration` is measured in degrees per second squared and smoothly ramps from zero to `speed` (default: `18`, so the default speed takes one second to reach). Set it to `0` for an immediate fixed speed. `startDelay` is measured in milliseconds from when `enabled` becomes true. While the user is dragging, or while drag inertia is still settling, rotation pauses and resumes from zero speed automatically.
+`TextHotspot` rasterizes plain text onto a canvas texture. It does not accept
+HTML or Markdown. `\n` is a hard line break; `whiteSpace="normal"` (default)
+wraps words to the hotspot's angular width. Dimensions stay in degrees like
+the other point hotspots. `fontSize`, `padding`, and `borderRadius` are
+fractions of the texture, so they scale with `width` / `height`.
 
 ```tsx
-<PanoView style={{ height: 560 }}>
-  <AutoRotate enabled speed={12} acceleration={6} startDelay={2_000} />
-  <Sphere src="/panoramas/room.webp" />
-</PanoView>
+import { TextHotspot } from "@ericchen1990/pano-view";
+
+<TextHotspot
+  id="caption"
+  ariaLabel="Courtyard overlook"
+  position={{ yaw: 0, pitch: -16 }}
+  width={16}
+  height={6}
+  mode="billboard"
+  scaleMode="fixed"
+  text={"Courtyard overlook\nNorth terrace"}
+  align="center"
+  verticalAlign="middle"
+  fontSize={0.18}
+  color="#f8fafc"
+  background="#111827"
+  backgroundOpacity={0.72}
+/>;
 ```
 
-Drag and zoom update a target view that the camera follows smoothly. `rotateDamping` and `zoomDamping` control that following speed in seconds^-1 (defaults: `14` and `16` respectively); lower values feel softer, while `0` disables smoothing for that axis. Both values must be non-negative finite numbers. Imperative `setView()` and `reset()` remain immediate.
+Load a custom `fontFamily` on the page before the hotspot paints; canvas text
+uses whatever faces the document already has. `onLoad(texture)` and
+`onError(error)` match `ImageHotspot`.
+
+## IframeHotspot
+
+`IframeHotspot` places an embedded document with `@react-three/drei` `Html`
+`transform`, so it follows the same hotspot mode, rotation, and zoom scaling
+as a texture plane. The iframe is a DOM overlay and is not occluded by the
+panorama shell. There is no `srcdoc` prop.
+
+```tsx
+import { IframeHotspot } from "@ericchen1990/pano-view";
+
+<IframeHotspot
+  id="guide"
+  ariaLabel="Open visitor guide"
+  position={{ yaw: -62, pitch: 4 }}
+  width={18}
+  height={12}
+  mode="billboard"
+  src="/hotspots/embed.html"
+  pointerPolicy="hotspot"
+/>;
+```
+
+`pointerPolicy="hotspot"` (default) sets the iframe to `pointer-events: none`
+so clicks and drags hit the WebGL plane. `"content"` makes the page
+interactive and blocks dragging through the iframe. `sandbox` defaults to
+`allow-scripts allow-popups allow-forms` without `allow-same-origin`.
+`referrerPolicy` defaults to `strict-origin-when-cross-origin`. Prefer a
+same-origin document; many third-party sites send `X-Frame-Options` and will
+not load.
 
 ## Next.js and SSR