@woosh/meep-engine 3.36.0 → 3.38.0

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

@@ -1,46 +1,75 @@
+import { assert } from "../../../../core/assert.js";
 import Signal from "../../../../core/events/signal/Signal.js";
 import { Vector1 } from "../../../../core/geom/Vector1.js";
 import { XRInputValueSource } from "./XRInputValueSource.js";
 
 /**
- * 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.
+ * Native interaction lifecycle, independent of pressure.
+ * @readonly
+ * @enum {number}
+ */
+const InteractionState = {
+    Idle: 0,
+    Started: 1,
+    Completed: 2
+};
+
+/**
+ * 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}
+     */
     completed = new Signal();
 
-    /** @readonly @type {Signal} No arguments. */
+    /**
+     * An unfinished interaction ended or was interrupted. Dispatches no arguments.
+     * @readonly
+     * @type {Signal}
+     */
     cancelled = new Signal();
 
-    /** @type {XRInputValueSource} Do not modify directly. */
+    /**
+     * Origin of the current amount. Do not modify directly.
+     * @type {XRInputValueSource}
+     */
     valueSource = XRInputValueSource.Unavailable;
 
-    /** 0: idle, 1: awaiting outcome, 2: completed, awaiting native end. */
-    #interaction = 0;
+    #interaction = InteractionState.Idle;
 
     #cancelled = false;
 
     /**
+     * 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, value) {
+    update(value = 0, source = XRInputValueSource.Unavailable) {
+        assert.greaterThanOrEqual(value, 0, 'value >= 0');
+        assert.lessThanOrEqual(value, 1, 'value <= 1');
+        assert.enum(source, XRInputValueSource, 'source');
+
         this.valueSource = source;
-        this.set(source === XRInputValueSource.Gamepad ? value : source === XRInputValueSource.Action && this.#interaction !== 0 ? 1 : 0);
+        this.set(value);
     }
 
     /** @internal Called only for a native start, never inferred from the amount. */
     begin() {
-        if (this.#interaction !== 0) {
+        if (this.#interaction !== InteractionState.Idle) {
             return;
         }
-        this.#interaction = 1;
+
+        this.#interaction = InteractionState.Started;
         if (this.valueSource === XRInputValueSource.Action) {
             this.set(1);
         }
@@ -48,20 +77,23 @@ export class XRInputAction extends Vector1 {
 
     /** @internal A completion without an observed start is not replayed after a rebind/interruption. */
     complete() {
-        if (this.#interaction !== 1) {
+        if (this.#interaction !== InteractionState.Started) {
             return;
         }
-        this.#interaction = 2;
+
+        this.#interaction = InteractionState.Completed;
         this.completed.send0();
     }
 
     /** @internal */
     end() {
-        const cancelled = this.#interaction === 1;
-        this.#interaction = 0;
+        const cancelled = this.#interaction === InteractionState.Started;
+        this.#interaction = InteractionState.Idle;
+
         if (this.valueSource === XRInputValueSource.Action) {
             this.set(0);
         }
+
         if (cancelled) {
             this.cancelled.send0();
         }
@@ -69,10 +101,9 @@ export class XRInputAction extends Vector1 {
 
     /** @internal Stage cancellation so the whole handle can become neutral before its notification. */
     reset() {
-        this.#cancelled = this.#cancelled || this.#interaction === 1;
-        this.#interaction = 0;
-        this.valueSource = XRInputValueSource.Unavailable;
-        this.set(0);
+        this.#cancelled = this.#cancelled || this.#interaction === InteractionState.Started;
+        this.#interaction = InteractionState.Idle;
+        this.update();
     }
 
     /** @internal */

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

@@ -1,7 +1,7 @@
 /**
- * One raw GamepadButton: its scalar amount and the two binary facts reported by the browser.
- * pressed is not inferred from x; a partially depressed trigger need not be pressed.
- * The device owns mutation. Switches and onChanged keep their identity across source replacement.
+ * One raw GamepadButton: its amount in [0, 1] and its native pressed/touched switches.
+ * {@link pressed} is independent of {@link x}; a partially depressed trigger need not be pressed.
+ * The device owns mutation. Switches and {@link onChanged} retain their identity across source replacement.
  */
 export class XRInputButton extends Vector1 {
     /** @readonly */
@@ -12,13 +12,11 @@ export class XRInputButton extends Vector1 {
      * Stage binary state while updating the scalar. All numeric channels and poses are sampled before
      * the device calls flushSwitches, so an input-map action can read the corresponding amount.
      * @internal
-     * @param {{value: number, pressed: boolean, touched: boolean}|undefined} button
+     * @param {number} [value=0]
+     * @param {boolean} [pressed=false]
+     * @param {boolean} [touched=false]
      */
-    update(button: {
-        value: number;
-        pressed: boolean;
-        touched: boolean;
-    } | undefined): void;
+    update(value?: number, pressed?: boolean, touched?: boolean): void;
     /** @internal */
     flushSwitches(): void;
     #private;

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

@@ -1 +1 @@
-{"version":3,"file":"XRInputButton.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRInputButton.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH;IACI,gBAAgB;IAChB,oCAAkC;IAClC,gBAAgB;IAChB,oCAAkC;IAKlC;;;;;OAKG;IACH,eAFW;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAC,GAAC,SAAS,QAMvE;IAED,gBAAgB;IAChB,sBAWC;;CACJ;wBA1CuB,kCAAkC;kCACxB,yBAAyB"}
+{"version":3,"file":"XRInputButton.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRInputButton.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IACI,gBAAgB;IAChB,oCAAkC;IAElC,gBAAgB;IAChB,oCAAkC;IAKlC;;;;;;;OAOG;IACH,eAJW,MAAM,YACN,OAAO,YACP,OAAO,QAWjB;IAED,gBAAgB;IAChB,sBAYC;;CACJ;wBAnDuB,kCAAkC;kCACxB,yBAAyB"}

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

@@ -1,14 +1,16 @@
+import { assert } from "../../../../core/assert.js";
 import { Vector1 } from "../../../../core/geom/Vector1.js";
 import { InputDeviceSwitch } from "../InputDeviceSwitch.js";
 
 /**
- * One raw GamepadButton: its scalar amount and the two binary facts reported by the browser.
- * pressed is not inferred from x; a partially depressed trigger need not be pressed.
- * The device owns mutation. Switches and onChanged keep their identity across source replacement.
+ * One raw GamepadButton: its amount in [0, 1] and its native pressed/touched switches.
+ * {@link pressed} is independent of {@link x}; a partially depressed trigger need not be pressed.
+ * The device owns mutation. Switches and {@link onChanged} retain their identity across source replacement.
  */
 export class XRInputButton extends Vector1 {
     /** @readonly */
     pressed = new InputDeviceSwitch();
+
     /** @readonly */
     touched = new InputDeviceSwitch();
 
@@ -19,12 +21,19 @@ export class XRInputButton extends Vector1 {
      * Stage binary state while updating the scalar. All numeric channels and poses are sampled before
      * the device calls flushSwitches, so an input-map action can read the corresponding amount.
      * @internal
-     * @param {{value: number, pressed: boolean, touched: boolean}|undefined} button
+     * @param {number} [value=0]
+     * @param {boolean} [pressed=false]
+     * @param {boolean} [touched=false]
      */
-    update(button) {
-        this.#pressed = button !== undefined && button.pressed;
-        this.#touched = button !== undefined && button.touched;
-        this.set(button === undefined ? 0 : button.value);
+    update(value = 0, pressed = false, touched = false) {
+        assert.greaterThanOrEqual(value, 0, 'value >= 0');
+        assert.lessThanOrEqual(value, 1, 'value <= 1');
+        assert.isBoolean(pressed, 'pressed');
+        assert.isBoolean(touched, 'touched');
+
+        this.#pressed = pressed;
+        this.#touched = touched;
+        this.set(value);
     }
 
     /** @internal */
@@ -34,6 +43,7 @@ export class XRInputButton extends Vector1 {
         } else {
             this.pressed.release();
         }
+
         if (this.#touched) {
             this.touched.press();
         } else {

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

@@ -1,9 +1,17 @@
-/** @param {number} index Native button index. @returns {number} Scalar amount, not pressed/touched. */
+/**
+ * Code for a raw button's scalar amount. Use InputTriggerXRButton for pressed/touched switches.
+ * @param {number} index Native button index.
+ * @returns {number}
+ */
 export function xr_input_button_coordinate(index: number): number;
-/** @param {number} index Native axis index. @returns {number} */
+/**
+ * Code for a raw axis, without stick calibration.
+ * @param {number} index Native axis index.
+ * @returns {number}
+ */
 export function xr_input_axis_coordinate(index: number): number;
 /**
- * Stable codes used in serialized input maps.
+ * Stable coordinate codes used in serialized input maps.
  */
 export type XRInputCoordinates = number;
 export namespace XRInputCoordinates {

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

@@ -1 +1 @@
-{"version":3,"file":"XRInputCoordinates.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRInputCoordinates.js"],"names":[],"mappings":"AAUA,uGAAuG;AACvG,kDADY,MAAM,GAAuC,MAAM,CAI9D;AAED,iEAAiE;AACjE,gDADY,MAAM,GAAqC,MAAM,CAI5D;;;;iCAlBoB,MAAM"}
+{"version":3,"file":"XRInputCoordinates.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRInputCoordinates.js"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,kDAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;GAIG;AACH,gDAHW,MAAM,GACJ,MAAM,CAMlB;;;;iCA7BS,MAAM"}

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

@@ -1,6 +1,10 @@
 import { assert } from "../../../../core/assert.js";
 
-/** @readonly @enum {number} Stable codes used in serialized input maps. */
+/**
+ * Stable coordinate codes used in serialized input maps.
+ * @readonly
+ * @enum {number}
+ */
 export const XRInputCoordinates = {
     select: 0,
     squeeze: 1,
@@ -8,14 +12,24 @@ export const XRInputCoordinates = {
     touchpad: 3
 };
 
-/** @param {number} index Native button index. @returns {number} Scalar amount, not pressed/touched. */
+/**
+ * Code for a raw button's scalar amount. Use InputTriggerXRButton for pressed/touched switches.
+ * @param {number} index Native button index.
+ * @returns {number}
+ */
 export function xr_input_button_coordinate(index) {
     assert.isNonNegativeInteger(index, 'index');
+
     return 4 + index * 2;
 }
 
-/** @param {number} index Native axis index. @returns {number} */
+/**
+ * Code for a raw axis, without stick calibration.
+ * @param {number} index Native axis index.
+ * @returns {number}
+ */
 export function xr_input_axis_coordinate(index) {
     assert.isNonNegativeInteger(index, 'index');
+
     return 5 + index * 2;
 }

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

@@ -1,8 +1,8 @@
 /**
  * One XR input source, or a persistent handedness slot owned by XRInputDevice.
  * All control objects survive disconnection. Consumers read them; the device owns mutation.
- * Only xr-standard supplies known button/axis semantics. Other mappings remain available through
- * buttons/axes, while select/squeeze use the explicitly identified binary action fallback.
+ * With xr-standard, select/squeeze read native button amounts. Other mappings remain available through
+ * buttons/axes, while select/squeeze report 0/1 from native events; check their valueSource.
  *
  * Button indices 0/1 are select/squeeze; axes 0/1 are touchpad and 2/3 thumbstick in xr-standard.
  * Placeholder entries are allowed by WebXR: a zero entry does not prove that a control exists.
@@ -12,33 +12,63 @@ export class XRInputHandle {
     readonly select: XRInputAction;
     /** @readonly */
     readonly squeeze: XRInputAction;
-    /** @readonly @type {XRInputButton[]} Use getButton for an index that may not exist yet. */
+    /**
+     * Raw native buttons. Use {@link getButton} for an index that may not exist yet.
+     * @readonly
+     * @type {XRInputButton[]}
+     */
     readonly buttons: XRInputButton[];
-    /** @readonly @type {Vector1[]} Use getAxis for an index that may not exist yet. */
+    /**
+     * Raw native axes in [-1, 1]. Use {@link getAxis} for an index that may not exist yet.
+     * @readonly
+     * @type {Vector1[]}
+     */
     readonly axes: Vector1[];
-    /** @readonly */
+    /**
+     * Calibrated xr-standard thumbstick, +x right and +y down.
+     * @readonly
+     */
     readonly thumbstick: GamepadStick;
-    /** @readonly Uncalibrated pad coordinates, +x right, +y down. */
+    /**
+     * Uncalibrated xr-standard touchpad coordinates, +x right and +y down.
+     * @readonly
+     */
     readonly touchpad: Vector2;
     /** @readonly */
     readonly targetRay: XRInputPose;
     /** @readonly */
     readonly grip: XRInputPose;
-    /** @readonly @type {import('./XRInputTypes.js').XRInputSource|null} Set by the device. */
+    /**
+     * Native source, or null while disconnected. Set by the device.
+     * @readonly
+     * @type {import('./XRInputTypes.js').XRInputSource|null}
+     */
     readonly nativeSource: import('./XRInputTypes.js').XRInputSource | null;
-    /** Number of native entries, excluding controls materialised for bindings. */
+    /** Number of native buttons, excluding controls materialised for bindings. Do not modify directly. */
     buttonCount: number;
+    /** Number of native axes, excluding controls materialised for bindings. Do not modify directly. */
     axisCount: number;
     get connected(): boolean;
     get handedness(): string;
     get targetRayMode(): string;
     /** @returns {ReadonlyArray<string>} */
     get profiles(): readonly string[];
-    /** @param {number} index @returns {XRInputButton} */
+    /**
+     * Return a stable button, creating neutral entries up to this index if needed.
+     * @param {number} index
+     * @returns {XRInputButton}
+     */
     getButton(index: number): XRInputButton;
-    /** @param {number} index @returns {Vector1} */
+    /**
+     * Return a stable axis, creating neutral entries up to this index if needed.
+     * @param {number} index
+     * @returns {Vector1}
+     */
     getAxis(index: number): Vector1;
-    /** @internal @param {import('./XRInputTypes.js').XRInputSource|null} source */
+    /**
+     * @internal
+     * @param {import('./XRInputTypes.js').XRInputSource|null} source
+     */
     bind(source: import('./XRInputTypes.js').XRInputSource | null): void;
     /**
      * @internal Sample values and poses before publishing raw switch edges.

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

@@ -1 +1 @@
-{"version":3,"file":"XRInputHandle.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRInputHandle.js"],"names":[],"mappings":"AAYA;;;;;;;;GAQG;AACH;IACI,gBAAgB;IAChB,+BAA6B;IAC7B,gBAAgB;IAChB,gCAA8B;IAC9B,2FAA2F;IAC3F,kBADqB,aAAa,EAAE,CACvB;IACb,mFAAmF;IACnF,eADqB,OAAO,EAAE,CACpB;IACV,gBAAgB;IAChB,kCAAoC;IACpC,iEAAiE;IACjE,2BAAyB;IACzB,gBAAgB;IAChB,gCAA8B;IAC9B,gBAAgB;IAChB,2BAAyB;IAEzB,0FAA0F;IAC1F,uBADqB,OAAO,mBAAmB,EAAE,aAAa,GAAC,IAAI,CAC/C;IAIpB,8EAA8E;IAC9E,oBAAgB;IAChB,kBAAc;IAOd,yBAAsD;IACtD,yBAA+F;IAC/F,4BAAiG;IACjG,uCAAuC;IACvC,kCAAgG;IAEhG,qDAAqD;IACrD,iBADY,MAAM,GAAkB,aAAa,CAOhD;IAED,+CAA+C;IAC/C,eADY,MAAM,GAAkB,OAAO,CAO1C;IAED,+EAA+E;IAC/E,aADsB,OAAO,mBAAmB,EAAE,aAAa,GAAC,IAAI,QAUnE;IAED;;;;OAIG;IACH,cAHW,OAAO,mBAAmB,EAAE,OAAO,GAAC,IAAI,kBACxC,WAAW,GAAC,IAAI,QA4C1B;IAED,sEAAsE;IACtE,wBAGC;IAED,yFAAyF;IACzF,cAeC;IAED,gBAAgB;IAChB,cAMC;;CACJ;8BAtK6B,oBAAoB;8BACpB,oBAAoB;wBAJ1B,kCAAkC;6BAE7B,4BAA4B;oBADrC,kCAAkC;4BAI1B,kBAAkB"}
+{"version":3,"file":"XRInputHandle.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRInputHandle.js"],"names":[],"mappings":"AA2BA;;;;;;;;GAQG;AACH;IACI,gBAAgB;IAChB,+BAA6B;IAE7B,gBAAgB;IAChB,gCAA8B;IAE9B;;;;OAIG;IACH,kBAFU,aAAa,EAAE,CAEZ;IAEb;;;;OAIG;IACH,eAFU,OAAO,EAAE,CAET;IAEV;;;OAGG;IACH,kCAAoC;IAEpC;;;OAGG;IACH,2BAAyB;IAEzB,gBAAgB;IAChB,gCAA8B;IAE9B,gBAAgB;IAChB,2BAAyB;IAEzB;;;;OAIG;IACH,uBAFU,OAAO,mBAAmB,EAAE,aAAa,GAAC,IAAI,CAEpC;IAQpB,sGAAsG;IACtG,oBAAgB;IAEhB,mGAAmG;IACnG,kBAAc;IAOd,yBAEC;IAED,yBAEC;IAED,4BAEC;IAED,uCAAuC;IACvC,kCAEC;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,aAAa,CAUzB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,OAAO,CAUnB;IAED;;;OAGG;IACH,aAFW,OAAO,mBAAmB,EAAE,aAAa,GAAC,IAAI,QAgBxD;IAED;;;;OAIG;IACH,cAHW,OAAO,mBAAmB,EAAE,OAAO,GAAC,IAAI,kBACxC,WAAW,GAAC,IAAI,QA+C1B;IAmBD,sEAAsE;IACtE,wBAGC;IAED,yFAAyF;IACzF,cAeC;IAED,gBAAgB;IAChB,cAMC;;CACJ;8BAvQ6B,oBAAoB;8BACpB,oBAAoB;wBAJ1B,kCAAkC;6BAE7B,4BAA4B;oBADrC,kCAAkC;4BAIN,kBAAkB"}

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

@@ -4,17 +4,32 @@ import Vector2 from "../../../../core/geom/Vector2.js";
 import { GamepadStick } from "../gamepad/GamepadStick.js";
 import { XRInputAction } from "./XRInputAction.js";
 import { XRInputButton } from "./XRInputButton.js";
-import { XRInputPose } from "./XRInputPose.js";
+import { XRInputPose, xr_input_read_pose } from "./XRInputPose.js";
 import { XRInputValueSource } from "./XRInputValueSource.js";
+import { XRHandedness } from "./XRHandedness.js";
+import { XRTargetRayMode } from "./XRTargetRayMode.js";
+import { XRGamepadMapping } from "./XRGamepadMapping.js";
 
-/** @type {ReadonlyArray<string>} */
-const NO_PROFILES = Object.freeze([]);
+const DEFAULT_METADATA = Object.freeze({
+    handedness: XRHandedness.None,
+    targetRayMode: XRTargetRayMode.Unavailable,
+    profiles: Object.freeze([])
+});
+
+/** @type {import('./XRInputTypes.js').XRGamepad} */
+const DEFAULT_GAMEPAD = Object.freeze({
+    mapping: XRGamepadMapping.Unmapped,
+    buttons: Object.freeze([]),
+    axes: Object.freeze([])
+});
+
+const DEFAULT_BUTTON = Object.freeze({ value: 0, pressed: false, touched: false });
 
 /**
  * One XR input source, or a persistent handedness slot owned by XRInputDevice.
  * All control objects survive disconnection. Consumers read them; the device owns mutation.
- * Only xr-standard supplies known button/axis semantics. Other mappings remain available through
- * buttons/axes, while select/squeeze use the explicitly identified binary action fallback.
+ * With xr-standard, select/squeeze read native button amounts. Other mappings remain available through
+ * buttons/axes, while select/squeeze report 0/1 from native events; check their valueSource.
  *
  * Button indices 0/1 are select/squeeze; axes 0/1 are touchpad and 2/3 thumbstick in xr-standard.
  * Placeholder entries are allowed by WebXR: a zero entry does not prove that a control exists.
@@ -22,28 +37,59 @@ const NO_PROFILES = Object.freeze([]);
 export class XRInputHandle {
     /** @readonly */
     select = new XRInputAction();
+
     /** @readonly */
     squeeze = new XRInputAction();
-    /** @readonly @type {XRInputButton[]} Use getButton for an index that may not exist yet. */
+
+    /**
+     * Raw native buttons. Use {@link getButton} for an index that may not exist yet.
+     * @readonly
+     * @type {XRInputButton[]}
+     */
     buttons = [];
-    /** @readonly @type {Vector1[]} Use getAxis for an index that may not exist yet. */
+
+    /**
+     * Raw native axes in [-1, 1]. Use {@link getAxis} for an index that may not exist yet.
+     * @readonly
+     * @type {Vector1[]}
+     */
     axes = [];
-    /** @readonly */
+
+    /**
+     * Calibrated xr-standard thumbstick, +x right and +y down.
+     * @readonly
+     */
     thumbstick = new GamepadStick(2, 3);
-    /** @readonly Uncalibrated pad coordinates, +x right, +y down. */
+
+    /**
+     * Uncalibrated xr-standard touchpad coordinates, +x right and +y down.
+     * @readonly
+     */
     touchpad = new Vector2();
+
     /** @readonly */
     targetRay = new XRInputPose();
+
     /** @readonly */
     grip = new XRInputPose();
 
-    /** @readonly @type {import('./XRInputTypes.js').XRInputSource|null} Set by the device. */
+    /**
+     * Native source, or null while disconnected. Set by the device.
+     * @readonly
+     * @type {import('./XRInputTypes.js').XRInputSource|null}
+     */
     nativeSource = null;
+
+    /** @type {Pick<import('./XRInputTypes.js').XRInputSource, 'handedness'|'targetRayMode'|'profiles'>} */
+    #metadata = DEFAULT_METADATA;
+
     /** @type {number[]} */
     #axisValues = [0, 0, 0, 0];
 
-    /** Number of native entries, excluding controls materialised for bindings. */
+    /** Number of native buttons, excluding controls materialised for bindings. Do not modify directly. */
     buttonCount = 0;
+
+    /** Number of native axes, excluding controls materialised for bindings. Do not modify directly. */
     axisCount = 0;
 
     constructor() {
@@ -51,40 +97,71 @@ export class XRInputHandle {
         this.getAxis(3);
     }
 
-    get connected() { return this.nativeSource !== null; }
-    get handedness() { return this.nativeSource === null ? 'none' : this.nativeSource.handedness; }
-    get targetRayMode() { return this.nativeSource === null ? '' : this.nativeSource.targetRayMode; }
+    get connected() {
+        return this.nativeSource !== null;
+    }
+
+    get handedness() {
+        return this.#metadata.handedness;
+    }
+
+    get targetRayMode() {
+        return this.#metadata.targetRayMode;
+    }
+
     /** @returns {ReadonlyArray<string>} */
-    get profiles() { return this.nativeSource === null ? NO_PROFILES : this.nativeSource.profiles; }
+    get profiles() {
+        return this.#metadata.profiles;
+    }
 
-    /** @param {number} index @returns {XRInputButton} */
+    /**
+     * Return a stable button, creating neutral entries up to this index if needed.
+     * @param {number} index
+     * @returns {XRInputButton}
+     */
     getButton(index) {
         assert.isNonNegativeInteger(index, 'index');
+
         while (this.buttons.length <= index) {
             this.buttons.push(new XRInputButton());
         }
+
         return this.buttons[index];
     }
 
-    /** @param {number} index @returns {Vector1} */
+    /**
+     * Return a stable axis, creating neutral entries up to this index if needed.
+     * @param {number} index
+     * @returns {Vector1}
+     */
     getAxis(index) {
         assert.isNonNegativeInteger(index, 'index');
+
         while (this.axes.length <= index) {
             this.axes.push(new Vector1());
         }
+
         return this.axes[index];
     }
 
-    /** @internal @param {import('./XRInputTypes.js').XRInputSource|null} source */
+    /**
+     * @internal
+     * @param {import('./XRInputTypes.js').XRInputSource|null} source
+     */
     bind(source) {
+        assert.defined(source, 'source');
+        assert.isObject(source, 'source');
+
         if (this.nativeSource === source) {
             return;
         }
         this.nativeSource = null;
+        this.#metadata = DEFAULT_METADATA;
         this.clear();
         this.flush();
         this.thumbstick.forgetCalibration();
         this.nativeSource = source;
+        this.#metadata = source ?? DEFAULT_METADATA;
     }
 
     /**
@@ -93,6 +170,9 @@ export class XRInputHandle {
      * @param {EventTarget|null} referenceSpace
      */
     sample(frame, referenceSpace) {
+        assert.defined(frame, 'frame');
+        assert.defined(referenceSpace, 'referenceSpace');
+
         const source = this.nativeSource;
         if (source === null) {
             return;
@@ -100,17 +180,16 @@ export class XRInputHandle {
         // A source/visibility notification has no pose frame. Preserve the last sample in that case;
         // only an actual unavailable pose, a reference-space change or cleanup invalidates it.
         if (frame !== null) {
-            const ray = referenceSpace !== null ? frame.getPose(source.targetRaySpace, referenceSpace) ?? null : null;
-            const grip = referenceSpace !== null && source.gripSpace != null
-                ? frame.getPose(source.gripSpace, referenceSpace) ?? null : null;
+            const ray = xr_input_read_pose(frame, source.targetRaySpace, referenceSpace);
+            const grip = xr_input_read_pose(frame, source.gripSpace ?? null, referenceSpace);
             this.targetRay.update(ray);
             this.grip.update(grip);
         }
 
-        const gamepad = source.gamepad;
-        const mapped = gamepad != null && gamepad.mapping === 'xr-standard';
-        this.buttonCount = gamepad == null ? 0 : gamepad.buttons.length;
-        this.axisCount = gamepad == null ? 0 : gamepad.axes.length;
+        const gamepad = source.gamepad ?? DEFAULT_GAMEPAD;
+        const mapped = gamepad.mapping === XRGamepadMapping.Standard;
+        this.buttonCount = gamepad.buttons.length;
+        this.axisCount = gamepad.axes.length;
         if (this.buttonCount > 0) {
             this.getButton(this.buttonCount - 1);
         }
@@ -118,10 +197,11 @@ export class XRInputHandle {
             this.getAxis(this.axisCount - 1);
         }
         for (let i = 0; i < this.buttons.length; i++) {
-            this.buttons[i].update(i < this.buttonCount ? gamepad.buttons[i] : undefined);
+            const button = gamepad.buttons[i] ?? DEFAULT_BUTTON;
+            this.buttons[i].update(button.value, button.pressed, button.touched);
         }
         for (let i = 0; i < this.axes.length; i++) {
-            const value = i < this.axisCount ? gamepad.axes[i] : 0;
+            const value = gamepad.axes[i] ?? 0;
             this.#axisValues[i] = value;
             this.axes[i].set(value);
         }
@@ -132,14 +212,31 @@ export class XRInputHandle {
             this.touchpad.set(0, 0);
             this.thumbstick.reset();
         }
-        this.select.update(mapped && this.buttonCount > 0 ? XRInputValueSource.Gamepad : XRInputValueSource.Action, this.buttons[0].x);
-        this.squeeze.update(mapped && this.buttonCount > 1 ? XRInputValueSource.Gamepad : XRInputValueSource.Action, this.buttons[1].x);
+        this.#sampleAction(this.select, 0, mapped);
+        this.#sampleAction(this.squeeze, 1, mapped);
+    }
+
+    /**
+     * @param {XRInputAction} action
+     * @param {number} buttonIndex
+     * @param {boolean} mapped
+     */
+    #sampleAction(action, buttonIndex, mapped) {
+        if (mapped && buttonIndex < this.buttonCount) {
+            action.update(this.buttons[buttonIndex].x, XRInputValueSource.Gamepad);
+            return;
+        }
+        // Preserve event-driven amounts between native begin/end events. Clear a previous hardware
+        // amount when entering event-only mode.
+        if (action.valueSource !== XRInputValueSource.Action) {
+            action.update(0, XRInputValueSource.Action);
+        }
     }
 
     /** @internal Tracking loss does not imply release or cancellation. */
     invalidatePoses() {
-        this.targetRay.update(null);
-        this.grip.update(null);
+        this.targetRay.update();
+        this.grip.update();
     }
 
     /** @internal Neutralise everything before switch releases and cancellation callbacks. */
@@ -148,7 +245,7 @@ export class XRInputHandle {
         this.buttonCount = 0;
         this.axisCount = 0;
         for (let i = 0; i < this.buttons.length; i++) {
-            this.buttons[i].update(undefined);
+            this.buttons[i].update();
         }
         for (let i = 0; i < this.axes.length; i++) {
             this.axes[i].set(0);