@iwsdk/xr-input 1.0.0-rc.0 → 1.0.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/dist/gamepad/generated-profiles.js.map +1 -1
  2. package/dist/gamepad/input-profiles.js.map +1 -1
  3. package/dist/gamepad/stateful-button-axes-device.js.map +1 -1
  4. package/dist/gamepad/stateful-gamepad.js.map +1 -1
  5. package/dist/index.d.ts +4 -0
  6. package/dist/index.d.ts.map +1 -1
  7. package/dist/index.js +3 -0
  8. package/dist/index.js.map +1 -1
  9. package/dist/pointer/cursor-visual.js.map +1 -1
  10. package/dist/pointer/filtered-eye-gaze.d.ts +48 -0
  11. package/dist/pointer/filtered-eye-gaze.d.ts.map +1 -0
  12. package/dist/pointer/filtered-eye-gaze.js +118 -0
  13. package/dist/pointer/filtered-eye-gaze.js.map +1 -0
  14. package/dist/pointer/gaze-candidate-provider.d.ts +58 -0
  15. package/dist/pointer/gaze-candidate-provider.d.ts.map +1 -0
  16. package/dist/pointer/gaze-conecaster.d.ts +130 -0
  17. package/dist/pointer/gaze-conecaster.d.ts.map +1 -0
  18. package/dist/pointer/gaze-conecaster.js +456 -0
  19. package/dist/pointer/gaze-conecaster.js.map +1 -0
  20. package/dist/pointer/gaze-pointer.d.ts +266 -0
  21. package/dist/pointer/gaze-pointer.d.ts.map +1 -0
  22. package/dist/pointer/gaze-pointer.js +865 -0
  23. package/dist/pointer/gaze-pointer.js.map +1 -0
  24. package/dist/pointer/grab-pointer.js.map +1 -1
  25. package/dist/pointer/multi-pointer.d.ts +21 -6
  26. package/dist/pointer/multi-pointer.d.ts.map +1 -1
  27. package/dist/pointer/multi-pointer.js +52 -12
  28. package/dist/pointer/multi-pointer.js.map +1 -1
  29. package/dist/pointer/ray-pointer.js.map +1 -1
  30. package/dist/pointer/touch-pointer.js.map +1 -1
  31. package/dist/pointer/visibility.js.map +1 -1
  32. package/dist/rig/xr-origin.d.ts +26 -0
  33. package/dist/rig/xr-origin.d.ts.map +1 -1
  34. package/dist/rig/xr-origin.js +25 -1
  35. package/dist/rig/xr-origin.js.map +1 -1
  36. package/dist/version.d.ts +1 -1
  37. package/dist/visual/adapter/base-visual-adapter.js.map +1 -1
  38. package/dist/visual/adapter/controller-visual-adapter.js.map +1 -1
  39. package/dist/visual/adapter/hand-visual-adapter.d.ts +9 -0
  40. package/dist/visual/adapter/hand-visual-adapter.d.ts.map +1 -1
  41. package/dist/visual/adapter/hand-visual-adapter.js +47 -9
  42. package/dist/visual/adapter/hand-visual-adapter.js.map +1 -1
  43. package/dist/visual/impl/animated-controller-hand.js.map +1 -1
  44. package/dist/visual/impl/animated-controller.js.map +1 -1
  45. package/dist/visual/impl/animated-hand.js.map +1 -1
  46. package/dist/visual/impl/base-impl.js.map +1 -1
  47. package/dist/visual/utils/flex-batched-mesh.js.map +1 -1
  48. package/dist/visual/utils/simple-batched-mesh.js.map +1 -1
  49. package/dist/xr-input-manager.d.ts +57 -1
  50. package/dist/xr-input-manager.d.ts.map +1 -1
  51. package/dist/xr-input-manager.js +285 -15
  52. package/dist/xr-input-manager.js.map +1 -1
  53. package/package.json +1 -1
