@woosh/meep-engine 3.36.0 → 3.37.0

package/package.json

@@ -6,7 +6,7 @@
   "description": "Advanced 3D game engine",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.36.0",
+  "version": "3.37.0",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",

package/src/engine/input/devices/XRInputDevice.d.ts

@@ -1,23 +1,27 @@
 /**
- * Session-owned WebXR input. Safe to construct/start without a browser, XR support, or hardware.
- * This device never requests a session or schedules frames. The application owns both:
+ * WebXR input from an application-owned session and frame loop. Construction and {@link start} work
+ * without a browser, XR support, or hardware; all controls remain neutral until a session is attached.
+ * Engine starts this device automatically. Call {@link start} when using it independently.
  *
- * @example
- *   engine.devices.xr.setSession(session, referenceSpace);
- *   // In the session's requestAnimationFrame callback, before gameplay reads input:
- *   engine.devices.xr.poll(frame);
- *   // Ordinary Vector1 and Signal bindings, valid even before a session exists:
- *   engine.devices.xr.right.select.onChanged.add(amount => { });
- *   engine.devices.xr.right.select.completed.add(() => { });
+ * {@link left}, {@link right} and {@link none} are stable slots, each retaining the oldest available
+ * source of that handedness. {@link sources} contains a separate handle for every live source.
+ * Control objects retain their identity when a slot changes source, so bindings survive disconnection.
+ *
+ * Removal, session replacement/end, {@link stop}, and a blurred or hidden session clear controls and
+ * cancel unfinished actions. Completed actions are not cancelled. Binding a slot midway through an
+ * action does not replay it. Tracking loss clears poses while preserving controls and action state.
  *
- * left/right/none are stable slots, each retaining the oldest available source of that handedness.
- * sources contains every live source, keyed internally by native object identity (never gamepad.index).
- * A slot swap neutralises its old controls and cancels unfinished actions before adopting new hardware.
- * Completed actions are not cancelled. Binding a slot midway through an action does not replay it.
+ * Lifecycle changes requested inside a signal handler take effect after the current update.
+ * Recursive {@link poll} calls are ignored. Frames are consumed synchronously and never retained.
  *
- * Lifecycle changes requested by signal handlers take effect after the current update. This keeps a
- * stop/session replacement from being overwritten by the remainder of that update. Native frames are
- * consumed synchronously and never retained. Recursive poll calls are ignored.
+ * @example
+ *   const xr = engine.devices.xr;
+ *   // Bind application callbacks before or after attaching a session.
+ *   xr.right.select.onChanged.add(setToolPressure);
+ *   xr.right.select.completed.add(useTool);
+ *   xr.setSession(session, referenceSpace);
+ *   // In the session's existing requestAnimationFrame callback, before reading input:
+ *   xr.poll(frame);
  */
 export class XRInputDevice {
     /** @readonly */
@@ -26,30 +30,54 @@ export class XRInputDevice {
     readonly right: XRInputHandle;
     /** @readonly */
     readonly none: XRInputHandle;
-    /** @readonly @type {XRInputHandle[]} Read only; membership is owned by the device. */
+    /**
+     * All connected source handles. Do not modify membership.
+     * @readonly
+     * @type {XRInputHandle[]}
+     */
     readonly sources: XRInputHandle[];
     /** @readonly */
     readonly on: {
-        /** @type {Signal} Dispatches the connected XRInputHandle. */
+        /**
+         * Dispatches the connected XRInputHandle after its initial sample.
+         * @type {Signal}
+         */
         connected: Signal;
-        /** @type {Signal} Dispatches the XRInputHandle, already neutral and detached. */
+        /**
+         * Dispatches the XRInputHandle after its controls are cleared and its source is detached.
+         * @type {Signal}
+         */
         disconnected: Signal;
     };
-    /** @readonly @type {import('./xr/XRInputTypes.js').XRSession|null} Change through setSession. */
+    /**
+     * Attached session, or null. Change through {@link setSession}.
+     * @readonly
+     * @type {import('./xr/XRInputTypes.js').XRSession|null}
+     */
     readonly session: import('./xr/XRInputTypes.js').XRSession | null;
-    /** @readonly @type {EventTarget|null} Change through setReferenceSpace. */
+    /**
+     * Space in which poses are reported, or null. Change through {@link setReferenceSpace}.
+     * @readonly
+     * @type {EventTarget|null}
+     */
     readonly referenceSpace: EventTarget | null;
     get isRunning(): boolean;
+    /** Start listening to the configured session. Safe to call repeatedly. */
     start(): void;
     /** Detach without ending the application's native XRSession. */
     stop(): void;
     /**
-     * May be called before start. Null detaches; attaching does not request permission or own session.end().
+     * Attach an existing session. May be called before {@link start}. Pass null to detach.
+     * The application remains responsible for requesting and ending the native session.
      * @param {import('./xr/XRInputTypes.js').XRSession|null} session
      * @param {EventTarget|null} [referenceSpace=null] Null still samples controls, with invalid poses.
      */
     setSession(session: import('./xr/XRInputTypes.js').XRSession | null, referenceSpace?: EventTarget | null): void;
-    /** @param {EventTarget|null} referenceSpace */
+    /**
+     * Change the space used for poses. Existing poses become invalid until the next frame.
+     * Pass null to disable pose sampling while continuing to sample controls.
+     * @param {EventTarget|null} referenceSpace
+     */
     setReferenceSpace(referenceSpace: EventTarget | null): void;
     /**
      * No-op without a running session. Otherwise call only within that session's active frame callback.

package/src/engine/input/devices/XRInputDevice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"XRInputDevice.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/XRInputDevice.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IACI,gBAAgB;IAChB,6BAA2B;IAC3B,gBAAgB;IAChB,8BAA4B;IAC5B,gBAAgB;IAChB,6BAA2B;IAC3B,sFAAsF;IACtF,kBADqB,aAAa,EAAE,CACvB;IACb,gBAAgB;IAChB;QACI,6DAA6D;mBAAlD,MAAM;QAEjB,iFAAiF;sBAAtE,MAAM;MAEnB;IAOF,iGAAiG;IACjG,kBADqB,OAAO,sBAAsB,EAAE,SAAS,GAAC,IAAI,CACnD;IACf,2EAA2E;IAC3E,yBADqB,WAAW,GAAC,IAAI,CACf;IAOtB,yBAAyC;IAEzC,cAiBC;IAED,gEAAgE;IAChE,aAYC;IAED;;;;OAIG;IACH,oBAHW,OAAO,sBAAsB,EAAE,SAAS,GAAC,IAAI,mBAC7C,WAAW,GAAC,IAAI,QA4B1B;IAED,+CAA+C;IAC/C,kCADY,WAAW,GAAC,IAAI,QAuB3B;IAED;;;OAGG;IACH,aAFW,OAAO,sBAAsB,EAAE,OAAO,QAehD;;CAsNJ;8BA/X6B,uBAAuB;mBADlC,uCAAuC"}
+{"version":3,"file":"XRInputDevice.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/XRInputDevice.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IACI,gBAAgB;IAChB,6BAA2B;IAE3B,gBAAgB;IAChB,8BAA4B;IAE5B,gBAAgB;IAChB,6BAA2B;IAE3B;;;;OAIG;IACH,kBAFU,aAAa,EAAE,CAEZ;IAEb,gBAAgB;IAChB;QACI;;;WAGG;mBADO,MAAM;QAIhB;;;WAGG;sBADO,MAAM;MAGlB;IAUF;;;;OAIG;IACH,kBAFU,OAAO,sBAAsB,EAAE,SAAS,GAAC,IAAI,CAExC;IAEf;;;;OAIG;IACH,yBAFU,WAAW,GAAC,IAAI,CAEJ;IAYtB,yBAEC;IAED,0EAA0E;IAC1E,cAiBC;IAED,gEAAgE;IAChE,aAYC;IAED;;;;;OAKG;IACH,oBAHW,OAAO,sBAAsB,EAAE,SAAS,GAAC,IAAI,mBAC7C,WAAW,GAAC,IAAI,QAwC1B;IAED;;;;OAIG;IACH,kCAFW,WAAW,GAAC,IAAI,QA8B1B;IAED;;;OAGG;IACH,aAFW,OAAO,sBAAsB,EAAE,OAAO,QAkBhD;;CA0OJ;8BA3d6B,uBAAuB;mBADlC,uCAAuC"}

package/src/engine/input/devices/XRInputDevice.js

@@ -1,68 +1,115 @@
 import { assert } from "../../../core/assert.js";
+import { Deque } from "../../../core/collection/queue/Deque.js";
 import Signal from "../../../core/events/signal/Signal.js";
 import { XRInputHandle } from "./xr/XRInputHandle.js";
+import { XRHandedness } from "./xr/XRHandedness.js";
+import { XRVisibilityState } from "./xr/XRVisibilityState.js";
 
-const SESSION_EVENTS = ['inputsourceschange', 'selectstart', 'select', 'selectend',
-    'squeezestart', 'squeeze', 'squeezeend', 'visibilitychange', 'end'];
+const SESSION_EVENTS = [
+    'inputsourceschange',
+    'selectstart', 'select', 'selectend',
+    'squeezestart', 'squeeze', 'squeezeend',
+    'visibilitychange',
+    'end'
+];
 
 /**
- * Session-owned WebXR input. Safe to construct/start without a browser, XR support, or hardware.
- * This device never requests a session or schedules frames. The application owns both:
+ * WebXR input from an application-owned session and frame loop. Construction and {@link start} work
+ * without a browser, XR support, or hardware; all controls remain neutral until a session is attached.
+ * Engine starts this device automatically. Call {@link start} when using it independently.
  *
- * @example
- *   engine.devices.xr.setSession(session, referenceSpace);
- *   // In the session's requestAnimationFrame callback, before gameplay reads input:
- *   engine.devices.xr.poll(frame);
- *   // Ordinary Vector1 and Signal bindings, valid even before a session exists:
- *   engine.devices.xr.right.select.onChanged.add(amount => { });
- *   engine.devices.xr.right.select.completed.add(() => { });
+ * {@link left}, {@link right} and {@link none} are stable slots, each retaining the oldest available
+ * source of that handedness. {@link sources} contains a separate handle for every live source.
+ * Control objects retain their identity when a slot changes source, so bindings survive disconnection.
+ *
+ * Removal, session replacement/end, {@link stop}, and a blurred or hidden session clear controls and
+ * cancel unfinished actions. Completed actions are not cancelled. Binding a slot midway through an
+ * action does not replay it. Tracking loss clears poses while preserving controls and action state.
  *
- * left/right/none are stable slots, each retaining the oldest available source of that handedness.
- * sources contains every live source, keyed internally by native object identity (never gamepad.index).
- * A slot swap neutralises its old controls and cancels unfinished actions before adopting new hardware.
- * Completed actions are not cancelled. Binding a slot midway through an action does not replay it.
+ * Lifecycle changes requested inside a signal handler take effect after the current update.
+ * Recursive {@link poll} calls are ignored. Frames are consumed synchronously and never retained.
  *
- * Lifecycle changes requested by signal handlers take effect after the current update. This keeps a
- * stop/session replacement from being overwritten by the remainder of that update. Native frames are
- * consumed synchronously and never retained. Recursive poll calls are ignored.
+ * @example
+ *   const xr = engine.devices.xr;
+ *   // Bind application callbacks before or after attaching a session.
+ *   xr.right.select.onChanged.add(setToolPressure);
+ *   xr.right.select.completed.add(useTool);
+ *   xr.setSession(session, referenceSpace);
+ *   // In the session's existing requestAnimationFrame callback, before reading input:
+ *   xr.poll(frame);
  */
 export class XRInputDevice {
     /** @readonly */
     left = new XRInputHandle();
+
     /** @readonly */
     right = new XRInputHandle();
+
     /** @readonly */
     none = new XRInputHandle();
-    /** @readonly @type {XRInputHandle[]} Read only; membership is owned by the device. */
+
+    /**
+     * All connected source handles. Do not modify membership.
+     * @readonly
+     * @type {XRInputHandle[]}
+     */
     sources = [];
+
     /** @readonly */
     on = {
-        /** @type {Signal} Dispatches the connected XRInputHandle. */
+        /**
+         * Dispatches the connected XRInputHandle after its initial sample.
+         * @type {Signal}
+         */
         connected: new Signal(),
-        /** @type {Signal} Dispatches the XRInputHandle, already neutral and detached. */
+
+        /**
+         * Dispatches the XRInputHandle after its controls are cleared and its source is detached.
+         * @type {Signal}
+         */
         disconnected: new Signal()
     };
 
     #slots = [this.left, this.right, this.none];
+
     /** @type {Map<import('./xr/XRInputTypes.js').XRInputSource, XRInputHandle>} */
     #handles = new Map();
+
     /** @type {XRInputHandle[]} */
     #connected = [];
-    /** @readonly @type {import('./xr/XRInputTypes.js').XRSession|null} Change through setSession. */
+
+    /**
+     * Attached session, or null. Change through {@link setSession}.
+     * @readonly
+     * @type {import('./xr/XRInputTypes.js').XRSession|null}
+     */
     session = null;
-    /** @readonly @type {EventTarget|null} Change through setReferenceSpace. */
+
+    /**
+     * Space in which poses are reported, or null. Change through {@link setReferenceSpace}.
+     * @readonly
+     * @type {EventTarget|null}
+     */
     referenceSpace = null;
+
     #running = false;
     #busy = false;
     #draining = false;
-    /** @type {Array<()=>void>} Only reentrant configuration changes are queued, never frames. */
-    #pending = [];
 
-    get isRunning() { return this.#running; }
+    /**
+     * Configuration changes requested during an update; frames are never queued.
+     * @type {Deque<()=>void>}
+     */
+    #pending = new Deque();
+
+    get isRunning() {
+        return this.#running;
+    }
 
+    /** Start listening to the configured session. Safe to call repeatedly. */
     start() {
         if (this.#busy) {
-            this.#pending.push(() => this.start());
+            this.#pending.addLast(() => this.start());
             return;
         }
         if (this.#running) {
@@ -82,7 +129,7 @@ export class XRInputDevice {
     /** Detach without ending the application's native XRSession. */
     stop() {
         if (this.#busy) {
-            this.#pending.push(() => this.stop());
+            this.#pending.addLast(() => this.stop());
             return;
         }
         this.#busy = true;
@@ -95,17 +142,30 @@ export class XRInputDevice {
     }
 
     /**
-     * May be called before start. Null detaches; attaching does not request permission or own session.end().
+     * Attach an existing session. May be called before {@link start}. Pass null to detach.
+     * The application remains responsible for requesting and ending the native session.
      * @param {import('./xr/XRInputTypes.js').XRSession|null} session
      * @param {EventTarget|null} [referenceSpace=null] Null still samples controls, with invalid poses.
      */
     setSession(session, referenceSpace = null) {
         assert.defined(session, 'session');
+
         if (session === null) {
             referenceSpace = null;
+        } else {
+            assert.isFunction(session.addEventListener, 'session.addEventListener');
+            assert.isFunction(session.removeEventListener, 'session.removeEventListener');
+            assert.isArrayLike(session.inputSources, 'session.inputSources');
+            assert.enum(session.visibilityState, XRVisibilityState, 'session.visibilityState');
         }
+
+        if (referenceSpace !== null) {
+            assert.isFunction(referenceSpace.addEventListener, 'referenceSpace.addEventListener');
+            assert.isFunction(referenceSpace.removeEventListener, 'referenceSpace.removeEventListener');
+        }
+
         if (this.#busy) {
-            this.#pending.push(() => this.setSession(session, referenceSpace));
+            this.#pending.addLast(() => this.setSession(session, referenceSpace));
             return;
         }
         if (session === this.session) {
@@ -116,7 +176,7 @@ export class XRInputDevice {
         try {
             this.#detach();
             this.session = session;
-            this.referenceSpace = session === null ? null : referenceSpace;
+            this.referenceSpace = referenceSpace;
             if (this.#running) {
                 this.#listen(true);
                 this.#reconcile();
@@ -127,11 +187,21 @@ export class XRInputDevice {
         }
     }
 
-    /** @param {EventTarget|null} referenceSpace */
+    /**
+     * Change the space used for poses. Existing poses become invalid until the next frame.
+     * Pass null to disable pose sampling while continuing to sample controls.
+     * @param {EventTarget|null} referenceSpace
+     */
     setReferenceSpace(referenceSpace) {
         assert.defined(referenceSpace, 'referenceSpace');
+
+        if (referenceSpace !== null) {
+            assert.isFunction(referenceSpace.addEventListener, 'referenceSpace.addEventListener');
+            assert.isFunction(referenceSpace.removeEventListener, 'referenceSpace.removeEventListener');
+        }
+
         if (this.#busy) {
-            this.#pending.push(() => this.setReferenceSpace(referenceSpace));
+            this.#pending.addLast(() => this.setReferenceSpace(referenceSpace));
             return;
         }
         if (referenceSpace === this.referenceSpace) {
@@ -161,7 +231,10 @@ export class XRInputDevice {
             return;
         }
         assert.defined(frame, 'frame');
+        assert.notNull(frame, 'frame');
         assert.equal(frame.session, this.session, 'frame.session');
+        assert.isFunction(frame.getPose, 'frame.getPose');
+
         this.#busy = true;
         try {
             this.#reconcile();
@@ -242,12 +315,15 @@ export class XRInputDevice {
                 this.#connected.push(handle);
             }
         }
-        this.#bindSlot(this.left, 'left');
-        this.#bindSlot(this.right, 'right');
-        this.#bindSlot(this.none, 'none');
+        this.#bindSlot(this.left, XRHandedness.Left);
+        this.#bindSlot(this.right, XRHandedness.Right);
+        this.#bindSlot(this.none, XRHandedness.None);
     }
 
-    /** @param {XRInputHandle} slot @param {string} handedness */
+    /**
+     * @param {XRInputHandle} slot
+     * @param {string} handedness
+     */
     #bindSlot(slot, handedness) {
         if (slot.connected) {
             return;
@@ -263,7 +339,7 @@ export class XRInputDevice {
 
     /** @param {import('./xr/XRInputTypes.js').XRFrame|null} frame */
     #sample(frame) {
-        if (this.session !== null && this.session.visibilityState === 'visible') {
+        if (this.session !== null && this.session.visibilityState === XRVisibilityState.Visible) {
             for (let i = 0; i < this.sources.length; i++) {
                 this.sources[i].sample(frame, this.referenceSpace);
             }
@@ -310,7 +386,7 @@ export class XRInputDevice {
 
     #onReset = () => {
         if (this.#busy) {
-            this.#pending.push(() => this.#onReset());
+            this.#pending.addLast(() => this.#onReset());
             return;
         }
         this.#busy = true;
@@ -333,22 +409,23 @@ export class XRInputDevice {
                 return;
             }
             this.#reconcile();
-            const frame = event.frame === undefined ? null : event.frame;
+            const frame = event.frame ?? null;
+            const inputSource = event.inputSource ?? null;
             if (frame !== null && frame.session !== this.session) {
                 return;
             }
             this.#sample(frame);
-            if (this.session.visibilityState !== 'visible' || event.inputSource === undefined) {
+            if (this.session.visibilityState !== XRVisibilityState.Visible || inputSource === null) {
                 return;
             }
-            const handle = this.#handles.get(event.inputSource);
+            const handle = this.#handles.get(inputSource);
             if (handle === undefined) {
                 return;
             }
             this.#actionEvent(handle, event.type);
             for (let i = 0; i < this.#slots.length; i++) {
                 const slot = this.#slots[i];
-                if (slot.nativeSource === event.inputSource) {
+                if (slot.nativeSource === inputSource) {
                     this.#actionEvent(slot, event.type);
                 }
             }
@@ -357,15 +434,30 @@ export class XRInputDevice {
         }
     };
 
-    /** @param {XRInputHandle} handle @param {string} type */
+    /**
+     * @param {XRInputHandle} handle
+     * @param {string} type
+     */
     #actionEvent(handle, type) {
         switch (type) {
-            case 'selectstart': handle.select.begin(); break;
-            case 'select': handle.select.complete(); break;
-            case 'selectend': handle.select.end(); break;
-            case 'squeezestart': handle.squeeze.begin(); break;
-            case 'squeeze': handle.squeeze.complete(); break;
-            case 'squeezeend': handle.squeeze.end(); break;
+            case 'selectstart':
+                handle.select.begin();
+                break;
+            case 'select':
+                handle.select.complete();
+                break;
+            case 'selectend':
+                handle.select.end();
+                break;
+            case 'squeezestart':
+                handle.squeeze.begin();
+                break;
+            case 'squeeze':
+                handle.squeeze.complete();
+                break;
+            case 'squeezeend':
+                handle.squeeze.end();
+                break;
         }
     }
 
@@ -376,8 +468,9 @@ export class XRInputDevice {
         }
         this.#draining = true;
         try {
-            while (this.#pending.length > 0) {
-                this.#pending.shift()();
+            while (!this.#pending.isEmpty()) {
+                const change = this.#pending.removeFirst();
+                change();
             }
         } finally {
             this.#draining = false;

package/src/engine/input/devices/xr/XRGamepadMapping.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Mapping values exposed by an XR input source's gamepad.
+ */
+export type XRGamepadMapping = string;
+/**
+ * Mapping values exposed by an XR input source's gamepad.
+ * @readonly
+ * @enum {string}
+ */
+export const XRGamepadMapping: Readonly<{
+    Unmapped: "";
+    Standard: "xr-standard";
+}>;
+//# sourceMappingURL=XRGamepadMapping.d.ts.map

package/src/engine/input/devices/xr/XRGamepadMapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XRGamepadMapping.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRGamepadMapping.js"],"names":[],"mappings":";;;+BAGU,MAAM;AAHhB;;;;GAIG;AACH;;;GAGG"}

package/src/engine/input/devices/xr/XRGamepadMapping.js

@@ -0,0 +1,9 @@
+/**
+ * Mapping values exposed by an XR input source's gamepad.
+ * @readonly
+ * @enum {string}
+ */
+export const XRGamepadMapping = Object.freeze({
+    Unmapped: '',
+    Standard: 'xr-standard'
+});

package/src/engine/input/devices/xr/XRHandedness.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Native XRInputSource handedness values.
+ */
+export type XRHandedness = string;
+/**
+ * Native XRInputSource handedness values.
+ * @readonly
+ * @enum {string}
+ */
+export const XRHandedness: Readonly<{
+    None: "none";
+    Left: "left";
+    Right: "right";
+}>;
+//# sourceMappingURL=XRHandedness.d.ts.map

package/src/engine/input/devices/xr/XRHandedness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XRHandedness.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRHandedness.js"],"names":[],"mappings":";;;2BAGU,MAAM;AAHhB;;;;GAIG;AACH;;;;GAIG"}

package/src/engine/input/devices/xr/XRHandedness.js

@@ -0,0 +1,10 @@
+/**
+ * Native XRInputSource handedness values.
+ * @readonly
+ * @enum {string}
+ */
+export const XRHandedness = Object.freeze({
+    None: 'none',
+    Left: 'left',
+    Right: 'right'
+});

package/src/engine/input/devices/xr/XRInputAction.d.ts

@@ -1,24 +1,37 @@
 /**
- * Observable amount of a select/squeeze action, in [0, 1]. Read x and subscribe to onChanged as with
- * any Vector1. The device owns mutation. Scalar changes never manufacture an action outcome.
+ * Observable amount of a select/squeeze action, in [0, 1]. Read {@link x} and subscribe to
+ * {@link onChanged} as with any Vector1. The device owns mutation.
  *
- * Completion/cancellation describe a browser interaction, independently of the amount. There is no
- * public up/down state or inferred threshold. The private lifecycle only pairs native events so an
- * interrupted interaction is cancelled once and an already completed one is never cancelled.
+ * {@link valueSource} identifies a native button amount or an event-derived 0/1 value.
+ * {@link completed} fires on native action completion; {@link cancelled} fires when an unfinished
+ * interaction ends or is interrupted. Each interaction has at most one outcome. Amount changes alone
+ * do not complete or cancel an action.
  */
 export class XRInputAction extends Vector1 {
-    /** @readonly @type {Signal} No arguments. */
+    /**
+     * Successful native action completion. Dispatches no arguments.
+     * @readonly
+     * @type {Signal}
+     */
     readonly completed: Signal;
-    /** @readonly @type {Signal} No arguments. */
+    /**
+     * An unfinished interaction ended or was interrupted. Dispatches no arguments.
+     * @readonly
+     * @type {Signal}
+     */
     readonly cancelled: Signal;
-    /** @type {XRInputValueSource} Do not modify directly. */
+    /**
+     * Origin of the current amount. Do not modify directly.
+     * @type {XRInputValueSource}
+     */
     valueSource: XRInputValueSource;
     /**
+     * Store the supplied amount and its source.
      * @internal
-     * @param {XRInputValueSource} source
-     * @param {number} value
+     * @param {number} [value=0]
+     * @param {XRInputValueSource} [source=XRInputValueSource.Unavailable]
      */
-    update(source: XRInputValueSource, value: number): void;
+    update(value?: number, source?: XRInputValueSource): void;
     /** @internal Called only for a native start, never inferred from the amount. */
     begin(): void;
     /** @internal A completion without an observed start is not replayed after a rebind/interruption. */

package/src/engine/input/devices/xr/XRInputAction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"XRInputAction.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRInputAction.js"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH;IACI,6CAA6C;IAC7C,oBADqB,MAAM,CACF;IAEzB,6CAA6C;IAC7C,oBADqB,MAAM,CACF;IAEzB,yDAAyD;IACzD,aADW,kBAAkB,CACgB;IAO7C;;;;OAIG;IACH,eAHW,kBAAkB,SAClB,MAAM,QAKhB;IAED,gFAAgF;IAChF,cAQC;IAED,oGAAoG;IACpG,iBAMC;IAED,gBAAgB;IAChB,YASC;IAED,mGAAmG;IACnG,cAKC;IAED,gBAAgB;IAChB,0BAKC;;CACJ;wBAnFuB,kCAAkC;mBADvC,0CAA0C;mCAE1B,yBAAyB"}
+{"version":3,"file":"XRInputAction.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRInputAction.js"],"names":[],"mappings":"AAgBA;;;;;;;;GAQG;AACH;IACI;;;;OAIG;IACH,oBAFU,MAAM,CAES;IAEzB;;;;OAIG;IACH,oBAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,aAFU,kBAAkB,CAEiB;IAM7C;;;;;OAKG;IACH,eAHW,MAAM,WACN,kBAAkB,QAS5B;IAED,gFAAgF;IAChF,cASC;IAED,oGAAoG;IACpG,iBAOC;IAED,gBAAgB;IAChB,YAWC;IAED,mGAAmG;IACnG,cAIC;IAED,gBAAgB;IAChB,0BAKC;;CACJ;wBAjHuB,kCAAkC;mBADvC,0CAA0C;mCAE1B,yBAAyB"}