hud-7: live picture pan; fix the reset crash; tap-to-reset / hold-to-drag

Reported after hud-6:
  触发复位后直接崩溃了;我拖动后,我希望画面立刻就有反应,而不是我松手之后才改变。
  按住0.5s后拖动才是拖动,否则算复位

1. Why the picture only moved on release — a bad probe
The transform-write probe compared quaternion COMPONENTS. q and -q are the same
rotation and a runtime may hand back a renormalised quaternion, so a perfectly
capable runtime could be judged "read-only". When it was, the drag took the
rebuild branch, and that branch was throttled to "on release only" — hence the
picture sitting still until the finger came up. The probe now compares the
POSITION (exact, no sign ambiguity).

2. Two mechanisms, auto-selected and mutually exclusive
   'transform' -> layer.transform = q              (one write per change)
   'space'     -> layer.space = refSpace.getOffsetReferenceSpace(q)
                     (the recentering path every WebXR app uses; a layer pose is
                      recomputed from its space each frame)
   'rebuild'   -> recreate the media layer (manual escape hatch, "兼容" in the 2D panel)
createVideoLayer() only bakes the transform in for 'rebuild' — otherwise the
probe's own write would apply the aim twice. layer.transform is never written on
the 'space' path and vice versa. stats.videoRotMode / videoTransformWritable
report what was chosen.

3. The crash — create-before-destroy
The reset created the replacement layer BEFORE destroying the old one: two
XRMediaBinding equirect layers bound to one <video> element at once, then a
second rebuild microseconds later (release rebuilt, then reset rebuilt again),
took the browser down. A rebuild now runs in a setTimeout OUTSIDE the XR frame
callback, destroys FIRST, is throttled to 120 ms, and never queues more than one.
The transform/space paths never rebuild at all.

Two robustness holes found while testing:
  * videoSpaceFor() let a throwing getOffsetReferenceSpace() escape into the frame
    loop, where an exception kills the loop for good (rAF is only re-armed at the
    end of the callback) — a frozen session. Caught now, demoting to 'rebuild'.
  * the whole per-frame body is wrapped in try/catch for the same reason.

4. The gesture the owner asked for
   press the drag strip
     released before 500 ms, no movement -> RESET to dead ahead
     held past 500 ms, then moved        -> PAN
     held past 500 ms, never moved       -> RESET
The pan reference is captured when the hold threshold passes, not at the press,
so the hold itself cannot fling the picture; a ~1 deg dead zone absorbs jitter.
The strip now reads 点一下复位 · 按住 0.5s 再拖动 (the triple-tap hint is gone).

Verified offline against the real sources by three suites (build.py --check too):
  test-gesture  the state machine above, stubbed ray/clock: quick tap resets;
                hold-without-move resets; movement inside the hold window is
                ignored; after arming a +10/+5 deg ray move gives exactly
                +10/+5 deg; a pan does not reset; dead zone respected; pitch guard
  test-mech     position probe true/false for writable/ignored; transform
                strategy writes with no rebuild; space strategy assigns the offset
                space and leaves the transform alone; unchanged angle reuses the
                cached space; rebuild queues at most one and runs
                removeLayer -> createVideoLayer -> addLayer; throwing or absent
                getOffsetReferenceSpace is reported and falls back permanently
  test-ad8      quaternion aim/wrap/guard maths, panel bands on the 1440x520
                canvas, the strip's drawn readout, hold()
