@ericchen1990/pano-view 4.0.1 → 4.1.0

package/README.md

@@ -1999,6 +1999,9 @@ These are props on `Gyro` itself. `PanoEvents` `onGyro*` callbacks subscribe to
 
 ## WebVR
 
+VR settings use independent v2 storage for simulated desktop and MobileVR; legacy v1 values are ignored. Reset affects the active fallback mode, or both outside VR. The neutral `none` preset uses 80° vertical FOV, 60 mm virtual eye spacing and centered optics regardless of physical screen size. Only MobileVR auto screen size queries DPDB (5-second timeout); ambiguous matches require manual calibration. Phone detection never selects a lens preset. Explicit props take precedence and their controls are read-only in Setup.
+
+
 `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
@@ -2052,8 +2055,12 @@ 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
+(`mousePointerLock`) so the cursor hides and mouse movement looks around. Right-click
+to release the mouse without leaving VR; left-click the view to lock it again.
+While unlocked, the reticle is hidden and gaze actions stop; relocking starts
+a fresh dwell. Desktop crosshair and ring sizes are 60% of the headset size.
+Browser Escape behavior is preserved. If locking is denied or unsupported,
+VR stays available with a normal cursor; a later left-click can retry. Fallback sessions keep the
 screen awake (`wakelock`) with the Screen Wake Lock API, or a looping hidden
 video on browsers that lack it.
 
@@ -2066,13 +2073,13 @@ interactive through the default WebXR controller rays.
 
 ### Props
 
-- `chrome` — default `true` mounts session Exit / Setup UI (no Enter VR button). An appearance object may set `background` (default `rgba(16, 24, 32, 0.78)`), `color` (`#ffffff`), `accent` (`#7dd3fc`), `borderRadius` (`6`), `fontSize` (`14`), and optional `setupTitle`. Session buttons fade after ~3s idle and return on pointer / wheel / keyboard interaction with the viewer.
+- `chrome` — default `true` mounts session Exit / Setup UI (no Enter VR button). An appearance object may set `background` (default `rgba(16, 24, 32, 0.78)`), `color` (`#ffffff`), `accent` (`#7dd3fc`), `borderRadius` (`6`), `fontSize` (`14`), and optional `setupTitle`. Session buttons fade after ~3s idle while locked. Simulated VR keeps them visible while the mouse is unlocked; hovering, keyboard focus, and an open Setup panel also keep them visible.
 - `mobileVr` — default `true`.
 - `desktopSupport` — default `false` (independent of the same-named `Gyro` prop).
 - `fakeSupport` — default `true` for mouse-driven desktop simulation.
 - `screensize` — `"auto"` (factory / omitted storage default) or inches; numbers are clamped to **3–20** with one decimal place.
 - `databaseUrl` — Cardboard DPDB URL for `"auto"` screensize. Default `https://storage.googleapis.com/cardboard-dpdb/dpdb.json`. Pass `""` or `null` to disable the online lookup.
-- `profile` — omitted values use stored settings; factory default is `"cardboard-v1"`. Also accepts `"none"`, `"cardboard-v2"`, `"gear-vr"`, `"daydream"`, or a custom `{ fov, ipdMm, k1, k2, screenToLensMm?, trayDistanceMm?, label?, id? }`. `trayDistanceMm` is millimetres from the headset tray bottom to the lens center; `0` / omitted keeps the vertical optical axis at screen center.
+- `profile` — omitted values use stored settings; factory default is `"none"`. Also accepts `"none"`, `"cardboard-v2"`, `"gear-vr"`, `"daydream"`, or a custom `{ fov, ipdMm, k1, k2, screenToLensMm?, trayDistanceMm?, label?, id? }`. `trayDistanceMm` is millimetres from the headset tray bottom to the lens center; `0` / omitted keeps the vertical optical axis at screen center.
 - `absolute` — default `false`. Compass-oriented MobileVR heading (no effect in WebXR).
 - `north` — default `0`. Panorama yaw that represents North when `absolute` is enabled.
 - `friction` — default `0` (range `0–0.99`). MobileVR gyro smoothing; keep `0` for normal viewing.
@@ -2470,6 +2477,8 @@ on screen. Clicking the hotspot does not toggle it. Optional
 clicked. Hover and click triggers need `interactive` and `pointerEvents`
 other than `"none"`.
 
+`tooltipMode` defaults to `"billboard"` and supports `"surface"`. `tooltipScaleMode` defaults to `"inherit"`, following the hotspot’s effective zoom behavior. Floating tooltips also support `"fov"` and `"fixed"`; surface tooltips always scale with FOV. Styling is measured at the hotspot’s `referenceFov` (default `75`), while the gap remains in screen pixels. Polygon and polyline geometry always follows the sphere, without floating, distance or scale-mode controls; their tooltips remain independently configurable and default to floating with FOV scaling. Omitted settings in existing projects use these new defaults too.
+
 `tooltipPlacement` is `"top"` (default), `"bottom"`, `"left"`, or `"right"`.
 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.