@@ -0,0 +1,865 @@
1
+ import { createRayPointer } from '@pmndrs/pointer-events';
2
+ import { Vector3, Quaternion, Matrix4, Matrix3, Color, Mesh, CircleGeometry, MeshBasicMaterial, Object3D } from 'three';
3
+ import { FilteredEyeGaze } from './filtered-eye-gaze.js';
4
+ import { GazeConecaster } from './gaze-conecaster.js';
5
+ import { isObjectTreeVisible } from './visibility.js';
6
+
7
+ /**
8
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
9
+ *
10
+ * This source code is licensed under the MIT license found in the
11
+ * LICENSE file in the root directory of this source tree.
12
+ */
13
+ /**
14
+ * Locate the eye-tracking input source.
15
+ *
16
+ * The primary scan is the one the standalone WebXR eye-gaze diagnostic page
17
+ * uses verbatim — the gaze source is whichever entry of `session.inputSources`
18
+ * reports `targetRayMode === 'gaze'`. `trackedSources` is checked afterwards
19
+ * because some runtimes surface non-primary sources only there; the
20
+ * diagnostics log says which list produced the hit.
21
+ */
22
+ function findGazeSource(session) {
23
+ for (const source of session.inputSources) {
24
+ if (source.targetRayMode === 'gaze') {
25
+ return { source, fromTrackedSources: false };
26
+ }
27
+ }
28
+ if (session.trackedSources) {
29
+ for (const source of session.trackedSources) {
30
+ if (source.targetRayMode === 'gaze') {
31
+ return { source, fromTrackedSources: true };
32
+ }
33
+ }
34
+ }
35
+ return { source: undefined, fromTrackedSources: false };
36
+ }
37
+ /**
38
+ * Thresholds lifted from the standalone WebXR eye-gaze diagnostic page, so a
39
+ * verdict logged here means the same thing as a verdict shown there.
40
+ */
41
+ const GAZE_VERDICT = {
42
+ /** Gaze/head separation that proves the eye ray is genuinely independent. */
43
+ passAngleDeg: 1.5,
44
+ /** Below this, one frame's gaze and head rays count as "the same ray". */
45
+ identicalAngleDeg: 0.05,
46
+ /** Below this (millimetres), one frame's gaze and head origins coincide. */
47
+ identicalPositionMm: 0.5,
48
+ /** Ratio of identical frames that indicates a head-pose mapping bug. */
49
+ headLockedRatio: 0.95,
50
+ /** Max separation still counted as head-locked. */
51
+ headLockedAngleDeg: 0.1,
52
+ /** Minimum evidence before any negative verdict is logged. */
53
+ minSeconds: 3,
54
+ minFrames: 90,
55
+ };
56
+ const RAD_TO_DEG = 180 / Math.PI;
57
+ const diagForward = new Vector3();
58
+ const diagHeadForward = new Vector3();
59
+ const RETICLE_FORWARD = new Vector3(0, 0, 1);
60
+ function isIntentionalHeadDirectedPreview() {
61
+ const preview = globalThis.__IWSDK_TARGET_DEVICE_PREVIEW__;
62
+ return (preview === null || preview === void 0 ? void 0 : preview.active) === true && preview.gazeSimulation === 'head';
63
+ }
64
+ /**
65
+ * One-shot console diagnostics for the gaze pipeline.
66
+ *
67
+ * Eye tracking fails silently in several distinct ways — feature not granted,
68
+ * no gaze input source, source present but posed null, or a runtime that maps
69
+ * the gaze target ray onto the head pose. These can otherwise look like either
70
+ * missing or head-locked gaze, so each gets its own message with the
71
+ * remediation that actually applies. Every message fires at most once per
72
+ * state transition, so this is safe to leave on in a per-frame path.
73
+ */
74
+ class GazeDiagnostics {
75
+ constructor() {
76
+ this.sessionStart = -1;
77
+ this.loggedFeature = false;
78
+ this.loggedMissingSource = false;
79
+ this.loggedTrackedSourcesFallback = false;
80
+ this.loggedPoseThrow = false;
81
+ this.loggedNoTargets = false;
82
+ this.loggedVerdict = false;
83
+ this.loggedInconclusive = false;
84
+ this.sourcePresent = false;
85
+ /** Tri-state so the very first sample always logs its pose validity. */
86
+ this.poseValid = null;
87
+ // Head-versus-gaze separation stats, accumulated over valid poses only.
88
+ this.firstValidPoseAt = -1;
89
+ this.comparisonFrames = 0;
90
+ this.identicalFrames = 0;
91
+ this.maxAngleDeg = 0;
92
+ this.maxPositionMm = 0;
93
+ }
94
+ reset() {
95
+ this.sessionStart = -1;
96
+ this.loggedFeature = false;
97
+ this.loggedMissingSource = false;
98
+ this.loggedTrackedSourcesFallback = false;
99
+ this.loggedPoseThrow = false;
100
+ this.loggedNoTargets = false;
101
+ this.loggedVerdict = false;
102
+ this.loggedInconclusive = false;
103
+ this.sourcePresent = false;
104
+ this.poseValid = null;
105
+ this.firstValidPoseAt = -1;
106
+ this.comparisonFrames = 0;
107
+ this.identicalFrames = 0;
108
+ this.maxAngleDeg = 0;
109
+ this.maxPositionMm = 0;
110
+ }
111
+ /**
112
+ * @param time Monotonic seconds, matching {@link GazePointer.update}.
113
+ * @param xrOrigin Rig whose `eyeSpace`/`head` hold this frame's poses.
114
+ */
115
+ frame(time, xrOrigin, session, gazeSource, fromTrackedSources, posed) {
116
+ if (this.sessionStart < 0) {
117
+ this.sessionStart = time;
118
+ }
119
+ this.logFeature(session);
120
+ this.logSource(time, gazeSource, fromTrackedSources);
121
+ this.logPose(gazeSource, posed);
122
+ if (posed) {
123
+ this.compareWithHead(time, xrOrigin);
124
+ }
125
+ }
126
+ /** Nothing is gaze-eligible, so gaze can never hit anything. */
127
+ targets(count) {
128
+ if (count > 0) {
129
+ this.loggedNoTargets = false;
130
+ return;
131
+ }
132
+ if (this.loggedNoTargets) {
133
+ return;
134
+ }
135
+ this.loggedNoTargets = true;
136
+ console.info('[iwsdk][gaze] no ray-interactable targets are available, so the gaze ' +
137
+ 'cone has nothing to hit.');
138
+ }
139
+ poseThrew(error) {
140
+ if (this.loggedPoseThrow) {
141
+ return;
142
+ }
143
+ this.loggedPoseThrow = true;
144
+ console.warn('[iwsdk][gaze] frame.getPose(gazeSource.targetRaySpace) threw; tracked ' +
145
+ 'gaze is unavailable for this frame.', error);
146
+ }
147
+ /** Report whether the runtime actually granted `gaze-tracking`. */
148
+ logFeature(session) {
149
+ if (this.loggedFeature) {
150
+ return;
151
+ }
152
+ this.loggedFeature = true;
153
+ // `enabledFeatures` is not in every UA's lib.dom typing yet.
154
+ const enabled = session
155
+ .enabledFeatures;
156
+ if (!enabled) {
157
+ console.info("[iwsdk][gaze] this browser doesn't expose session.enabledFeatures, " +
158
+ "so whether 'gaze-tracking' was granted can't be confirmed here. " +
159
+ 'Watch for the gaze XRInputSource message below instead.');
160
+ return;
161
+ }
162
+ const enabledFeatures = Array.from(enabled);
163
+ if (enabledFeatures.includes('gaze-tracking') ||
164
+ enabledFeatures.includes('eye-tracking')) {
165
+ console.info("[iwsdk][gaze] 'gaze-tracking' granted for this session.", {
166
+ enabledFeatures,
167
+ });
168
+ return;
169
+ }
170
+ console.warn("[iwsdk][gaze] 'gaze-tracking' was NOT granted for this session, so " +
171
+ 'tracked gaze is unavailable. Check that the project requests ' +
172
+ 'xr.features.gazeTracking, that this browser build exposes eye ' +
173
+ "tracking, and that the page's permissions policy allows " +
174
+ 'xr-spatial-tracking.', { enabledFeatures });
175
+ }
176
+ logSource(time, gazeSource, fromTrackedSources) {
177
+ const present = !!gazeSource;
178
+ if (present && fromTrackedSources && !this.loggedTrackedSourcesFallback) {
179
+ this.loggedTrackedSourcesFallback = true;
180
+ console.info('[iwsdk][gaze] gaze source found in session.trackedSources rather ' +
181
+ 'than session.inputSources.');
182
+ }
183
+ if (present !== this.sourcePresent) {
184
+ this.sourcePresent = present;
185
+ this.poseValid = null;
186
+ if (present) {
187
+ console.info('[iwsdk][gaze] gaze XRInputSource appeared.', {
188
+ profiles: Array.from(gazeSource.profiles),
189
+ handedness: gazeSource.handedness,
190
+ });
191
+ }
192
+ else {
193
+ console.warn('[iwsdk][gaze] the gaze XRInputSource disappeared; ' +
194
+ 'ordinary hand/controller far targeting is now active.');
195
+ }
196
+ return;
197
+ }
198
+ // Never showed up at all — distinct failure from "showed up then left".
199
+ if (!present &&
200
+ !this.loggedMissingSource &&
201
+ time - this.sessionStart >= GAZE_VERDICT.minSeconds) {
202
+ this.loggedMissingSource = true;
203
+ console.warn('[iwsdk][gaze] no XRInputSource with targetRayMode === "gaze" ' +
204
+ `appeared within ${GAZE_VERDICT.minSeconds}s of session start. ` +
205
+ 'Ordinary hand/controller far targeting remains active. Common causes: the ' +
206
+ 'feature was not granted, eye tracking is disabled in system ' +
207
+ 'settings, the headset has not been calibrated for this user, or ' +
208
+ 'the hardware has no eye tracking.');
209
+ }
210
+ }
211
+ logPose(gazeSource, posed) {
212
+ if (!gazeSource || posed === this.poseValid) {
213
+ return;
214
+ }
215
+ this.poseValid = posed;
216
+ if (posed) {
217
+ console.info('[iwsdk][gaze] eye pose is valid — real gaze data is flowing.');
218
+ }
219
+ else {
220
+ console.warn('[iwsdk][gaze] the gaze input source is present but ' +
221
+ 'frame.getPose(targetRaySpace) returned null, so tracked gaze is ' +
222
+ 'temporarily unavailable. Common causes: OS eye-tracking permission ' +
223
+ 'not granted, headset not calibrated, or hardware without eye tracking.');
224
+ }
225
+ }
226
+ /**
227
+ * Compare the tracked gaze ray against the head ray. A runtime can hand back
228
+ * a perfectly valid gaze pose that is just a copy of the viewer pose; that
229
+ * is indistinguishable from the fallback unless the two are measured.
230
+ */
231
+ compareWithHead(time, xrOrigin) {
232
+ if (this.loggedVerdict) {
233
+ return;
234
+ }
235
+ const eye = xrOrigin.eyeSpace;
236
+ const head = xrOrigin.head;
237
+ diagForward.set(0, 0, -1).applyQuaternion(eye.quaternion);
238
+ diagHeadForward.set(0, 0, -1).applyQuaternion(head.quaternion);
239
+ const dot = Math.min(1, Math.max(-1, diagForward.dot(diagHeadForward)));
240
+ const angleDeg = Math.acos(dot) * RAD_TO_DEG;
241
+ const positionMm = eye.position.distanceTo(head.position) * 1000;
242
+ if (this.firstValidPoseAt < 0) {
243
+ this.firstValidPoseAt = time;
244
+ }
245
+ this.comparisonFrames++;
246
+ this.maxAngleDeg = Math.max(this.maxAngleDeg, angleDeg);
247
+ this.maxPositionMm = Math.max(this.maxPositionMm, positionMm);
248
+ if (angleDeg < GAZE_VERDICT.identicalAngleDeg &&
249
+ positionMm < GAZE_VERDICT.identicalPositionMm) {
250
+ this.identicalFrames++;
251
+ }
252
+ if (this.maxAngleDeg >= GAZE_VERDICT.passAngleDeg) {
253
+ this.loggedVerdict = true;
254
+ console.info('[iwsdk][gaze] real eye movement observed — the gaze ray separates ' +
255
+ `from the head ray by up to ${this.maxAngleDeg.toFixed(2)}°.`);
256
+ return;
257
+ }
258
+ if (time - this.firstValidPoseAt < GAZE_VERDICT.minSeconds ||
259
+ this.comparisonFrames < GAZE_VERDICT.minFrames) {
260
+ return;
261
+ }
262
+ const identicalRatio = this.identicalFrames / this.comparisonFrames;
263
+ if (identicalRatio >= GAZE_VERDICT.headLockedRatio &&
264
+ this.maxAngleDeg < GAZE_VERDICT.headLockedAngleDeg &&
265
+ this.maxPositionMm < GAZE_VERDICT.identicalPositionMm) {
266
+ this.loggedVerdict = true;
267
+ if (isIntentionalHeadDirectedPreview()) {
268
+ console.info('[iwsdk][gaze] target-device preview is intentionally ' +
269
+ 'providing head-directed synthetic gaze.');
270
+ return;
271
+ }
272
+ console.warn('[iwsdk][gaze] the gaze target-ray pose matched the head pose on ' +
273
+ `${(identicalRatio * 100).toFixed(0)}% of ${this.comparisonFrames} ` +
274
+ `frames (max separation ${this.maxAngleDeg.toFixed(3)}°). Eye ` +
275
+ 'tracking is reporting poses, but the runtime is mapping ' +
276
+ 'XRTargetRaySpace onto the head pose, so gaze behaves as ' +
277
+ 'head-pointing. This is a runtime/build issue, not an app one.');
278
+ return;
279
+ }
280
+ if (!this.loggedInconclusive) {
281
+ this.loggedInconclusive = true;
282
+ console.info(`[iwsdk][gaze] inconclusive: only ${this.maxAngleDeg.toFixed(2)}° of ` +
283
+ `gaze/head separation over ${this.comparisonFrames} frames. Hold ` +
284
+ 'your head still and look far left and right to confirm real gaze.');
285
+ }
286
+ }
287
+ }
288
+ /**
289
+ * Singleton gaze pointer. Peer of {@link MultiPointer} in
290
+ * {@link XRInputManager}.
291
+ *
292
+ * @remarks
293
+ * - One global instance — gaze has no handedness.
294
+ * - Samples the WebXR gaze target ray itself via
295
+ * {@link GazePointer.sampleGazePose}, publishing the result to
296
+ * {@link XROrigin.eyeSpace}. The hand/controller ray owns far targeting when
297
+ * a gaze source is unavailable. {@link GazePointerOptions.diagnostics}
298
+ * explains the silent failure modes.
299
+ * - Candidate selection is delegated to a {@link GazeCandidateProvider};
300
+ * the default {@link GazeConecaster} does OBB cone membership and
301
+ * time-weighted dwell consensus while this pointer resolves surfaces with
302
+ * the same pmndrs ray intersector used for event delivery.
303
+ * - Selector composes either hand's pinch; once selecting, the other hand
304
+ * is ignored until release (per-hand mutual exclusion, matching Meta
305
+ * Interaction SDK's `HandGazeInteractor` semantics).
306
+ * - Drives a real `@pmndrs/pointer-events` pointer so UIKit panels click
307
+ * naturally on gaze-pinch.
308
+ * - Keeps its optional debug reticle hidden by default. Production feedback
309
+ * belongs on the hovered target, matching Meta Interaction SDK.
310
+ *
311
+ * @category Pointer
312
+ */
313
+ class GazePointer {
314
+ get trackingLossGraceSeconds() {
315
+ return this._trackingLossGraceSeconds;
316
+ }
317
+ set trackingLossGraceSeconds(value) {
318
+ this._trackingLossGraceSeconds = Number.isFinite(value)
319
+ ? Math.max(0, value)
320
+ : 0;
321
+ }
322
+ constructor(xrOrigin, scene, camera, options = {}) {
323
+ var _a, _b, _c, _d, _e, _f, _g;
324
+ this.xrOrigin = xrOrigin;
325
+ this.scene = scene;
326
+ this._trackingLossGraceSeconds = 5;
327
+ this.pointerState = {
328
+ source: 'gaze',
329
+ handedness: null,
330
+ };
331
+ this.filteredOrigin = new Vector3();
332
+ this.filteredQuaternion = new Quaternion();
333
+ this.rawOrigin = new Vector3();
334
+ this.rawQuaternion = new Quaternion();
335
+ this.direction = new Vector3();
336
+ this.aimDirection = new Vector3();
337
+ this.reticleOffset = new Vector3();
338
+ this.rayTarget = new Vector3();
339
+ this.rayUp = new Vector3();
340
+ this.handOrigin = new Vector3();
341
+ this.handQuaternion = new Quaternion();
342
+ this.worldRayQuaternion = new Quaternion();
343
+ this.handRelativeRayQuaternion = new Quaternion();
344
+ this.tmpQuat = new Quaternion();
345
+ this.lookMatrix = new Matrix4();
346
+ this.normalMatrix = new Matrix3();
347
+ this.conecasterCtx = {
348
+ origin: this.filteredOrigin,
349
+ direction: this.direction,
350
+ candidates: [],
351
+ intersectCandidate: (candidate, direction) => this.intersectCandidate(candidate, direction),
352
+ };
353
+ this.nativeEvent = { timeStamp: 0 };
354
+ this.buttonEvent = { timeStamp: 0, button: 0 };
355
+ this.currentHit = null;
356
+ this.heldHit = null;
357
+ this.heldByHand = null;
358
+ this.wasSelecting = false;
359
+ this.buttonDown = false;
360
+ this.heldFollowsHand = false;
361
+ this.hasAcquiredTrackedGaze = false;
362
+ this.gazeSource = null;
363
+ this.gazeSourcePresent = false;
364
+ this.lastTrackedPoseTime = Number.NEGATIVE_INFINITY;
365
+ this.diagnostics = new GazeDiagnostics();
366
+ this.provider = new GazeConecaster();
367
+ this.suppressWhenDirectPointerActive =
368
+ (_a = options.suppressWhenDirectPointerActive) !== null && _a !== void 0 ? _a : true;
369
+ this.pointerTransformFollowsHand =
370
+ (_b = options.pointerTransformFollowsHand) !== null && _b !== void 0 ? _b : true;
371
+ this.showDebugReticle = (_c = options.showDebugReticle) !== null && _c !== void 0 ? _c : false;
372
+ this.trackingLossGraceSeconds = (_d = options.trackingLossGraceSeconds) !== null && _d !== void 0 ? _d : 5;
373
+ this.diagnosticsEnabled = (_e = options.diagnostics) !== null && _e !== void 0 ? _e : true;
374
+ this.filter = new FilteredEyeGaze(options.filter);
375
+ this.reticleTrackedColor =
376
+ options.reticleColor instanceof Color
377
+ ? options.reticleColor.clone()
378
+ : new Color((_f = options.reticleColor) !== null && _f !== void 0 ? _f : 0xffffff);
379
+ const radius = (_g = options.reticleRadius) !== null && _g !== void 0 ? _g : 0.012;
380
+ this.reticle = new Mesh(new CircleGeometry(radius, 32), new MeshBasicMaterial({
381
+ color: this.reticleTrackedColor.clone(),
382
+ transparent: true,
383
+ opacity: 0.85,
384
+ depthWrite: false,
385
+ depthTest: false,
386
+ }));
387
+ this.reticle.renderOrder = Infinity;
388
+ this.reticle.visible = false;
389
+ this.reticle.name = 'gaze-reticle';
390
+ // Synthetic ray source for the @pmndrs Pointer. We can't use eyeSpace
391
+ // directly because we want the *filtered* pose, not the raw per-frame
392
+ // gaze. Manual matrix updates: we drive position/quaternion explicitly
393
+ // each frame from the filter output.
394
+ this.gazeRaySpace = new Object3D();
395
+ this.gazeRaySpace.name = 'gaze-ray-space';
396
+ this.gazeRaySpace.matrixAutoUpdate = false;
397
+ this.pointer = createRayPointer(() => camera, { current: this.gazeRaySpace }, this.pointerState,
398
+ // contextMenu lives on button 2; gaze never produces it. Disable to
399
+ // avoid spurious contextmenu events.
400
+ {
401
+ contextMenuButton: -1,
402
+ filter: isObjectTreeVisible,
403
+ });
404
+ // BVH-accelerated firstHitOnly raycast (matches hand RayPointer).
405
+ const raycaster = this.pointer.intersector.raycaster;
406
+ if (raycaster) {
407
+ raycaster.firstHitOnly = true;
408
+ }
409
+ }
410
+ /**
411
+ * Add or remove the pointer's rig nodes (debug reticle and ray space).
412
+ *
413
+ * The pointer is constructed eagerly by {@link XRInputManager} so systems can
414
+ * hold a stable reference, but an app that never uses gaze shouldn't pay for
415
+ * gaze geometry in every rig matrix walk — so nothing is parented until gaze
416
+ * is actually switched on.
417
+ */
418
+ setAttached(attached) {
419
+ if (attached) {
420
+ this.xrOrigin.add(this.reticle, this.gazeRaySpace);
421
+ }
422
+ else {
423
+ this.reticle.removeFromParent();
424
+ this.gazeRaySpace.removeFromParent();
425
+ }
426
+ }
427
+ /**
428
+ * Read the gaze target ray off the live frame and write it into
429
+ * {@link XROrigin.eyeSpace}.
430
+ *
431
+ * This mirrors the standalone WebXR eye-gaze diagnostic page's probe: find
432
+ * the input source whose `targetRayMode` is `'gaze'`, then pose its
433
+ * `targetRaySpace` against the frame's reference space, tolerating a throw.
434
+ * The source can exist while `getPose` returns null (uncalibrated headset,
435
+ * withheld permission), so source presence and pose validity are tracked
436
+ * separately. A missing or invalid pose clears the current gaze pose so stale
437
+ * tracking can never be used for targeting.
438
+ *
439
+ * Call once per frame before {@link GazePointer.update}.
440
+ */
441
+ sampleGazePose(time, context) {
442
+ var _a;
443
+ const { frame, referenceSpace, session } = context;
444
+ const { source, fromTrackedSources } = findGazeSource(session);
445
+ const nextGazeSource = source !== null && source !== void 0 ? source : null;
446
+ if (nextGazeSource !== this.gazeSource) {
447
+ // Grace belongs to one uninterrupted source lifetime. A source that is
448
+ // removed or replaced must earn ownership again with a valid pose.
449
+ this.hasAcquiredTrackedGaze = false;
450
+ this.lastTrackedPoseTime = Number.NEGATIVE_INFINITY;
451
+ this.gazeSource = nextGazeSource;
452
+ }
453
+ this.gazeSourcePresent = source != null;
454
+ this.xrOrigin.clearGaze();
455
+ let pose = null;
456
+ if (source) {
457
+ try {
458
+ pose = (_a = frame.getPose(source.targetRaySpace, referenceSpace)) !== null && _a !== void 0 ? _a : null;
459
+ }
460
+ catch (error) {
461
+ if (this.diagnosticsEnabled) {
462
+ this.diagnostics.poseThrew(error);
463
+ }
464
+ }
465
+ }
466
+ if (pose) {
467
+ this.xrOrigin.applyTrackedEyePose(pose.transform);
468
+ this.hasAcquiredTrackedGaze = true;
469
+ this.lastTrackedPoseTime = time;
470
+ }
471
+ if (this.diagnosticsEnabled) {
472
+ this.diagnostics.frame(time, this.xrOrigin, session, source, fromTrackedSources, !!pose);
473
+ }
474
+ }
475
+ /**
476
+ * Whether gaze mode should own far targeting this frame.
477
+ *
478
+ * This mirrors ISDK's mode/source distinction: a valid pose activates gaze;
479
+ * then a short grace period keeps the mode active when a frame's pose is
480
+ * invalid (for example, a blink), while targeting itself clears. WebXR does
481
+ * not expose a separate pose-validity signal, so source enumeration defines
482
+ * the lifetime of that grace period. Removing the source hands far targeting
483
+ * back to hands/controllers immediately; the grace period applies only to
484
+ * temporary pose invalidity (for example, a blink).
485
+ */
486
+ ownsFarTargeting(time) {
487
+ if (!this.gazeSourcePresent) {
488
+ return false;
489
+ }
490
+ if (this.xrOrigin.gazeOrigin === 'tracked') {
491
+ return true;
492
+ }
493
+ return (this.hasAcquiredTrackedGaze &&
494
+ time - this.lastTrackedPoseTime <= this.trackingLossGraceSeconds);
495
+ }
496
+ /** Whether this frame has a pose that is safe to use for fresh targeting. */
497
+ canTarget() {
498
+ return this.xrOrigin.gazeOrigin === 'tracked';
499
+ }
500
+ /**
501
+ * Swap the candidate provider at runtime (e.g. a multi-cone or dwell-only
502
+ * provider). The previous provider is reset and detached.
503
+ */
504
+ setCandidateProvider(provider) {
505
+ this.provider.reset();
506
+ this.provider = provider;
507
+ }
508
+ update(targetingAvailable, dt, time, input) {
509
+ this.nativeEvent.timeStamp = time * 1000;
510
+ // Source removal is a mode transition, not transient tracking loss. End a
511
+ // gaze-started gesture before hand/controller far targeting resumes.
512
+ if (!this.gazeSourcePresent && !targetingAvailable && this.heldByHand) {
513
+ this.releaseSelect(true);
514
+ }
515
+ if (!targetingAvailable && !this.heldByHand) {
516
+ this.provider.reset();
517
+ this.filter.reset();
518
+ this.currentHit = null;
519
+ this.reticle.visible = false;
520
+ this.releaseAndDisable();
521
+ return;
522
+ }
523
+ let releasedSelect = false;
524
+ if (this.heldByHand) {
525
+ const hand = this.heldByHand;
526
+ const pinchEnded = input.pinchEnd[hand];
527
+ const targetAvailable = this.isHeldTargetAvailable(input.candidates);
528
+ if (pinchEnded || !input.pinchActive[hand] || !targetAvailable) {
529
+ // A real pinch-end is an up/click. Tracking loss, reset, removal, or
530
+ // semantic invisibility interrupts the gesture and must cancel it.
531
+ this.releaseSelect(!pinchEnded || !targetAvailable);
532
+ releasedSelect = true;
533
+ }
534
+ else {
535
+ this.driveHeldPointer();
536
+ this.updateReticle();
537
+ return;
538
+ }
539
+ }
540
+ // A transient invalid eye pose clears hover immediately, matching ISDK,
541
+ // but does not interrupt a selection that was already handed off to the
542
+ // pinching hand. Once that gesture ends there is no stale pose from which
543
+ // to start a new selection.
544
+ if (!targetingAvailable) {
545
+ this.provider.reset();
546
+ this.filter.reset();
547
+ this.currentHit = null;
548
+ this.reticle.visible = false;
549
+ this.releaseAndDisable();
550
+ return;
551
+ }
552
+ if (this.diagnosticsEnabled) {
553
+ this.diagnostics.targets(input.candidates.length);
554
+ }
555
+ // World-space pose of the (raw) gaze, then smoothed in-place. This runs
556
+ // only with a current targeting pose, so a transient invalid frame cannot
557
+ // contaminate the eye filter with the previous valid gaze pose.
558
+ this.xrOrigin.eyeSpace.getWorldPosition(this.rawOrigin);
559
+ this.xrOrigin.eyeSpace.getWorldQuaternion(this.rawQuaternion);
560
+ this.filter.filter(this.rawOrigin, this.rawQuaternion, Math.max(dt, 1 / 240), this.filteredOrigin, this.filteredQuaternion);
561
+ this.direction.set(0, 0, -1).applyQuaternion(this.filteredQuaternion);
562
+ const externallySuppressed = this.suppressWhenDirectPointerActive &&
563
+ (input.directPointerActive.left || input.directPointerActive.right);
564
+ if (externallySuppressed) {
565
+ this.currentHit = null;
566
+ this.reticle.visible = false;
567
+ this.commitNoTarget();
568
+ }
569
+ else {
570
+ this.conecasterCtx.candidates = input.candidates;
571
+ this.currentHit = this.provider.update(time, dt, this.conecasterCtx);
572
+ if (this.currentHit) {
573
+ this.commitHit(this.currentHit);
574
+ }
575
+ else {
576
+ this.commitNoTarget();
577
+ }
578
+ }
579
+ if (!releasedSelect) {
580
+ this.processSelector(input);
581
+ }
582
+ this.updateReticle();
583
+ }
584
+ /** Resolve one candidate through the same intersector used for dispatch. */
585
+ intersectCandidate(candidate, direction) {
586
+ this.setRayFromDirection(this.filteredOrigin, direction, this.filteredQuaternion);
587
+ const intersection = this.computeScopedIntersection([candidate]);
588
+ return intersection.object.isVoidObject ? null : intersection;
589
+ }
590
+ /** Install the provider's authoritative intersection and emit one move. */
591
+ commitHit(hit) {
592
+ this.ensurePointerEnabled();
593
+ this.setRayWorldPose(hit.intersection.pointerPosition, hit.intersection.pointerQuaternion);
594
+ this.pointer.setIntersection(hit.intersection);
595
+ this.pointer.commit(this.nativeEvent, true);
596
+ }
597
+ /** Commit a void hit so the previous target receives out/leave events. */
598
+ commitNoTarget() {
599
+ this.currentHit = null;
600
+ this.ensurePointerEnabled();
601
+ this.setRayFromDirection(this.filteredOrigin, this.direction, this.filteredQuaternion);
602
+ const intersection = this.computeScopedIntersection([]);
603
+ this.pointer.setIntersection(intersection);
604
+ this.pointer.commit(this.nativeEvent, true);
605
+ }
606
+ computeScopedIntersection(descendants) {
607
+ const scene = this.scene;
608
+ const previous = scene.interactableDescendants;
609
+ scene.interactableDescendants = descendants;
610
+ try {
611
+ return this.pointer.computeIntersection('pointer', this.scene, this.nativeEvent);
612
+ }
613
+ finally {
614
+ scene.interactableDescendants = previous;
615
+ }
616
+ }
617
+ ensurePointerEnabled() {
618
+ if (!this.pointer.getEnabled()) {
619
+ this.pointer.setEnabled(true, this.nativeEvent, false);
620
+ }
621
+ }
622
+ /** Pose the synthetic ray in world space while it remains parented to the rig. */
623
+ setRayWorldPose(origin, quaternion) {
624
+ this.xrOrigin.updateWorldMatrix(true, false);
625
+ this.gazeRaySpace.position.copy(origin);
626
+ this.xrOrigin.worldToLocal(this.gazeRaySpace.position);
627
+ this.xrOrigin.getWorldQuaternion(this.tmpQuat).invert();
628
+ this.gazeRaySpace.quaternion.copy(this.tmpQuat).multiply(quaternion);
629
+ this.gazeRaySpace.updateMatrix();
630
+ this.gazeRaySpace.updateMatrixWorld(true);
631
+ }
632
+ /** Build a ray pose whose -Z axis follows `direction`. */
633
+ setRayFromDirection(origin, direction, upQuaternion) {
634
+ this.rayTarget.copy(origin).add(direction);
635
+ this.rayUp.set(0, 1, 0).applyQuaternion(upQuaternion);
636
+ this.lookMatrix.lookAt(origin, this.rayTarget, this.rayUp);
637
+ this.worldRayQuaternion.setFromRotationMatrix(this.lookMatrix);
638
+ this.setRayWorldPose(origin, this.worldRayQuaternion);
639
+ }
640
+ /** Release event state before disabling or detaching the pointer. */
641
+ releaseAndDisable() {
642
+ this.releaseSelect(true);
643
+ if (!this.pointer.getEnabled()) {
644
+ return;
645
+ }
646
+ this.pointer.exit(this.nativeEvent);
647
+ this.pointer.setEnabled(false, this.nativeEvent, false);
648
+ }
649
+ updateReticle() {
650
+ var _a, _b;
651
+ if (!this.showDebugReticle) {
652
+ this.reticle.visible = false;
653
+ return;
654
+ }
655
+ const intersection = this.pointer.getIntersection();
656
+ if (!intersection || intersection.object.isVoidObject) {
657
+ this.reticle.visible = false;
658
+ return;
659
+ }
660
+ if (this.reticle.material.color.getHex() !== this.reticleTrackedColor.getHex()) {
661
+ this.reticle.material.color.copy(this.reticleTrackedColor);
662
+ }
663
+ this.reticleOffset.copy(intersection.point);
664
+ this.xrOrigin.worldToLocal(this.reticleOffset);
665
+ this.reticle.position.copy(this.reticleOffset);
666
+ const normal = (_a = intersection.normal) !== null && _a !== void 0 ? _a : (_b = intersection.face) === null || _b === void 0 ? void 0 : _b.normal;
667
+ if (normal) {
668
+ this.normalMatrix.getNormalMatrix(intersection.object.matrixWorld);
669
+ this.rayUp.copy(normal).applyNormalMatrix(this.normalMatrix).normalize();
670
+ this.reticle.quaternion.setFromUnitVectors(RETICLE_FORWARD, this.rayUp);
671
+ this.xrOrigin.getWorldQuaternion(this.tmpQuat).invert();
672
+ this.reticle.quaternion.premultiply(this.tmpQuat);
673
+ }
674
+ // Scale reticle gently with distance for legibility.
675
+ const s = Math.max(0.6, Math.min(2, intersection.distance));
676
+ this.reticle.scale.setScalar(s);
677
+ this.reticle.visible = true;
678
+ }
679
+ processSelector(input) {
680
+ const hand = input.pinchStart.left
681
+ ? 'left'
682
+ : input.pinchStart.right
683
+ ? 'right'
684
+ : null;
685
+ if (!hand || !this.currentHit) {
686
+ return;
687
+ }
688
+ const gazeHit = this.currentHit;
689
+ this.heldByHand = hand;
690
+ this.pointerState.handedness = hand;
691
+ this.heldFollowsHand = false;
692
+ let selectIntersection = gazeHit.intersection;
693
+ if (this.pointerTransformFollowsHand) {
694
+ const handSpace = this.xrOrigin.raySpaces[hand];
695
+ handSpace.updateWorldMatrix(true, false);
696
+ handSpace.getWorldPosition(this.handOrigin);
697
+ handSpace.getWorldQuaternion(this.handQuaternion);
698
+ this.aimDirection.copy(gazeHit.intersection.point).sub(this.handOrigin);
699
+ if (this.aimDirection.lengthSq() > 1e-12) {
700
+ this.aimDirection.normalize();
701
+ this.setRayFromDirection(this.handOrigin, this.aimDirection, this.handQuaternion);
702
+ const handIntersection = this.computeScopedIntersection([
703
+ gazeHit.object,
704
+ ]);
705
+ if (!handIntersection.object.isVoidObject &&
706
+ handIntersection.object === gazeHit.intersection.object) {
707
+ selectIntersection = handIntersection;
708
+ this.handRelativeRayQuaternion
709
+ .copy(this.handQuaternion)
710
+ .invert()
711
+ .multiply(handIntersection.pointerQuaternion);
712
+ this.heldFollowsHand = true;
713
+ }
714
+ else {
715
+ this.setRayWorldPose(gazeHit.intersection.pointerPosition, gazeHit.intersection.pointerQuaternion);
716
+ }
717
+ }
718
+ }
719
+ this.heldHit = {
720
+ object: gazeHit.object,
721
+ intersection: selectIntersection,
722
+ angularDistance: gazeHit.angularDistance,
723
+ };
724
+ this.wasSelecting = true;
725
+ this.pointer.setIntersection(selectIntersection);
726
+ // The hover path already emitted this frame's move. This commit only needs
727
+ // to install the hand-origin intersection before a synchronous capture in
728
+ // `down()`; enter/leave bookkeeping still runs if the leaf changed.
729
+ this.pointer.commit(this.nativeEvent, false);
730
+ this.buttonEvent.timeStamp = this.nativeEvent.timeStamp;
731
+ this.buttonEvent.button = 0;
732
+ this.buttonDown = true;
733
+ try {
734
+ this.pointer.down(this.buttonEvent);
735
+ }
736
+ catch (_a) {
737
+ this.releaseSelect(true);
738
+ }
739
+ }
740
+ driveHeldPointer() {
741
+ if (!this.heldHit || !this.heldByHand) {
742
+ return;
743
+ }
744
+ if (this.pointer.getPointerCapture()) {
745
+ if (this.heldFollowsHand) {
746
+ const handSpace = this.xrOrigin.raySpaces[this.heldByHand];
747
+ handSpace.updateWorldMatrix(true, false);
748
+ handSpace.getWorldPosition(this.handOrigin);
749
+ handSpace.getWorldQuaternion(this.handQuaternion);
750
+ this.worldRayQuaternion
751
+ .copy(this.handQuaternion)
752
+ .multiply(this.handRelativeRayQuaternion);
753
+ this.setRayWorldPose(this.handOrigin, this.worldRayQuaternion);
754
+ }
755
+ else {
756
+ this.setRayWorldPose(this.heldHit.intersection.pointerPosition, this.heldHit.intersection.pointerQuaternion);
757
+ }
758
+ this.pointer.move(this.scene, this.nativeEvent);
759
+ return;
760
+ }
761
+ // Plain clickable targets generally do not capture. Keep their select-time
762
+ // intersection stable so small hand motion during the pinch cannot turn a
763
+ // valid down into an up on the void object.
764
+ this.setRayWorldPose(this.heldHit.intersection.pointerPosition, this.heldHit.intersection.pointerQuaternion);
765
+ this.pointer.setIntersection(this.heldHit.intersection);
766
+ this.pointer.commit(this.nativeEvent, true);
767
+ }
768
+ isHeldTargetAvailable(candidates) {
769
+ var _a;
770
+ const object = (_a = this.heldHit) === null || _a === void 0 ? void 0 : _a.object;
771
+ return (!!object && isObjectTreeVisible(object) && candidates.includes(object));
772
+ }
773
+ releaseSelect(cancelled = false) {
774
+ if (this.buttonDown) {
775
+ this.buttonEvent.timeStamp = this.nativeEvent.timeStamp;
776
+ this.buttonEvent.button = 0;
777
+ if (cancelled) {
778
+ try {
779
+ this.pointer.cancel(this.nativeEvent);
780
+ }
781
+ catch (_a) { }
782
+ // Pointer.cancel emits the correct event but the upstream pointer
783
+ // keeps its button/capture bookkeeping. Clear it while disabled so no
784
+ // pointerup or click is dispatched for an interrupted gesture.
785
+ const wasEnabled = this.pointer.getEnabled();
786
+ if (wasEnabled) {
787
+ this.pointer.setEnabled(false, this.nativeEvent, true);
788
+ }
789
+ try {
790
+ this.pointer.up(this.buttonEvent);
791
+ }
792
+ catch (_b) { }
793
+ if (wasEnabled) {
794
+ this.pointer.setEnabled(true, this.nativeEvent, false);
795
+ }
796
+ }
797
+ else {
798
+ try {
799
+ this.pointer.up(this.buttonEvent);
800
+ }
801
+ catch (_c) { }
802
+ }
803
+ this.buttonDown = false;
804
+ }
805
+ this.heldHit = null;
806
+ this.heldByHand = null;
807
+ this.pointerState.handedness = null;
808
+ this.heldFollowsHand = false;
809
+ this.wasSelecting = false;
810
+ }
811
+ /** Current dwell winner's root Object3D (null if none/suppressed). */
812
+ getCurrentTarget() {
813
+ var _a, _b;
814
+ return (_b = (_a = this.currentHit) === null || _a === void 0 ? void 0 : _a.object) !== null && _b !== void 0 ? _b : null;
815
+ }
816
+ /** Which hand initiated the active gaze-pinch select. */
817
+ getHeldByHand() {
818
+ return this.heldByHand;
819
+ }
820
+ /** True while a gaze-pinch select is held. */
821
+ isSelecting() {
822
+ return this.wasSelecting;
823
+ }
824
+ /** World-space gaze origin (post-filter). */
825
+ getOrigin() {
826
+ return this.filteredOrigin;
827
+ }
828
+ /** World-space gaze direction (post-filter, unit length). */
829
+ getDirection() {
830
+ return this.direction;
831
+ }
832
+ /**
833
+ * Whether a valid gaze pose is available this frame.
834
+ */
835
+ getGazeOrigin() {
836
+ return this.xrOrigin.gazeOrigin;
837
+ }
838
+ /**
839
+ * Reset filter, provider, selector and diagnostic state. Call when gaze
840
+ * becomes invalid (session ended, eye tracking lost) so we don't carry stale
841
+ * samples, and so the next session re-reports its gaze verdict.
842
+ */
843
+ reset() {
844
+ this.diagnostics.reset();
845
+ this.provider.reset();
846
+ this.filter.reset();
847
+ this.currentHit = null;
848
+ this.hasAcquiredTrackedGaze = false;
849
+ this.gazeSource = null;
850
+ this.gazeSourcePresent = false;
851
+ this.lastTrackedPoseTime = Number.NEGATIVE_INFINITY;
852
+ this.reticle.visible = false;
853
+ this.releaseAndDisable();
854
+ }
855
+ dispose() {
856
+ this.releaseAndDisable();
857
+ this.reticle.geometry.dispose();
858
+ this.reticle.material.dispose();
859
+ this.reticle.removeFromParent();
860
+ this.gazeRaySpace.removeFromParent();
861
+ }
862
+ }
863
+
864
+ export { GazePointer };
865
+ //# sourceMappingURL=gaze-pointer.js.map