Deployed as mvp-5217a3 (hud-7); confirmed live on the Quest, errors empty.
This commit is contained in:
2026-10-11 21:47:55 +08:00
parent 263e270747
commit 7f751b7eee
7 changed files with 672 additions and 161 deletions
+101
View File
@@ -890,6 +890,10 @@ for the duration, otherwise the panel would auto-hide mid-drag.
## The one runtime unknown
> **SUPERSEDED by ADDENDUM 8b** — this probe compared quaternion components (sign- and
> normalisation-sensitive) and so could report "read-only" on a perfectly good runtime.
> The gesture also changed: tap = reset, hold 0.5 s then drag = pan.
`XREquirectLayer.transform` is settable per spec but a runtime may ignore the write. It
is probed once per session (write a known rotation, read it back):
@@ -934,3 +938,100 @@ x sweep 0.04..0.96 at y 0.05 -> no dead column
Live Quest 3 over CDP after deploy: `__JFVR.version = 'hud-6'`,
`state.videoYaw = state.videoPitch = 0`, `errors: []`.
---
# ADDENDUM 8b — live pan, the crash, and the real gesture
## Why the picture only moved on release
ADDENDUM 8 gated the transform write on a probe that compared **quaternion components**:
```js
live = Math.abs(readBack.orientation.y - q.y) < 1e-4 && Math.abs(readBack.orientation.w - q.w) < 1e-4;
```
`q` and `−q` are the same rotation, and a runtime may return a renormalised quaternion,
so this could answer "read-only" on a runtime that would have accepted the write. When it
did, the drag fell into the rebuild branch — which was throttled to release-only — so the
picture did not move until the finger came up.
The probe now compares the **position** (exact, no sign ambiguity):
```
layer.transform = XRRigidTransform({0.123, -0.456, 0.789}, identity)
writable <=> layer.transform.position equals that marker
```
## Two mechanisms, mutually exclusive
| `stats.videoRotMode` | Mechanism | Cost per change |
| --- | --- | --- |
| `transform` | `layer.transform = q` | one write |
| `space` | `layer.space = refSpace.getOffsetReferenceSpace(q)` | one space alloc |
| `rebuild` | recreate the media layer (manual escape hatch) | ~8/second max |
`space` exists because if the transform write is genuinely ignored,
`getOffsetReferenceSpace()` is the recentering path every WebXR app relies on, and a
layer's pose is recomputed from its space each frame. The two are never combined:
`createVideoLayer()` only bakes the transform in for the `rebuild` strategy, otherwise the
probe's write would double the aim. `stats.videoTransformWritable` shows the raw probe
result; the 2D panel's 「画面旋转: 自动 / 兼容」 can force the rebuild path.
## The crash, and every fix around it
The reset rebuilt the layer and created the replacement **before** destroying the old
one — two `XRMediaBinding` equirect layers on one `<video>` element at once, then a
second rebuild microseconds later (release rebuilt, then reset rebuilt again) took the
browser down.
A rebuild now: runs in a `setTimeout` **outside** the XR frame callback, **destroys
first**, is throttled to 120 ms, and never queues more than one. The `transform`/`space`
paths never rebuild at all, so the normal case cannot reach the crash.
Two robustness holes found while testing:
- `videoSpaceFor()` let a throwing `getOffsetReferenceSpace()` escape into the frame
loop, where an exception stops it for good (`requestAnimationFrame` is only re-armed at
the end of the callback) — a frozen session. It is caught, and the strategy demotes to
`rebuild`.
- The whole per-frame body is now wrapped in a try/catch for the same reason.
## The gesture
```
press the drag strip
├─ released before 500 ms with no movement -> RESET to dead ahead
├─ held past 500 ms, then moved -> PAN
└─ held past 500 ms, never moved -> RESET
```
The pan reference is taken **when the hold threshold passes**, not at the press, so the
hold itself cannot fling the picture; a ~1° dead zone absorbs hand jitter. The strip reads
`点一下复位 · 按住 0.5s 再拖动`.
## Verification
Everything below was asserted offline against the real sources with a stubbed ray, stubbed
WebXR layer objects and a stubbed clock (`build.py --check` passes as well):
```
test-gesture quick tap -> reset; hold-without-move -> reset; movement inside the hold
window ignored; after arming, +10°/+5° ray -> exactly +10°/+5°; a pan does
not reset; dead zone respected; pitch guard holds
test-mech probe true for a writable transform, false for an ignored one;
transform strategy: writes, no rebuild; space strategy: assigns the offset
space, leaves the transform alone, no rebuild; unchanged angle reuses the
cached space; rebuild strategy: one pending max, observed sequence
removeLayer -> createVideoLayer -> addLayer; throwing/absent
getOffsetReferenceSpace -> reported + permanent fallback
test-ad8 quaternion aim/wrap/guard maths, panel bands on the 1440x520 canvas,
the strip's drawn readout, hold()
```
Deployed as `mvp-5217a3` (hud-7) and confirmed live on the Quest.
## Still to confirm on device
Which of `transform` / `space` this runtime actually honours — `stats.videoRotMode` and
`stats.videoTransformWritable` say so once a session is running.