@@ -2645,7 +2654,7 @@ Point hotspots use `mode` to configure orientation and placement together:
   decrease it to move the hotspot nearer.
   The built-in panorama shell is at roughly `1000` units; distance is
   automatically capped so the hotspot's corners cannot cross it.
-- `scaleMode="fov"` (default) lets a hotspot grow when the user zooms in.
+- Floating hotspots default to `scaleMode="fixed"`; choose `"fov"` to scale with zoom. Surface hotspots always use `"fov"`, even when `"fixed"` was saved.
   `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; positive
@@ -3178,3 +3187,7 @@ Legacy `action` remains a click fallback; `events.click` wins. Editing or cleari
 `ProjectScenes.onHotspotEvent(event)` receives `trigger`, `sceneId`, `hotspot`, `interaction` and `preventDefault()`. On clicks it runs before the existing `onHotspotClick`; either callback can cancel the action. `onCustomAction(event)` additionally receives `action` and may return a Promise. Dispatch by the stable `action.actionId`, validate business parameters and throw for unknown actions. Missing handlers, synchronous exceptions and rejected Promises reach `onHotspotError` with `trigger`. Requests, authentication, cancellation, duplicate prevention and response ordering are host responsibilities; events dispatch independently without automatic retries.
 
 Hover runs once per logical hotspot boundary, skips touch and keyboard focus, and respects visibility and pointer interaction settings. Scene changes, hiding and unmounting clear hover state without executing leave actions. Existing tooltip behavior is independent. Custom renderers must forward `context.onHoverChange(hovered, interaction)` as well as `context.onClick`; `context.renderDefault()` wires both automatically.
+
+## VR control groups
+
+Customizable VR-only icon groups support media, models and scrolling. See the [VR controls guide](./docs/dialogs.md#vr-icon-controls-and-scrolling) for APIs and examples.

package/README.zh-CN.md

@@ -1793,6 +1793,9 @@ export function GyroExample() {
 
 ## WebVR
 
+VR 设置按桌面模拟与手机分屏分别保存到 v2 存储，不继承旧版 v1。Reset 仅重置当前回退模式，未进入 VR 时重置两种模式。默认 `none` 使用每眼垂直 FOV 80°、虚拟眼距 60 mm 和居中光轴，不根据屏幕尺寸校准。只有手机自动尺寸查询 DPDB（5 秒超时），冲突结果需要手动校准；识别手机不会自动选择镜头。显式 props 优先，相关设置项只读。桌面解锁期间顶部按钮常显；锁定后空闲 3 秒淡出，悬停、键盘焦点或设置面板打开时保持显示。
+
+
 `WebVR` 为最近的 `PanoViewer` 增加沉浸式观看。支持的头戴设备优先使用 `immersive-vr` WebXR 会话。无 WebXR 的手机使用设备方向的立体分屏；桌面可提供鼠标驱动的模拟 VR 预览。进入 VR 由宿主通过查看器句柄触发；内置 chrome 仅在会话中显示退出 VR 与 MobileVR 设置（空闲后淡出）。
 
 ```tsx
