@ericchen1990/pano-view 1.0.0 → 2.1.0

package/README.md

@@ -7,10 +7,13 @@ Try the components in the [live playground](https://pano-view-playground.vercel.
 ## krpano-compatible tile output
 
 Use this package when you want a React-native viewer around equirectangular
-images or an existing krpano cube-tile pyramid. `Tile` understands the common
-krpano-style multires directory layout by default, while keeping rendering,
-controls, hotspots, and scene transitions in your React application. It is
-compatible with that tile output format but is not affiliated with krpano.
+images or an existing krpano cube-tile pyramid. Copy the krpano `<cube>` `url`
+and `multires` attributes into `Tile`'s `urlTemplate` and `multires`, and copy
+`<preview url>` into `previewUrl`; krpano's on-disk naming is not the same as
+this package's defaults, so omitting them loads the wrong tiles or preview.
+Rendering, controls, hotspots, and scene transitions stay in your React
+application. This package is compatible with that tile output format but is
+not affiliated with krpano.
 
 ## Install
 
@@ -18,7 +21,25 @@ compatible with that tile output format but is not affiliated with krpano.
 npm install @ericchen1990/pano-view
 ```
 
-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.
+React 19, React DOM 19, Three.js, `@react-three/fiber` 9,
+`@react-three/drei` 10, and `@react-three/xr` 6 are peer dependencies. npm 7+
+and pnpm install them automatically; they must be a single copy in the host
+app.
+
+Tailwind CSS v4 is now required for the built-in HTML chrome: video controls,
+captions, context menus, tooltips, and accessibility helpers render with
+Tailwind utility classes instead of a bundled stylesheet. Add a source entry in
+your app so Tailwind can scan this package:
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@ericchen1990/pano-view";
+```
+
+This package does not ship a separate CSS file. If your app does not scan
+`@ericchen1990/pano-view`, those built-in overlays will render without their
+default styling. Customization still works through `className`, `style`, and
+component appearance props.
 
 ## Exported components
 
@@ -26,8 +47,10 @@ React 19, React DOM 19, Three.js, `@react-three/fiber` 9, and `@react-three/drei
 
 - [`PanoViewer`](#panoviewer) — canvas shell, camera, default controls, and imperative view API
 - [`Sphere`](#sphere) — single 2:1 equirectangular image
+- [`PanoVideo`](#panovideo) — 2:1 equirectangular video on the panorama sphere
 - [`Tile`](#tile) — krpano-style multires cube tiles
 - [`Scenes`](#scenes) — controlled multi-scene transitions
+- [`PanoFilter`](#panofilter) — color and artistic filters on the panorama source
 
 ### Controls
 
@@ -35,11 +58,14 @@ React 19, React DOM 19, Three.js, `@react-three/fiber` 9, and `@react-three/drei
 - [`TouchControls`](#touchcontrols) — one-finger drag and pinch zoom
 - [`KeyboardControls`](#keyboardcontrols) — arrow-key look, FOV, and scene cycling
 - [`AutoRotate`](#autorotate) — automatic yaw rotation
+- [`Gyro`](#gyro) — opt-in device-orientation control
+- [`WebVR`](#webvr) — WebXR-first immersive VR with MobileVR fallback
 
 ### Events and chrome
 
 - [`PanoEvents`](#panoevents) — viewer-level lifecycle and interaction callbacks
 - [`PanoContextMenu`](#panocontextmenu) — right-click reset / fullscreen menu
+- [`PanoVideoControls`](#panovideo) — playback chrome for `PanoVideo` (mounted by default)
 
 ### Hotspots
 
@@ -97,7 +123,7 @@ export function ControlledExample() {
         style={{ height: 560 }}
       >
         <AutoRotate enabled speed={18} acceleration={18} startDelay={1_000} />
-        <Sphere src="/panoramas/room.webp" />
+        <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
       </PanoViewer>
     </>
   );
@@ -128,6 +154,12 @@ The canvas cursor defaults to `grab`, becomes `grabbing` while dragging with the
 
 `Sphere` expects a 2:1 equirectangular image. Use `yawOffset` when the source's forward direction needs horizontal adjustment.
 
+`previewUrl` is required and shows a low-resolution 2:1 image while `src` loads.
+Relative paths resolve against the directory of `src`; root-absolute and
+`http(s)` URLs are used as-is. For krpano sphere scenes, copy
+[`<preview url>`](https://krpano.com/docu/xml/#preview) into `previewUrl`. That
+preview must be equirectangular, not a cube strip.
+
 ```tsx
 "use client";
 
@@ -136,21 +168,97 @@ import { PanoViewer, Sphere } from "@ericchen1990/pano-view";
 export function SphereExample() {
   return (
     <PanoViewer style={{ width: "100%", height: 560 }}>
-      <Sphere src="/panoramas/room.webp" />
+      <Sphere
+        src="/panoramas/room.webp"
+        previewUrl="preview.webp"
+      />
+    </PanoViewer>
+  );
+}
+```
+
+## PanoVideo
+
+`PanoVideo` maps a 2:1 equirectangular video onto the same inward sphere as
+`Sphere`. Pass one `src`, or `variants` with multiple files per quality so the
+browser can pick mp4 / webm and the control bar can switch resolution. Changing
+quality keeps the current time and play/pause state.
+
+A default playback bar is mounted on the viewer overlay: play/pause, seek, time,
+volume, speed, resolution, captions, and fullscreen. Volume is a hover (or tap)
+vertical slider when the browser allows `HTMLMediaElement.volume`; iOS Safari
+only exposes mute. The speed menu lists rates the current element accepts. The
+captions menu also includes a settings panel for subtitle font size and
+background opacity. When the viewer is narrow, speed, quality, and captions
+move into a More menu.
+Pass `controls={false}` to hide it, an appearance object to restyle the default
+instance, or render `PanoVideoControls` as a `PanoViewer` child to replace that
+instance.
+
+Captions use WebVTT `tracks`. The video element is off-screen, so cue text is
+rendered as a HUD overlay. `captions={false}` hides the overlay and the language
+menu; an object merges with the default appearance (`color`, `background`,
+`fontSize`, `fontFamily`, `textShadow`, `padding`, `borderRadius`, `maxWidth`,
+`bottom`). Those values act as the initial caption appearance; viewers can still
+adjust subtitle size and background from the default control-bar menu at
+runtime.
+
+```tsx
+"use client";
+
+import { PanoViewer, PanoVideo } from "@ericchen1990/pano-view";
+
+export function VideoExample() {
+  return (
+    <PanoViewer style={{ width: "100%", height: 560 }}>
+      <PanoVideo
+        defaultVariantId="1024"
+        variants={[
+          {
+            id: "1024",
+            label: "1024p",
+            poster: "/video/1024-poster.jpg",
+            sources: [
+              { src: "/video/1024.mp4", type: "video/mp4" },
+              { src: "/video/1024.webm", type: "video/webm" },
+            ],
+          },
+          {
+            id: "1920",
+            label: "1920p",
+            poster: "/video/1920-poster.jpg",
+            sources: [
+              { src: "/video/1920.mp4", type: "video/mp4" },
+              { src: "/video/1920.webm", type: "video/webm" },
+            ],
+          },
+        ]}
+        tracks={[
+          { src: "/video/en.vtt", srcLang: "en", label: "English", default: true },
+          { src: "/video/zh.vtt", srcLang: "zh", label: "中文" },
+        ]}
+        captions={{ fontSize: 16, color: "#fff" }}
+        muted
+      />
     </PanoViewer>
   );
 }
 ```
 
+`muted` defaults to `true` so `autoPlay` has a chance under browser autoplay
+rules. Unmuted playback still needs a user gesture; `onPlaybackStateChange`
+receives `"blocked"` when `play()` is rejected. Remote videos and VTT files
+that are not same-origin should set `crossOrigin` (usually `"anonymous"`).
+
 ## Tile
 
-`Tile` renders six inward-facing cube faces and loads only tiles around the current view. The default layout matches krpano-style output:
+`Tile` renders six inward-facing cube faces and loads only tiles around the current view. When `urlTemplate` is omitted, paths relative to `baseUrl` use this package default:
 
 ```text
-tiles/{face}/l{level}/{row}/l{level}_{face}_{col}_{row}.webp
+tiles/%s/l%l/%v/l%l_%s_%h_%v.webp
 ```
 
-Faces are `f`, `r`, `b`, `l`, `u`, and `d`; rows and columns are 1-based.
+which expands to `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 { PanoViewer, Tile } from "@ericchen1990/pano-view";
@@ -161,33 +269,81 @@ export function TileExample() {
       <Tile
         baseUrl="https://cdn.example.com/panoramas/room"
         multires="512,500,1000,2000"
+        previewUrl="previews/cube-vertical.webp"
       />
     </PanoViewer>
   );
 }
 ```
 
-The first `multires` value is the tile size. Remaining values are ascending cube-face sizes for `l1`, `l2`, and later levels. The default preview is `${baseUrl}/previews/cube-vertical.webp`, with six square faces stacked from top to bottom as `l/f/r/b/u/d`. Use `previewFaceOrder` when an atlas uses a different order:
+krpano cube-tile output does not follow that default. Read `url`, `multires`,
+and the preview path from the krpano XML
+([`<cube>`](https://krpano.com/docu/xml/#image.cube),
+[`<preview>`](https://krpano.com/docu/xml/#preview)) and pass them through. If
+those values are missing or do not match the files on disk, tiles resolve to
+the wrong face, level, or row/column and the panorama looks scrambled.
+
+| krpano | `Tile` / `TileScene` prop |
+|---|---|
+| `<cube url>` | `urlTemplate` |
+| `<cube multires>` | `multires` |
+| `<preview url>` | `previewUrl` |
+| `<preview striporder>` | `previewFaceOrder` |
+
+`Sphere` uses the same `<preview url>` → `previewUrl` mapping; that file must be a 2:1 equirectangular image, not a cube strip.
+
+krpano's documented short syntax:
+
+```xml
+<preview url="preview.jpg" />
+<image>
+  <cube url="pano_%s_%l_%v_%h.jpg"
+        multires="512,1024,2048,4096"
+  />
+</image>
+```
+
+maps to:
+
+```tsx
+<Tile
+  baseUrl="/panoramas/room"
+  urlTemplate="pano_%s_%l_%v_%h.jpg"
+  multires="512,1024,2048,4096"
+  previewUrl="preview.jpg"
+/>
+```
+
+A MAKE PANO (MULTIRES) folder layout is often
+`tiles/%s/l%l/%v/l%l_%s_%v_%h.jpg` with `preview.jpg` at the scene root. That
+filename is `%v_%h` (row then column). This package's default tile template is
+`%h_%v` (column then row). Copy the XML values instead of assuming the two
+conventions match.
+
+The first `multires` value is the tile size. Remaining values are ascending cube-face sizes for `l1`, `l2`, and later levels. `previewUrl` is required. Relative paths resolve against `baseUrl`; root-absolute and `http(s)` URLs are used as-is. A typical krpano MAKE PANO (MULTIRES) scene looks like this:
 
 ```tsx
 <Tile
   baseUrl="/panoramas/room"
+  urlTemplate="tiles/%s/l%l/%v/l%l_%s_%v_%h.jpg"
   multires="512,1000,2000"
-  previewUrl="/panoramas/room/previews/cube-vertical.webp"
+  previewUrl="preview.jpg"
   previewFaceOrder={["l", "f", "r", "b", "u", "d"]}
 />
 ```
 
-`previewFaceOrder` must list the six face codes in their top-to-bottom atlas order: `f`, `r`, `b`, `l`, `u`, and `d`.
+`previewFaceOrder` must list the six face codes in their top-to-bottom atlas order: `f`, `r`, `b`, `l`, `u`, and `d`. The preview image is a vertical 1×6 cubestrip. krpano `thumb.jpg` is a small thumbnail and is not this atlas.
 
 During rapid rotation or zoom, loaded tiles remain visible while newly visible tiles use their parent level or the preview as a local fallback.
 
-Override storage conventions with either a krpano placeholder template or a resolver. Both return paths relative to `baseUrl`:
+For layouts that are not krpano XML, override the default with a placeholder
+template or a resolver. Both return paths relative to `baseUrl`:
 
 ```tsx
 <Tile
   baseUrl="/panoramas/room"
   multires={{ tileSize: 512, levels: [500, 1000, 2000] }}
+  previewUrl="previews/cube-vertical.webp"
   urlTemplate="assets/%s/%l/%v_%h.webp"
   resolveTileUrl={({ face, level, row, col }) =>
     `api/tile/${face}/${level}/${row}/${col}`
@@ -208,7 +364,7 @@ a single non-stereo cube panorama.
 ## Scenes
 
 `Scenes` switches controlled sphere and cube-tile scenes with GPU-only
-snapshot blending. The target scene loads its sphere image or tile preview first;
+snapshot blending. The target scene loads its sphere 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
 high-resolution tile scenes in WebGL memory at once.
@@ -221,12 +377,14 @@ import {
 } from "@ericchen1990/pano-view";
 
 const scenes: Scene[] = [
-  { id: "lobby", type: "sphere", src: "/panoramas/lobby.webp" },
+  { id: "lobby", type: "sphere", src: "/panoramas/lobby.webp", previewUrl: "preview.webp" },
   {
     id: "terrace",
     type: "tile",
     baseUrl: "/panoramas/terrace",
     multires: "512,1000,2000",
+    urlTemplate: "tiles/%s/l%l/%v/l%l_%s_%v_%h.webp",
+    previewUrl: "previews/cube-vertical.webp",
   },
 ];
 
@@ -241,16 +399,64 @@ const scenes: Scene[] = [
 </PanoViewer>;
 ```
 
-Available presets are `none`, `crossfade`, `zoom`, `blackout`, `whiteFlash`,
-`slideRightToLeft`, `slideTopToBottom`, `slideDiagonal`, `circleOpen`,
-`verticalOpen`, `horizontalOpen`, and `ellipticZoomOpen`. Pass
-`{ preset: "crossfade", duration: 0.6 }` to override a preset duration.
+Available KRpano-style presets are `none`, `crossfade`, `zoom`, `blackout`,
+`whiteFlash`, `slideRightToLeft`, `slideTopToBottom`, `slideDiagonal`,
+`circleOpen`, `verticalOpen`, `horizontalOpen`, and `ellipticZoomOpen`.
+Grid presets are `pixelate`, `gridWipe`, `gridWipeUp`, `gridWipeRight`,
+`gridWipeDiagonal`, `gridWipeCenter`, `gridWipeChecker`, and `hexDissolve`.
+Cinematic presets are `dissolve`, `shatter`, `particles`, `glitch`, `swirl`,
+`clockWipe`, `ripple`, `zoomBlur`, and `filmBurn`. All of them still blend a
+GPU framebuffer snapshot over the incoming panorama; they do not mix two full
+360 textures. Pass `{ preset: "crossfade", duration: 0.6 }` to override a
+preset duration.
 
 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 `Scenes` viewer rather than to each tile scene.
 
+## PanoFilter
+
+Render `PanoFilter` inside `PanoViewer` to color-grade or stylize the panorama
+source (`Sphere`, `Tile`, and `PanoVideo`). The filter runs on those materials
+only: 3D hotspots, tooltips, video chrome, and iframe overlays keep their
+original color. WebXR / MobileVR inherit the same look because the panorama
+shader itself is patched.
+
+`intensity` mixes the filtered result with the original image (`0`–`1`,
+default `1`). Omit the component, pass `preset="none"`, or set `enabled={false}`
+to leave the source unfiltered.
+
+```tsx
+<PanoViewer style={{ height: 560 }}>
+  <PanoFilter preset="pencil" intensity={0.85} />
+  <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
+  <ImageHotspot
+    id="door"
+    position={{ yaw: 24, pitch: -6 }}
+    src="/hotspots/door.webp"
+  />
+</PanoViewer>
+```
+
+| Preset | Look |
+|---|---|
+| `none` | Identity (no filter) |
+| `grayscale` | Rec.709 black and white |
+| `sepia` | Warm brown antique print |
+| `vintage` | Faded film with grain |
+| `cool` / `warm` | Blue or amber temperature shift |
+| `pencil` | Graphite sketch on paper |
+| `coloredPencil` | Tinted pencil lines |
+| `crayon` | Posterized wax strokes |
+| `watercolor` | Soft pigment on paper |
+| `cartoon` | Cel shading with outlines |
+| `crosshatch` | Luminance hatching |
+
+Built-in artistic looks use screen-space edges and world-space grain so cube
+tiles do not show filter seams. Scene-transition snapshots capture the filtered
+panorama when a filter is active.
+
 ## AutoRotate
 
 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.
@@ -258,10 +464,140 @@ Auto-rotation is off by default. Render `AutoRotate` inside `PanoViewer` to enab
 ```tsx
 <PanoViewer style={{ height: 560 }}>
   <AutoRotate enabled speed={12} acceleration={6} startDelay={2_000} />
-  <Sphere src="/panoramas/room.webp" />
+  <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
 </PanoViewer>
 ```
 
+## Gyro
+
+`Gyro` is an opt-in device-orientation control and is disabled by default.
+Render it inside `PanoViewer` and control its `enabled` prop. Relative mode
+(the default) treats the view at activation time as the starting direction.
+Set `absolute` to follow compass-oriented headings and use `north` to identify
+the panorama yaw that points North.
+
+```tsx
+import { useRef, useState } from "react";
+import {
+  Gyro,
+  PanoViewer,
+  Sphere,
+  type GyroHandle,
+} from "@ericchen1990/pano-view";
+
+export function GyroExample() {
+  const gyroRef = useRef<GyroHandle>(null);
+  const [enabled, setEnabled] = useState(false);
+
+  const toggle = async () => {
+    if (enabled) {
+      setEnabled(false);
+      return;
+    }
+    // iOS requires this call to run directly inside a user gesture.
+    setEnabled((await gyroRef.current?.requestPermission()) ?? false);
+  };
+
+  return (
+    <>
+      <button onClick={() => void toggle()}>
+        {enabled ? "Disable gyro" : "Enable gyro"}
+      </button>
+      <PanoViewer style={{ height: 560 }}>
+        <Gyro
+          ref={gyroRef}
+          enabled={enabled}
+          camroll
+          friction={0}
+          softstart={0.5}
+          touchMode="full"
+          onDenied={() => setEnabled(false)}
+        />
+        <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
+      </PanoViewer>
+    </>
+  );
+}
+```
+
+`camroll` (default `true`) levels the camera from device roll. `friction`
+accepts `0` to `0.99`; higher values smooth more strongly but add latency.
+`softstart` is the activation blend duration in seconds (default `0.5`).
+`desktopSupport` defaults to `false` because desktop browsers can expose the
+API without a physical sensor.
+
+`touchMode` controls how touch drag combines with device movement:
+
+- `off` ignores touch yaw/pitch while leaving pinch FOV available.
+- `horizontaloffset` adds only a horizontal offset.
+- `full` adds horizontal and vertical offsets; the vertical offset returns
+  toward the physical orientation as the device moves.
+- `disablegyro` disables the active gyro session on the next touch.
+
+The `GyroHandle` exposes `resetSensor(yaw?, pitch?)`, `isAvailable()`,
+`isEnabled()`, and `requestPermission()`. Gyro activity pauses `AutoRotate`
+and counts as viewer interaction for idle tracking. Sensor APIs generally
+require HTTPS. A cross-origin iframe must be permitted by the host page, for
+example with `allow="gyroscope; accelerometer"` and a compatible
+`Permissions-Policy` header.
+
+## WebVR
+
+`WebVR` adds immersive viewing to the nearest `PanoViewer`. It prefers an
+`immersive-vr` WebXR session on supported headsets. On phones without WebXR it
+uses a stereoscopic split-screen view with device orientation, and on desktop
+it can provide a mouse-driven simulated VR preview. The built-in chrome includes
+Enter VR, Exit VR, and MobileVR setup controls.
+
+```tsx
+import { useRef } from "react";
+import {
+  PanoViewer,
+  Sphere,
+  WebVR,
+  type WebVRHandle,
+} from "@ericchen1990/pano-view";
+
+export function WebVRExample() {
+  const webVRRef = useRef<WebVRHandle>(null);
+
+  return (
+    <PanoViewer style={{ height: 560 }}>
+      <WebVR
+        ref={webVRRef}
+        chrome
+        fakeSupport
+        mobileVr
+        onEnterVR={(mode) => console.log("Entered", mode)}
+      />
+      <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
+    </PanoViewer>
+  );
+}
+```
+
+The handle exposes `enterVR()`, `exitVR()`, `toggleVR()`, `isAvailable()`,
+`isEnabled()`, `getMode()`, and `requestPermission()`. Modes are `"webxr"`,
+`"mobilevr"`, and `"fake"`. `profile` accepts `"none"`, `"cardboard-v1"`,
+`"cardboard-v2"`, `"gear-vr"`, `"daydream"`, or a custom
+`{ fov, ipdMm, k1, k2 }` lens profile. MobileVR setup values are versioned and
+stored in the current origin's `localStorage`. In VR, a center reticle shows a
+crosshair; looking at an interactive hotspot draws a clockwise ring that fills
+over `cursorDwellMs` (default 1500), then the hotspot click handler runs. Set
+`cursorDwellMs={0}` to keep the reticle without auto-click. Simulated desktop
+VR (`fake` mode) requests pointer lock by default (`mousePointerLock`) so the
+cursor hides and mouse movement looks around; click the view again if the
+browser releases the lock. Fallback sessions keep the screen awake
+(`wakelock`) with the Screen Wake Lock API, or a looping hidden video on
+browsers that lack it.
+
+WebXR requires HTTPS and a user gesture. Mobile sensor access also requires
+HTTPS and may require an explicit iOS permission prompt. Embedded viewers need
+appropriate `xr-spatial-tracking`, `gyroscope`, and `accelerometer` permissions.
+DOM overlays such as iframe hotspots, tooltips, and video controls are not
+visible inside an immersive headset session; mesh-based hotspots remain
+interactive through the default WebXR controller rays.
+
 ## 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.
@@ -277,7 +613,7 @@ Auto-rotation is off by default. Render `AutoRotate` inside `PanoViewer` to enab
   }}
   style={{ height: 560 }}
 >
-  <Sphere src="/panoramas/room.webp" />
+  <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
 </PanoViewer>
 ```
 
@@ -346,7 +682,7 @@ export function KeyboardExample({ scenes }: { scenes: Scene[] }) {
 
 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.
+Default bindings: arrows and WASD 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
 
@@ -375,7 +711,7 @@ export function PlacementExample() {
       onPanoramaPointerMove={({ position }) => console.log("move", position)}
       style={{ height: 560 }}
     >
-      <Sphere src="/panoramas/room.webp" />
+      <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
     </PanoViewer>
   );
 }
@@ -416,7 +752,7 @@ import {
     onAutoRotateOneRound={() => console.log("full turn")}
   />
   <AutoRotate enabled />
-  <Sphere src="/panoramas/room.webp" />
+  <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
 </PanoViewer>;
 ```
 
@@ -429,6 +765,8 @@ Supported callbacks (krpano names in parentheses where applicable):
 - Fullscreen: `onEnterFullscreen` / `onExitFullscreen`
 - `onResize` — canvas content-box size via `ResizeObserver`
 - Auto-rotate: `onAutoRotateStart` / `onAutoRotateStop` / `onAutoRotateOneRound`
+- Gyro: `onGyroAvailable` / `onGyroUnavailable` / `onGyroEnable` /
+  `onGyroDisable` / `onGyroDenied`
 
 `PanoViewer`'s existing `onViewChange` / `onPanoramaClick` / `onPanoramaDoubleClick` /
 `onPanoramaPointerMove` props remain supported and share the same event bus.
@@ -436,7 +774,7 @@ Supported callbacks (krpano names in parentheses where applicable):
 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.
+xml/VR/frame-render events.
 
 ## PanoContextMenu
 
@@ -447,7 +785,7 @@ separator between them.
 
 ```tsx
 <PanoViewer style={{ height: 560 }}>
-  <Sphere src="/panoramas/room.webp" />
+  <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
 </PanoViewer>
 ```
 
@@ -455,7 +793,7 @@ Disable the default menu (restore the browser menu, or mount your own):
 
 ```tsx
 <PanoViewer contextMenu={false}>
-  <Sphere src="/panoramas/room.webp" />
+  <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
 </PanoViewer>
 ```
 
@@ -463,7 +801,7 @@ Tune appearance while keeping the default items:
 
 ```tsx
 <PanoViewer contextMenu={{ appearance: { opacity: 0.92, borderRadius: 8 } }}>
-  <Sphere src="/panoramas/room.webp" />
+  <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
 </PanoViewer>
 ```
 
@@ -490,7 +828,7 @@ only add your own:
   }}
   style={{ height: 560 }}
 >
-  <Sphere src="/panoramas/room.webp" />
+  <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
 </PanoViewer>
 ```
 
@@ -524,7 +862,7 @@ reimplementing fullscreen enter/exit state:
   }}
   style={{ height: 560 }}
 >
-  <Sphere src="/panoramas/room.webp" />
+  <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
 </PanoViewer>
 ```
 
@@ -548,14 +886,25 @@ For a fully custom DOM menu, set `contextMenu={false}` and render
 
 ## Shared hotspot contract and saved definitions
 
-Every hotspot has an `id`, optional `visible`, `interactive`, `renderOrder`,
-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.
+Every hotspot has an `id`, optional `visible`, `interactive`, `pointerEvents`,
+`renderOrder`, 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.
+`pointerEvents="none"` ignores mouse, touch, and pen so those events pass
+through to the panorama even when the hotspot stays keyboard-interactive.
 Interactive hotspots set the canvas cursor to `pointer` while hovered, or to
 the hotspot's `cursor` prop when that is set.
 
+```tsx
+<TextHotspot
+  id="caption"
+  pointerEvents="none"
+  position={{ yaw: 12, pitch: -8 }}
+  text="Decorative label"
+/>
+```
+
 `onClick` and `onHoverChange` receive a position and input source (`"pointer"`
 or `"keyboard"`). Point hotspots can use `draggable`, `onDragStart`,
 `onPositionChange`, and `onDragEnd`; the host must write the reported position
@@ -568,11 +917,18 @@ Every hotspot can show a DOM tooltip at its anchor. Pass a string or
 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`.
+clicked. Hover and click triggers need `interactive` and `pointerEvents`
+other than `"none"`.
 
 `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`).
+These are screen directions: the bubble sits outside the hotspot's projected
+screen bounds on that edge, so rotated graphics such as arrows are not covered.
+`tooltipOffset` is the screen-space gap in CSS pixels (default `12` /
+`DEFAULT_HOTSPOT_TOOLTIP_OFFSET`).
+
+Optional `tooltipAppearance` overrides the bubble paint. Unset fields keep the
+library default theme (`DEFAULT_HOTSPOT_TOOLTIP_APPEARANCE`): background, text
+color, border, corner radius, shadow, padding, and font size.
 
 ```tsx
 <ImageHotspot
@@ -583,6 +939,15 @@ screen-space gap in CSS pixels (default `12` / `DEFAULT_HOTSPOT_TOOLTIP_OFFSET`)
   tooltip={{ text: "Courtyard gallery", image: "/hotspots/gallery-thumb.webp" }}
   tooltipPlacement="top"
   tooltipOffset={16}
+  tooltipAppearance={{
+    background: "rgba(12, 28, 36, 0.88)",
+    color: "#e7f2f5",
+    border: "1px solid rgba(56, 84, 91, 0.9)",
+    borderRadius: 10,
+    shadow: "0 10px 28px rgba(0, 0, 0, 0.42)",
+    padding: 10,
+    fontSize: 13,
+  }}
 />
 <GraphicHotspot
   id="marker"
@@ -628,7 +993,7 @@ are angular degrees, so they remain independent of the canvas resolution.
 import { ImageHotspot, PanoViewer, Sphere } from "@ericchen1990/pano-view";
 
 <PanoViewer style={{ height: 560 }}>
-  <Sphere src="/panoramas/room.webp" />
+  <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
   <ImageHotspot
     id="gallery"
     ariaLabel="Open gallery"
@@ -765,6 +1130,8 @@ import { PolygonHotspot } from "@ericchen1990/pano-view";
   stroke="#f5fbfc"
   strokeWidth={2}
   strokeOpacity={0.8}
+  strokeDashSize={8}
+  strokeGapSize={4}
   draggable
   onVerticesChange={({ vertices }) => setZoneVertices(vertices)}
   onInvalid={(issues) => console.error(issues)}
@@ -772,9 +1139,11 @@ import { PolygonHotspot } from "@ericchen1990/pano-view";
 ```
 
 `strokeWidth` is a screen-space CSS pixel value, so it remains visually
-consistent across FOV changes. Dragging moves all vertices together while
-keeping yaw normalized and pitch clamped. Individual vertex editing is provided
-by the authoring workflow, not the runtime hotspot component.
+consistent across FOV changes. `strokeDashSize` and `strokeGapSize` use the
+same CSS-pixel units; omit them or set `strokeDashSize` to `0` for a solid
+stroke. Dragging moves all vertices together while keeping yaw normalized and
+pitch clamped. Individual vertex editing is provided by the authoring
+workflow, not the runtime hotspot component.
 
 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
@@ -783,7 +1152,8 @@ between them.
 ## PolylineHotspot
 
 `PolylineHotspot` is an open path of at least two yaw/pitch vertices. It uses
-the same CSS-pixel `strokeWidth`, visibility, semantic interaction, controlled
+the same CSS-pixel `strokeWidth`, optional dashed stroke (`strokeDashSize` /
+`strokeGapSize`), visibility, semantic interaction, controlled
 whole-path drag, and vertex-change callback as `PolygonHotspot`, but it never
 connects the final point to the first and has no fill.
 
@@ -797,6 +1167,8 @@ import { PolylineHotspot } from "@ericchen1990/pano-view";
   stroke="#75cbd3"
   strokeWidth={2}
   strokeOpacity={0.9}
+  strokeDashSize={8}
+  strokeGapSize={4}
   draggable
   onVerticesChange={({ vertices }) => setRouteVertices(vertices)}
 />;
@@ -880,8 +1252,12 @@ changes, unmounts, and React StrictMode lifecycles deterministic.
 `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`.
+the other point hotspots. Typography uses the same names as CSS
+(`fontFamily`, `fontSize`, `fontWeight`, `fontStyle`) but is painted onto the
+canvas, not applied as DOM style. `fontSize` is canvas pixels (default 96) and
+does not scale with panel height. `fontWeight` defaults to `600` and
+`fontStyle` to `"normal"`. `padding` and `borderRadius` remain fractions of
+the texture's shorter side, so they still follow `width` / `height`.
 
 ```tsx
 import { TextHotspot } from "@ericchen1990/pano-view";
@@ -895,18 +1271,22 @@ import { TextHotspot } from "@ericchen1990/pano-view";
   mode="billboard"
   scaleMode="fixed"
   text={"Courtyard overlook\nNorth terrace"}
+  fontFamily="system-ui, sans-serif"
+  fontSize={96}
+  fontWeight={600}
+  fontStyle="normal"
   align="center"
   verticalAlign="middle"
-  fontSize={0.18}
   color="#f8fafc"
   background="#111827"
   backgroundOpacity={0.72}
 />;
 ```
 
-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`.
+Load a custom `fontFamily` on the page before the hotspot paints. The hotspot
+waits on `document.fonts.load` when that API exists, then draws with whatever
+faces the document has. `onLoad(texture)` and `onError(error)` match
+`ImageHotspot`.
 
 ## IframeHotspot
 
@@ -932,7 +1312,9 @@ import { IframeHotspot } from "@ericchen1990/pano-view";
 
 `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
+interactive and blocks dragging through the iframe. A hotspot
+`pointerEvents="none"` also forces the iframe overlay not to capture pointer
+events. `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