hud-11: one pointer owner (dominant hand, press takes over) + hand isolation

ADDENDUM 12. The pointer was symmetric: whoever acted last owned it, and when
neither had acted the first source in runtime order won - the LEFT hand on this
runtime, so a right-handed user's guide line sat on the non-dominant hand.

- state.handPref ('right'|'left', default 'right') is the default owner. Set from the
  pre-VR panel (操作 -> 主用手), persisted. pickPointerCand(cands, preferKey,
  ownerKey, prefHand): acting source owns the shot (or MISSes), else owner aiming ->
  preferred hand aiming -> any hand aiming -> owner -> preferred hand -> first.
- A press takes the pointer over and the owner sticks while it is aiming.
- Hold exclusion: while a grab/viewDrag started by one source is active, a press from
  the other source is ignored (pressAt "IGNORED (other hand is holding)").
- Source-matched release: pointerUp(src) only ends the hold src started. It used to be
  argument-less, so either hand's release cancelled the other hand's subtitle grab or
  picture pan. grab/viewDrag now carry a key; onSelectEnd(ev) and pollGamepads pass
  their source.
- dropStaleHolds() runs each frame and ends a hold whose source left
  session.inputSources (tracking lost), so nothing sticks.

New diagnostics: stats.handPref, stats.owner.

Verified with injected synthetic input sources:
  default (right), both on panel     pointer hand:right HIT 0.78,0.50  (was hand:left)
  handPref=left, fresh session       pointer hand:left  HIT 0.22,0.50
  left press, release                owner hand:left, stays left
  right holds picture-pan, left press    "IGNORED (other hand is holding)"
  right holds picture-pan, LEFT release  viewDrag stays armed (drag survives)
  right holds picture-pan, RIGHT release viewDrag reset (tap) (drag ends)
This commit is contained in:
2026-10-12 21:36:03 +08:00
parent e18c3d51bd
commit 0713f35513
5 changed files with 250 additions and 49 deletions
+53 -3
View File
@@ -1,11 +1,12 @@
# Jellyfin Web VR180 — 项目交接文档
> 给新对话用。读完这份就能接手,不需要重新调查环境。
> 最后更新:已部署版本 `6bf1021`(`NS.version = hud-10`;ADDENDUM 6 字幕深度/大小解耦
> 最后更新:已部署版本 `917fde`(`NS.version = hud-11`;ADDENDUM 6 字幕深度/大小解耦
> + 7 唤出门限/前面板精简 + 7b 锁按钮与「锁定」面板模式 + 8/8b 画面搬迁(实时拖动)
> + 9 rAF 代理修复(VR 内字幕不再冻结)+ 普通/双目字幕自动识别
> + 10 原生(SRT 等)字幕由插件自绘到 HUD;布局覆盖不再持久化
> + 11 指针跟随正在操作/瞄准的那只手;11b 光标落在引导线上 + 点击归属操作手)
> + 11 指针跟随正在操作/瞄准的那只手;11b 光标落在引导线上 + 点击归属操作手
> + 12 单一指针主人(主用手默认,按下接管,按住互斥,抬起按源匹配))
>
> ⚠️ **Jellyfin web 注册了 service worker**(`serviceworker.js`,scope `/web/`),会把
> `index.html` 缓存在 SW cache 里。重新部署后如果只是普通刷新,浏览器可能仍用旧的
@@ -417,7 +418,7 @@ subMode / subCanvasSize / subCrop / subTex / subOpacity / subPlacement
subLockAngle / subAngleDeg / subTextDeg / subYOverZ ← ADDENDUM 6
subLayout / subDual / subEyeW / subCopyND / subCenterInk ← ADDENDUM 9
subSource / subNativeText ← ADDENDUM 10
activeSrc / pressSrc / pressPtr ← ADDENDUM 11
activeSrc / pressSrc / pressPtr / handPref ← ADDENDUM 11/12
ctlSubsOn / ctlSubDist / ctlSubAngle / ctlSubLock ← 控制条实际画出的值
ctlLock / ctlMode / ctlHold / pressAt / lastActivate ← ADDENDUM 7/7b 锁、面板保持与唤出判定
videoYaw / videoPitch / videoRotMode / videoTransformWritable ← ADDENDUM 8/8b 画面搬迁
@@ -730,3 +731,52 @@ Object.defineProperty(XRSession.prototype,'inputSources',{configurable:true,get:
面板外右手按下 pressSrc hand:right pressPtr "hand:right nohit"
pressAt "MISS (no hit on the panel)" (没有用左手位置)
```
---
## 17. ADDENDUM 12 — 单一指针“主人”:主用手默认,按下接管(已部署 `917fde` / `hud-11`)
之前的指针是**对称**的:谁最后操作谁拥有;谁都没操作时用「运行时第一个源」——本设备上就是**左手**,
所以右撇子一抬手引导线就在非惯用手上。而且两只手会互相打扰彼此的按住操作。
### 17.1 单一主人(像鼠标只有一个光标)
`pickPointerCand(cands, preferKey, ownerKey, prefHand)`:
```
preferKey(正在操作的那个源) → 就是它;取不到 → null ⇒ 这次按下 MISS
主人且正瞄面板 → 主人
主用手且正瞄面板 → 主用手
任一只正瞄面板的手 → 它
主人(没瞄面板) → 主人
主用手(没瞄面板) → 主用手
→ 第一个源
```
- **`state.handPref`**(`'right' | 'left'`,默认 `'right'`)= 指针的默认主人(惯用手)。
在**进 VR 前的面板**「操作 → 主用手」里设置,持久化在 `jfvr.settings.v1`。会话开始生效;
会话中主人只会粘滞。
- **按下即接管**(`preferKey`),之后主人粘在那只手上(只要它在瞄面板)。
### 17.2 两只手不再互相打扰
- **按住期间互斥**:某只手发起的长按/拖动(`grab` / `viewDrag`)进行中时,**另一只手的按下被忽略**
(`stats.pressAt = 'IGNORED (other hand is holding)'`)。
- **抬起按源匹配**:`pointerUp(src)` 只结束 `src` 自己发起的那次抓取/拖动。之前它是无参的,
所以**任一只手松手都会取消另一只手的字幕抓拖/画面搬迁**。现在 `onSelectEnd(ev)` 和
`pollGamepads` 都会传源,`grab` / `viewDrag` 各自带 `key`。
- **失效收尾**:`dropStaleHolds()` 每帧检查,若发起抓取的那只手从 `session.inputSources` 消失
(手部追踪丢失)就主动结束,避免永远没有 release 事件而卡住。
新增诊断:`stats.handPref`、`stats.owner`(= `stats.activeSrc`),以及已有的 `pressSrc` / `pressPtr`。
### 17.3 实测(注入合成输入源,活动会话)
```
默认(handPref=right),两手都在面板上 pointer hand:right HIT 0.78,0.50 (原来是 hand:left)
handPref=left(持久化后重开会话) pointer hand:left HIT 0.22,0.50
左手按下后松开 主人 hand:left,之后仍是 left
右手按住画面拖动条,左手按下 pressAt "IGNORED (other hand is holding)"
右手按住画面拖动条,左手松开 viewDrag 仍 "armed"(拖动存活)
右手按住画面拖动条,右手松开 viewDrag "reset (tap)"(拖动结束)
```