@ericchen1990/pano-view 5.0.0 → 5.1.0

package/dist/styles.css

@@ -886,9 +886,10 @@
   background: var(--pano-scene-menu-background, rgba(16, 16, 16, 0.72));
 }
 
-.pano-control-group { display:flex; flex-wrap:wrap; justify-content:center; gap:var(--pano-control-gap,12px); padding:var(--pano-control-padding,12px); }
-.pano-control-button { display:grid; place-items:center; width:var(--pano-control-size,64px); height:var(--pano-control-size,64px); border:var(--pano-control-border,1px solid #68778a); border-radius:var(--pano-control-radius,12px); background:var(--pano-control-background,#39424e); color:var(--pano-control-color,#fff); cursor:pointer; }
-.pano-control-button svg { width:32px; height:32px; }
+.pano-control-group { display:flex; flex-wrap:wrap; justify-content:center; gap:var(--pano-control-gap,8px); padding:var(--pano-control-padding,8px); background:#161b22; border-radius:12px; }
+.pano-control-button { display:grid; place-items:center; width:var(--pano-control-size,48px); height:var(--pano-control-size,48px); border:var(--pano-control-border,1px solid #68778a); border-radius:var(--pano-control-radius,50%); background:var(--pano-control-background,#39424e); color:var(--pano-control-color,#baf5ff); cursor:pointer; }
+.pano-control-button svg { width:24px; height:24px; }
+.pano-control-button[data-pano-gaze-active] { outline:3px solid var(--pano-control-focus,#ffb300); outline-offset:2px; }
 .pano-control-button:disabled { opacity:.4; cursor:default; }
 .pano-control-button:focus-visible { outline:3px solid var(--pano-control-focus,#ffb300); outline-offset:2px; }
 .pano-media-controls { background:#161b22; gap:var(--pano-control-gap,8px); padding:var(--pano-control-padding,8px); }

package/docs/dialogs.md

@@ -671,6 +671,8 @@ Customize explicit groups with `className`, `style`, and `--pano-control-backgro
 
 Each automatically controlled dialog video has a separate row of circular controls below its picture: backward, play/pause, forward, mute/unmute, then volume down/up where supported. The bar occupies its own layout space without covering the video or following content, scrolls with the video, and follows its container's clipping. Media controls default to 48px buttons with 24px light-blue outline icons, 8px gaps and 8px padding, and can wrap in narrow containers. These defaults apply to automatic video rows and explicit `PanoMediaControls` groups, including audio; existing control CSS variables still override button size, gaps and padding. Leaving VR removes the automatic control slot while preserving the video node and its normal-mode native controls. Before playback, the spatial panel displays the video's poster, or requests a first frame by temporarily hinting `preload="auto"` without playing, seeking, reloading, or creating another video element. If no readable image is available, a visible video placeholder remains. Poster images require same-origin access or CORS permission; unreadable media never taints the panel texture. Preview resources are released and temporary preload settings are restored when the panel closes or leaves VR.
 
+Media snapshots expose optional `hasAudio`: `true` means an audio track is present, `false` means no audio track, and omitted/`undefined` means unknown. Library controls hide mute and volume controls only when it is `false`; unknown states and existing custom controllers retain them. Detection depends on browser support, and silent audio tracks still count as present. Volume is limited to 0–1 (0%–100%) without additional gain; volume commands ignore non-finite values. Source and track changes refresh the detection.
+
 After `cursorDwellMs`, play, mute and reset fire once; seek, volume, rotation and zoom continue until gaze leaves. Scrolling advances in paced steps, with a 700 ms pause between updates. Defaults: `seekSpeed=10` seconds/second, `volumeSpeed=0.25` per second, scroll `speed=0.2` viewports/second (0.14 viewports per step at the default interval). Set `PanoScrollControls.repeatIntervalMs` to adjust the repeat interval. Leaving the target clears pending time and requires a fresh dwell. Closing, leaving VR, disabling or losing visibility stops actions. Gaze cannot bypass trusted media-gesture requirements. Volume buttons are omitted when the platform does not support volume adjustment (including iOS); mute remains available. On supported platforms, volume buttons disable at the corresponding volume limit.
 
 Customize scroll arrows with `--pano-scroll-opacity`, `--pano-scroll-active-opacity`, `--pano-scroll-background` and `--pano-scroll-color`.
@@ -686,3 +688,5 @@ Point at a registered model and hold the trigger to rotate; use the thumbstick v
 Loss of an active controller pauses operations without enabling dwell. The WebXR session toolbar provides exit and an explicit gaze entry point; only that entry point accepts head dwell while waiting or paused. Host cursor/dwell restrictions, forced input policies, and `chrome={false}` remain authoritative. The first selection after recovery only switches input. Transient system inputs do not cause gaze fallback when absent. Basic hand selection keeps directional controls; two-hand scaling, near touch, and moving panels are outside this version.
 
 When Immersive Web Emulator takes ownership of the canvas, the preview fills the browser content area and keeps its display dimensions and aspect ratio aligned with the emulator as the window resizes. It does not request browser fullscreen. Exiting restores the embedded canvas styles. Native WebXR headsets, MobileVR, and non-XR desktop presentation are unchanged.
+
+Media elements with `data-pano-media-controls="none"` opt out of automatic VR controls, allowing host buttons such as narration Listen to remain the only controls. Explicit control components still work. All media and model control groups use the same circular-button theme. Exiting VR preserves playback in an open dialog.

package/docs/dialogs.zh-CN.md

@@ -677,6 +677,8 @@ const controller = usePanoMediaController(mediaRef);
 
 自动接管的每个弹窗视频会在视频下方显示独立的圆形按钮控制栏，顺序为后退、播放／暂停、前进、静音／取消静音，以及平台支持时的减音量、加音量。控制栏在布局中独立占位，不遮挡画面或后续正文，随视频一起滚动并遵守所在滚动容器的裁剪。媒体按钮默认大小为 48px，浅蓝色线框图标为 24px，间距和内边距均为 8px；窄区域中按钮可换行。这些默认值同时适用于自动视频控制栏和显式 `PanoMediaControls`（包括音频），仍可使用现有控件 CSS 变量覆盖按钮大小、间距和内边距。退出 VR 时移除自动控件占位，原视频节点和普通模式原生控件保持不变。播放前优先显示封面；没有封面时临时提示 `preload="auto"` 尝试获取首帧，不播放、不跳转、不重新加载，也不创建第二个视频元素。没有可读取画面时显示明确的视频占位。封面需要同源或允许 CORS；不可读取的媒体不会污染面板纹理。关闭弹窗或退出 VR 时释放预览资源并恢复临时预载设置。
 
+媒体快照提供可选字段 `hasAudio`：`true` 表示有音轨，`false` 表示无音轨，省略或 `undefined` 表示未知。库自有控件仅在确认无音轨时隐藏静音和音量控制；未知状态及原有自定义 controller 保留控件。检测能力取决于浏览器，包含静音内容的音轨仍算有音轨。音量限制在 0～1（0%～100%），不额外增益；音量命令忽略非有限数值。切换媒体源和音轨变化时会更新检测结果。
+
 凝视完成 `cursorDwellMs` 后，播放、静音、复位执行一次；跳转、音量和模型持续执行；滚动每隔 700 毫秒执行一小步，移开即停。默认跳转每秒 10 秒（`seekSpeed`），音量每秒 0.25（`volumeSpeed`），滚动每秒 0.2 个可见区域（`speed`），每步默认移动 0.14 个可见区域。`PanoScrollControls.repeatIntervalMs` 可调整重复间隔；间隔计时不受组件重新渲染影响，移开会清零，重新凝视需重新完成 dwell。关闭、退出 VR、禁用和失焦会停止操作。凝视不能替代浏览器要求的可信用户手势；音量不可调整的平台（包括 iOS）隐藏音量加减按钮，仍可静音；支持调节的平台在音量上下限禁用对应按钮。
 
 通过 `--pano-scroll-opacity`、`--pano-scroll-active-opacity`、`--pano-scroll-background` 和 `--pano-scroll-color` 定制滚动按钮。
@@ -692,3 +694,5 @@ const controller = usePanoMediaController(mediaRef);
 使用过的手柄断开或丢失跟踪后暂停操作，不自动恢复凝视。默认 WebXR 会话工具栏提供退出和主动启用凝视的入口；等待输入或暂停时，只有启用凝视入口接受头部停留选择。宿主关闭 `cursor` 或自动凝视、固定输入策略、关闭 `chrome` 时，界面尊重宿主设置。恢复手柄的第一次明确选择只切换输入，不点击内容。系统瞬时输入不会因暂时消失而触发凝视回退。基础手势保留方向按钮；不提供双手缩放、近距离触碰或移动面板。
 
 Immersive Web Emulator 接管画布时，模拟预览会铺满浏览器内容区域，使用与模拟器相同的显示尺寸及宽高比，并随窗口变化更新。不会调用浏览器 Fullscreen API。退出后恢复原 viewer 的画布样式；真实 WebXR 头显、手机 VR 和桌面非 XR 模式不受此适配影响。
+
+媒体元素可设置 `data-pano-media-controls="none"` 退出自动 VR 控件，由宿主的 Listen 等按钮控制；显式控件仍然有效。媒体与模型按钮组统一采用圆形按钮样式。退出 VR 时保留仍打开弹窗中的媒体播放状态。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericchen1990/pano-view",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "React components for panoramic viewing experiences.",
   "author": "Eric Chen",
   "license": "MIT",