@@ -1822,7 +1825,7 @@ export function WebVRExample() {
 }
 ```
 
-句柄暴露 `enterVR()`、`exitVR()`、`toggleVR()`、`isAvailable()`、`isEnabled()`、`getMode()`、`getState()`、`subscribe()`、`requestPermission()` 与 `resetSettings()`。模式为 `"webxr"`、`"mobilevr"`、`"fake"`。`profile` 接受 `"none"`、`"cardboard-v1"`、`"cardboard-v2"`、`"gear-vr"`、`"daydream"`，或自定义 `{ fov, ipdMm, k1, k2, screenToLensMm?, trayDistanceMm? }` 镜头配置。在已知物理屏幕尺寸时，MobileVR 会用瞳距与可选的托盘到镜片高度（`trayDistanceMm`；Cardboard V1 为 `35`）放置每只眼睛的光轴；`0` 或省略则保持垂直方向居中。当 `screensize` 为 `"auto"` 时，MobileVR 会加载 Cardboard Device Parameter Database（`databaseUrl`，默认 Google 公开 DPDB）估算对角线英寸；传 `""` 或 `null` 可跳过请求。无法识别时触发 `onUnknownDevice`，并继续使用镜头预设 FOV（尺寸未知前不做托盘偏移）。MobileVR 设置值会版本化并保存在当前源的 `localStorage` 中；`resetSettings()` 会清除该存储并恢复 props 或内置默认（Setup 面板也有 Reset）。VR 中中心准星显示十字；注视可交互热点时绘制顺时针填充环，经 `cursorDwellMs`（默认 1500）后触发热点点击。设 `cursorDwellMs={0}` 可保留准星但不自动点击。模拟桌面 VR（`fake` 模式）默认请求指针锁定（`mousePointerLock`），隐藏光标并用鼠标环视；若浏览器释放锁定需再次点击视图。回退会话通过 Screen Wake Lock API 或在不支持时的循环隐藏视频保持屏幕常亮（`wakelock`）。
+句柄暴露 `enterVR()`、`exitVR()`、`toggleVR()`、`isAvailable()`、`isEnabled()`、`getMode()`、`getState()`、`subscribe()`、`requestPermission()` 与 `resetSettings()`。模式为 `"webxr"`、`"mobilevr"`、`"fake"`。`profile` 接受 `"none"`、`"cardboard-v1"`、`"cardboard-v2"`、`"gear-vr"`、`"daydream"`，或自定义 `{ fov, ipdMm, k1, k2, screenToLensMm?, trayDistanceMm? }` 镜头配置。在已知物理屏幕尺寸时，MobileVR 会用瞳距与可选的托盘到镜片高度（`trayDistanceMm`；Cardboard V1 为 `35`）放置每只眼睛的光轴；`0` 或省略则保持垂直方向居中。当 `screensize` 为 `"auto"` 时，MobileVR 会加载 Cardboard Device Parameter Database（`databaseUrl`，默认 Google 公开 DPDB）估算对角线英寸；传 `""` 或 `null` 可跳过请求。无法识别时触发 `onUnknownDevice`，并继续使用镜头预设 FOV（尺寸未知前不做托盘偏移）。MobileVR 设置值会版本化并保存在当前源的 `localStorage` 中；`resetSettings()` 会清除该存储并恢复 props 或内置默认（Setup 面板也有 Reset）。VR 中中心准星显示十字；注视可交互热点时绘制顺时针填充环，经 `cursorDwellMs`（默认 1500）后触发热点点击。设 `cursorDwellMs={0}` 可保留准星但不自动点击。模拟桌面 VR（`fake` 模式）默认请求指针锁定（`mousePointerLock`），隐藏光标并用鼠标环视；右键释放鼠标但保留 VR，左键点击画面重新锁定（该次点击只恢复锁定）。解锁时隐藏准星并停止注视动作，重新锁定后重新计时。桌面十字及进度环为头显尺寸的 60%。保留浏览器原有 Esc 行为；锁定被拒绝或不支持时保留普通鼠标，可再次左键重试。回退会话通过 Screen Wake Lock API 或在不支持时的循环隐藏视频保持屏幕常亮（`wakelock`）。
 
 WebXR 需要 HTTPS 与用户手势。移动端传感器访问也需要 HTTPS，iOS 可能需显式权限提示。嵌入查看器需要适当的 `xr-spatial-tracking`、`gyroscope`、`accelerometer` 权限。iframe 热点、tooltip、视频控件等 DOM 叠加层在沉浸式头戴会话中不可见；基于 mesh 的热点仍可通过默认 WebXR 控制器射线交互。
 
@@ -1834,7 +1837,7 @@ WebXR 需要 HTTPS 与用户手势。移动端传感器访问也需要 HTTPS，i
 - `fakeSupport` — 默认 `true`，允许鼠标驱动的桌面模拟 VR。
 - `screensize` — `"auto"`（出厂 / 省略时的存储默认）或英寸数；数字会被夹到 **3–20** 并保留一位小数。
 - `databaseUrl` — `"auto"` 屏幕尺寸时使用的 Cardboard DPDB URL。默认 `https://storage.googleapis.com/cardboard-dpdb/dpdb.json`。传 `""` 或 `null` 可关闭在线查询。
-- `profile` — 省略时用已存设置，出厂为 `"cardboard-v1"`。也可传 `"none"`、`"cardboard-v2"`、`"gear-vr"`、`"daydream"`，或自定义 `{ fov, ipdMm, k1, k2, screenToLensMm?, trayDistanceMm?, label?, id? }`。`trayDistanceMm` 为头显托盘底边到镜片中心的毫米距离；`0` / 省略时垂直光轴保持屏幕中心。
+- `profile` — 省略时用已存设置，出厂为 `"none"`。也可传 `"none"`、`"cardboard-v2"`、`"gear-vr"`、`"daydream"`，或自定义 `{ fov, ipdMm, k1, k2, screenToLensMm?, trayDistanceMm?, label?, id? }`。`trayDistanceMm` 为头显托盘底边到镜片中心的毫米距离；`0` / 省略时垂直光轴保持屏幕中心。
 - `absolute` — 默认 `false`。MobileVR 使用罗盘绝对朝向（对 WebXR 无效）。
 - `north` — 默认 `0`。启用 `absolute` 时，全景中代表北方的 yaw。
 - `friction` — 默认 `0`（范围 `0–0.99`）。MobileVR 陀螺仪平滑；正常观看保持 `0`。
@@ -2164,6 +2167,8 @@ import {
 
 `tooltipPlacement` 为 `"top"`（默认）、`"bottom"`、`"left"`、`"right"`。均为屏幕方向：气泡位于热点投影边界该侧之外，避免遮挡旋转后的图形（如箭头）。`tooltipOffset` 为屏幕空间间距（CSS 像素，默认 `12` / `DEFAULT_HOTSPOT_TOOLTIP_OFFSET`）。
 
+`tooltipMode` 默认 `"billboard"`（悬浮），可设为 `"surface"`（贴合球面）。`tooltipScaleMode` 默认 `"inherit"`，跟随热点实际缩放规则；悬浮提示可独立设为 `"fov"` 或 `"fixed"`，贴合提示始终随 FOV 缩放。气泡字号和样式以热点 `referenceFov`（默认 `75`）为基准，间距继续使用屏幕像素。多边形、折线本体始终贴合球面，不支持悬浮、距离或缩放模式；其提示默认悬浮并随 FOV 缩放，也支持独立配置。新旧项目省略配置均采用这些默认值。
+
 可选 `tooltipAppearance` 覆盖气泡绘制。未设字段保留库默认主题（`DEFAULT_HOTSPOT_TOOLTIP_APPEARANCE`）：背景、文字色、边框、圆角、阴影、内边距与字号。
 
 ```tsx
@@ -2300,7 +2305,7 @@ import { GraphicHotspot } from "@ericchen1990/pano-view";
 
 - `mode="surface"` 将平面附着于局部全景表面。
 - `mode="billboard"` 使平面始终朝向相机并浮于壳层前方。`distance` 是热点到相机的距离（世界单位，默认 `10`），减小该值可将热点移近相机。内置全景壳层约在 `1000` 单位；距离会自动限制在允许范围内，避免热点角点穿过壳层。
-- `scaleMode="fov"`（默认）在用户放大时热点变大。`scaleMode="fixed"` 补偿 FOV 变化，屏幕尺寸接近 `referenceFov`（默认 `75`）时的大小。
+- 悬浮热点默认 `scaleMode="fixed"`，保持固定屏幕大小；可用 `scaleMode="fov"` 随视角缩放。贴合热点始终使用 `fov`，显式的 `fixed` 不生效。`scaleMode="fixed"` 补偿 FOV 变化，屏幕尺寸接近 `referenceFov`（默认 `75`）时的大小。
 - `rotation` 绕自身法线旋转（度）；正值顺时针，负值逆时针。`scale` 为角向 width/height 的整体正倍率，默认 `1`。
 
 ```tsx
@@ -2709,3 +2714,7 @@ viewLimits: {
 `ProjectScenes.onHotspotEvent(event)` 提供 `trigger`、`sceneId`、`hotspot`、`interaction` 和 `preventDefault()`。点击时先调用它，再调用原有 `onHotspotClick`，任一回调均可取消动作。`onCustomAction(event)` 额外提供 `action`，支持返回 Promise。宿主按稳定的 `action.actionId` 分发，校验业务参数，对未知动作抛出错误。缺少执行器、同步异常和 Promise 拒绝进入附带 `trigger` 的 `onHotspotError`。请求、鉴权、取消、防重复和迟到响应由宿主负责；各事件独立分发，不自动重试。
 
 悬停按整个热点的边界触发一次，跳过触屏和键盘焦点，并遵循可见性、指针交互设置。切换场景、隐藏和卸载仅清理状态，不执行离开动作。原有 tooltip 行为独立保留。自定义渲染器需同时转发 `context.onHoverChange(hovered, interaction)` 和 `context.onClick`；调用 `context.renderDefault()` 会自动接线。
+
+## VR 操作按钮组
+
+视频、模型和滚动支持可定制图标按钮组，仅在 VR 显示。接口、凝视行为与完整示例见[VR 控件指南](./docs/dialogs.zh-CN.md#vr-图标控件与滚动)。

package/dist/data.cjs

@@ -464,6 +464,8 @@ var common = [
   "tooltip",
   "tooltipTrigger",
   "tooltipPlacement",
+  "tooltipMode",
+  "tooltipScaleMode",
   "tooltipOffset",
   "tooltipAppearance"
 ];
@@ -605,6 +607,8 @@ var enums = {
   pointerEvents: ["auto", "none"],
   tooltipTrigger: ["always", "hover", "click"],
   tooltipPlacement: ["top", "bottom", "left", "right"],
+  tooltipMode: ["surface", "billboard"],
+  tooltipScaleMode: ["inherit", "fov", "fixed"],
   mode: ["surface", "billboard"],
   scaleMode: ["fov", "fixed"],
   frameDirection: ["horizontal", "vertical"],