@woosh/meep-engine 3.36.0 → 3.37.0

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

@@ -1,6 +1,36 @@
+/**
+ * Read a pose relative to the reference space. Returns {@link DEFAULT_POSE} when either space or
+ * the native pose is unavailable.
+ * @param {import('./XRInputTypes.js').XRFrame} frame
+ * @param {EventTarget|null} space
+ * @param {EventTarget|null} referenceSpace
+ * @returns {import('./XRInputTypes.js').XRPose}
+ */
+export function xr_input_read_pose(frame: import('./XRInputTypes.js').XRFrame, space: EventTarget | null, referenceSpace: EventTarget | null): import('./XRInputTypes.js').XRPose;
+/**
+ * Neutral, unavailable pose. Shared immutable data, copied into each handle's own meep vectors.
+ * Identity is significant: a real tracked pose at the origin is still valid.
+ * @readonly
+ */
+export const DEFAULT_POSE: Readonly<{
+    transform: Readonly<{
+        position: Readonly<{
+            x: 0;
+            y: 0;
+            z: 0;
+        }>;
+        orientation: Readonly<{
+            x: 0;
+            y: 0;
+            z: 0;
+            w: 1;
+        }>;
+    }>;
+    emulatedPosition: false;
+}>;
 /**
  * A copied pose in the device's configured reference space. The device owns mutation.
- * valid must be checked before use; an unavailable pose is cleared, not presented as valid identity.
+ * Check {@link valid} before use. An unavailable pose has zero position and identity rotation.
  * Target-ray forward is local -Z, regardless of a game's own forward convention.
  */
 export class XRInputPose {
@@ -8,15 +38,21 @@ export class XRInputPose {
     readonly position: Vector3;
     /** @readonly */
     readonly rotation: Quaternion;
-    /** @type {boolean} */
+    /**
+     * Whether a pose is available in the current reference space. Do not modify directly.
+     * @type {boolean}
+     */
     valid: boolean;
-    /** @type {boolean} */
+    /**
+     * Whether the browser estimates the position instead of tracking it. Do not modify directly.
+     * @type {boolean}
+     */
     emulatedPosition: boolean;
     /**
      * @internal
-     * @param {import("./XRInputTypes.js").XRPose|null} pose
+     * @param {import("./XRInputTypes.js").XRPose} [pose=DEFAULT_POSE]
      */
-    update(pose: import("./XRInputTypes.js").XRPose | null): void;
+    update(pose?: import("./XRInputTypes.js").XRPose): void;
 }
 import Vector3 from "../../../../core/geom/Vector3.js";
 import Quaternion from "../../../../core/geom/Quaternion.js";

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

@@ -1 +1 @@
-{"version":3,"file":"XRInputPose.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRInputPose.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH;IACI,gBAAgB;IAChB,2BAAyB;IACzB,gBAAgB;IAChB,8BAA4B;IAC5B,sBAAsB;IACtB,OADW,OAAO,CACJ;IACd,sBAAsB;IACtB,kBADW,OAAO,CACO;IAEzB;;;OAGG;IACH,aAFW,OAAO,mBAAmB,EAAE,MAAM,GAAC,IAAI,QAcjD;CACJ;oBAlCmB,kCAAkC;uBAD/B,qCAAqC"}
+{"version":3,"file":"XRInputPose.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRInputPose.js"],"names":[],"mappings":"AAiBA;;;;;;;GAOG;AACH,0CALW,OAAO,mBAAmB,EAAE,OAAO,SACnC,WAAW,GAAC,IAAI,kBAChB,WAAW,GAAC,IAAI,GACd,OAAO,mBAAmB,EAAE,MAAM,CAW9C;AA9BD;;;;GAIG;AACH;;;;;;;;;;;;;;;GAMG;AAqBH;;;;GAIG;AACH;IACI,gBAAgB;IAChB,2BAAyB;IAEzB,gBAAgB;IAChB,8BAA4B;IAE5B;;;OAGG;IACH,OAFU,OAAO,CAEH;IAEd;;;OAGG;IACH,kBAFU,OAAO,CAEQ;IAEzB;;;OAGG;IACH,cAFW,OAAO,mBAAmB,EAAE,MAAM,QAa5C;CACJ;oBA1EmB,kCAAkC;uBAD/B,qCAAqC"}

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

@@ -1,36 +1,77 @@
+import { assert } from "../../../../core/assert.js";
 import Quaternion from "../../../../core/geom/Quaternion.js";
 import Vector3 from "../../../../core/geom/Vector3.js";
 
+/**
+ * Neutral, unavailable pose. Shared immutable data, copied into each handle's own meep vectors.
+ * Identity is significant: a real tracked pose at the origin is still valid.
+ * @readonly
+ */
+export const DEFAULT_POSE = Object.freeze({
+    transform: Object.freeze({
+        position: Object.freeze({ x: 0, y: 0, z: 0 }),
+        orientation: Object.freeze({ x: 0, y: 0, z: 0, w: 1 })
+    }),
+    emulatedPosition: false
+});
+
+/**
+ * Read a pose relative to the reference space. Returns {@link DEFAULT_POSE} when either space or
+ * the native pose is unavailable.
+ * @param {import('./XRInputTypes.js').XRFrame} frame
+ * @param {EventTarget|null} space
+ * @param {EventTarget|null} referenceSpace
+ * @returns {import('./XRInputTypes.js').XRPose}
+ */
+export function xr_input_read_pose(frame, space, referenceSpace) {
+    assert.defined(space, 'space');
+    assert.defined(referenceSpace, 'referenceSpace');
+
+    if (space === null || referenceSpace === null) {
+        return DEFAULT_POSE;
+    }
+
+    return frame.getPose(space, referenceSpace) ?? DEFAULT_POSE;
+}
+
 /**
  * A copied pose in the device's configured reference space. The device owns mutation.
- * valid must be checked before use; an unavailable pose is cleared, not presented as valid identity.
+ * Check {@link valid} before use. An unavailable pose has zero position and identity rotation.
  * Target-ray forward is local -Z, regardless of a game's own forward convention.
  */
 export class XRInputPose {
     /** @readonly */
     position = new Vector3();
+
     /** @readonly */
     rotation = new Quaternion();
-    /** @type {boolean} */
+
+    /**
+     * Whether a pose is available in the current reference space. Do not modify directly.
+     * @type {boolean}
+     */
     valid = false;
-    /** @type {boolean} */
+
+    /**
+     * Whether the browser estimates the position instead of tracking it. Do not modify directly.
+     * @type {boolean}
+     */
     emulatedPosition = false;
 
     /**
      * @internal
-     * @param {import("./XRInputTypes.js").XRPose|null} pose
+     * @param {import("./XRInputTypes.js").XRPose} [pose=DEFAULT_POSE]
      */
-    update(pose) {
-        this.valid = pose !== null;
-        this.emulatedPosition = pose !== null && pose.emulatedPosition;
-        if (pose === null) {
-            this.position.set(0, 0, 0);
-            this.rotation.set(0, 0, 0, 1);
-        } else {
-            const p = pose.transform.position;
-            const q = pose.transform.orientation;
-            this.position.set(p.x, p.y, p.z);
-            this.rotation.set(q.x, q.y, q.z, q.w);
-        }
+    update(pose = DEFAULT_POSE) {
+        assert.notNull(pose, 'pose');
+        assert.isBoolean(pose.emulatedPosition, 'pose.emulatedPosition');
+
+        const p = pose.transform.position;
+        const q = pose.transform.orientation;
+
+        this.valid = pose !== DEFAULT_POSE;
+        this.emulatedPosition = pose.emulatedPosition;
+        this.position.set(p.x, p.y, p.z);
+        this.rotation.set(q.x, q.y, q.z, q.w);
     }
 }

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

@@ -1,7 +1,7 @@
 /**
- * Structural subsets of WebXR used by the input boundary. Native WebXR objects satisfy these types;
- * keeping the boundary structural also permits headless hosts and avoids requiring ambient XR globals
- * in every consumer of Engine's generated declarations.
+ * WebXR interfaces accepted by meep's input API. Native WebXR objects satisfy these structural types;
+ * applications can use meep's declarations without installing ambient WebXR types.
+ * Only the members consumed by the input device are required.
  */
 export type XRGamepad = {
     mapping: string;
@@ -13,9 +13,9 @@ export type XRGamepad = {
     axes: ReadonlyArray<number>;
 };
 /**
- * Structural subsets of WebXR used by the input boundary. Native WebXR objects satisfy these types;
- * keeping the boundary structural also permits headless hosts and avoids requiring ambient XR globals
- * in every consumer of Engine's generated declarations.
+ * WebXR interfaces accepted by meep's input API. Native WebXR objects satisfy these structural types;
+ * applications can use meep's declarations without installing ambient WebXR types.
+ * Only the members consumed by the input device are required.
  */
 export type XRInputSource = {
     handedness: string;
@@ -26,18 +26,18 @@ export type XRInputSource = {
     gamepad?: XRGamepad | null;
 };
 /**
- * Structural subsets of WebXR used by the input boundary. Native WebXR objects satisfy these types;
- * keeping the boundary structural also permits headless hosts and avoids requiring ambient XR globals
- * in every consumer of Engine's generated declarations.
+ * WebXR interfaces accepted by meep's input API. Native WebXR objects satisfy these structural types;
+ * applications can use meep's declarations without installing ambient WebXR types.
+ * Only the members consumed by the input device are required.
  */
 export type XRSession = EventTarget & {
     readonly inputSources: ArrayLike<XRInputSource>;
     readonly visibilityState: string;
 };
 /**
- * Structural subsets of WebXR used by the input boundary. Native WebXR objects satisfy these types;
- * keeping the boundary structural also permits headless hosts and avoids requiring ambient XR globals
- * in every consumer of Engine's generated declarations.
+ * WebXR interfaces accepted by meep's input API. Native WebXR objects satisfy these structural types;
+ * applications can use meep's declarations without installing ambient WebXR types.
+ * Only the members consumed by the input device are required.
  */
 export type XRPose = {
     transform: {
@@ -56,18 +56,18 @@ export type XRPose = {
     emulatedPosition: boolean;
 };
 /**
- * Structural subsets of WebXR used by the input boundary. Native WebXR objects satisfy these types;
- * keeping the boundary structural also permits headless hosts and avoids requiring ambient XR globals
- * in every consumer of Engine's generated declarations.
+ * WebXR interfaces accepted by meep's input API. Native WebXR objects satisfy these structural types;
+ * applications can use meep's declarations without installing ambient WebXR types.
+ * Only the members consumed by the input device are required.
  */
 export type XRFrame = {
     session: XRSession;
     getPose: (space: EventTarget, baseSpace: EventTarget) => XRPose | null | undefined;
 };
 /**
- * Structural subsets of WebXR used by the input boundary. Native WebXR objects satisfy these types;
- * keeping the boundary structural also permits headless hosts and avoids requiring ambient XR globals
- * in every consumer of Engine's generated declarations.
+ * WebXR interfaces accepted by meep's input API. Native WebXR objects satisfy these structural types;
+ * applications can use meep's declarations without installing ambient WebXR types.
+ * Only the members consumed by the input device are required.
  */
 export type XRSessionInputEvent = Event & {
     inputSource?: XRInputSource;

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

@@ -1,7 +1,7 @@
 /**
- * Structural subsets of WebXR used by the input boundary. Native WebXR objects satisfy these types;
- * keeping the boundary structural also permits headless hosts and avoids requiring ambient XR globals
- * in every consumer of Engine's generated declarations.
+ * WebXR interfaces accepted by meep's input API. Native WebXR objects satisfy these structural types;
+ * applications can use meep's declarations without installing ambient WebXR types.
+ * Only the members consumed by the input device are required.
  *
  * @typedef {object} XRGamepad
  * @property {string} mapping

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

@@ -0,0 +1,17 @@
+/**
+ * Native target-ray modes, plus Unavailable for a disconnected handle.
+ */
+export type XRTargetRayMode = string;
+/**
+ * Native target-ray modes, plus Unavailable for a disconnected handle.
+ * @readonly
+ * @enum {string}
+ */
+export const XRTargetRayMode: Readonly<{
+    Unavailable: "";
+    Gaze: "gaze";
+    TrackedPointer: "tracked-pointer";
+    Screen: "screen";
+    TransientPointer: "transient-pointer";
+}>;
+//# sourceMappingURL=XRTargetRayMode.d.ts.map

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

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

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

@@ -0,0 +1,12 @@
+/**
+ * Native target-ray modes, plus Unavailable for a disconnected handle.
+ * @readonly
+ * @enum {string}
+ */
+export const XRTargetRayMode = Object.freeze({
+    Unavailable: '',
+    Gaze: 'gaze',
+    TrackedPointer: 'tracked-pointer',
+    Screen: 'screen',
+    TransientPointer: 'transient-pointer'
+});

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

@@ -0,0 +1,15 @@
+/**
+ * Native XRSession visibility states.
+ */
+export type XRVisibilityState = string;
+/**
+ * Native XRSession visibility states.
+ * @readonly
+ * @enum {string}
+ */
+export const XRVisibilityState: Readonly<{
+    Visible: "visible";
+    VisibleBlurred: "visible-blurred";
+    Hidden: "hidden";
+}>;
+//# sourceMappingURL=XRVisibilityState.d.ts.map

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

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

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

@@ -0,0 +1,10 @@
+/**
+ * Native XRSession visibility states.
+ * @readonly
+ * @enum {string}
+ */
+export const XRVisibilityState = Object.freeze({
+    Visible: 'visible',
+    VisibleBlurred: 'visible-blurred',
+    Hidden: 'hidden'
+});

package/src/engine/input/ecs/ism/coordinate/InputCoordinateDevice.d.ts

@@ -30,8 +30,10 @@ export class InputCoordinateDevice extends InputCoordinateChannel {
     static fromGamepad(code: number): InputCoordinateDevice;
     /**
      * Select/squeeze and raw buttons/axes are scalar; thumbstick/touchpad have two components.
+     * Missing hardware reads zero. Named sticks require xr-standard; raw axes retain native ordering.
+     *
      * @param {'left'|'right'|'none'} handedness
-     * @param {number} code XRInputCoordinates or xr_input_button_coordinate/xr_input_axis_coordinate.
+     * @param {number} code A value from XRInputCoordinates, xr_input_button_coordinate or xr_input_axis_coordinate.
      * @returns {InputCoordinateDevice}
      */
     static fromXR(handedness: 'left' | 'right' | 'none', code: number): InputCoordinateDevice;

package/src/engine/input/ecs/ism/coordinate/InputCoordinateDevice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InputCoordinateDevice.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/input/ecs/ism/coordinate/InputCoordinateDevice.js"],"names":[],"mappings":"AAaA;;;;GAIG;AAEH;;;;;;;;;;;GAWG;AACH;IA2BI;;;OAGG;IACH,0BAHW,qBAAqB,GACnB,qBAAqB,CAUjC;IAED;;;;;OAKG;IACH,yBAHW,MAAM,GACJ,qBAAqB,CAQjC;IAED;;;;;OAKG;IACH,0BAJW,MAAM,GAAC,OAAO,GAAC,MAAM,QACrB,MAAM,GACJ,qBAAqB,CAQjC;IAED;;;;;;;OAOG;IACH,yBAHW,MAAM,GACJ,qBAAqB,CAajC;IAtFD;;OAEG;IACH,QAFU,qBAAqB,CAEM;IAoHrC;;OAEG;IACH,SAFa,qBAAqB,CAIjC;;CAiBJ;+BAhKY,OAAO,wBAAwB,EAAE,gBAAgB;iCACjD,OAAO,iCAAiC,EAAE,kBAAkB;qBAC5D,OAAO,sCAAsC,EAAE,MAAM;uCAP3B,6BAA6B;sCAD9B,6BAA6B"}
+{"version":3,"file":"InputCoordinateDevice.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/input/ecs/ism/coordinate/InputCoordinateDevice.js"],"names":[],"mappings":"AAaA;;;;GAIG;AAEH;;;;;;;;;;;GAWG;AACH;IA2BI;;;OAGG;IACH,0BAHW,qBAAqB,GACnB,qBAAqB,CAUjC;IAED;;;;;OAKG;IACH,yBAHW,MAAM,GACJ,qBAAqB,CAQjC;IAED;;;;;;;OAOG;IACH,0BAJW,MAAM,GAAC,OAAO,GAAC,MAAM,QACrB,MAAM,GACJ,qBAAqB,CAUjC;IAED;;;;;;;OAOG;IACH,yBAHW,MAAM,GACJ,qBAAqB,CAajC;IA1FD;;OAEG;IACH,QAFU,qBAAqB,CAEM;IAwHrC;;OAEG;IACH,SAFa,qBAAqB,CAIjC;;CAiBJ;+BApKY,OAAO,wBAAwB,EAAE,gBAAgB;iCACjD,OAAO,iCAAiC,EAAE,kBAAkB;qBAC5D,OAAO,sCAAsC,EAAE,MAAM;uCAP3B,6BAA6B;sCAD9B,6BAA6B"}

package/src/engine/input/ecs/ism/coordinate/InputCoordinateDevice.js

@@ -86,13 +86,17 @@ export class InputCoordinateDevice extends InputCoordinateChannel {
 
     /**
      * Select/squeeze and raw buttons/axes are scalar; thumbstick/touchpad have two components.
+     * Missing hardware reads zero. Named sticks require xr-standard; raw axes retain native ordering.
+     *
      * @param {'left'|'right'|'none'} handedness
-     * @param {number} code XRInputCoordinates or xr_input_button_coordinate/xr_input_axis_coordinate.
+     * @param {number} code A value from XRInputCoordinates, xr_input_button_coordinate or xr_input_axis_coordinate.
      * @returns {InputCoordinateDevice}
      */
     static fromXR(handedness, code) {
         assert.isNonNegativeInteger(code, 'code');
+
         const dimensions = code === XRInputCoordinates.thumbstick || code === XRInputCoordinates.touchpad ? 2 : 1;
+
         return InputCoordinateDevice.fromSource(InputCoordinateSource.from(
             xr_input_device_id(handedness), code, dimensions, InputCoordinateKind.Normalized
         ));

package/src/engine/input/ecs/ism/device/XRInputDeviceAdapter.d.ts

@@ -1,14 +1,28 @@
 /**
- * A persistent XR handedness slot, usable before hardware exists and across source swaps.
- * Native pressed/touched switches are independent of semantic select/squeeze completion. Subscribe to
- * those outcomes directly through their Signals (or InputController paths such as xr/right/select/completed).
+ * Exposes one persistent XR handedness slot to {@link InputMapSystem}, including before hardware exists.
+ * Use {@link InputTriggerXRButton} for native pressed/touched switches and
+ * {@link InputCoordinateDevice.fromXR} for amounts, sticks and axes.
+ *
+ * Subscribe to select/squeeze completion directly through XRInputAction.completed or an InputController
+ * path such as 'xr/right/select/completed'. Button press triggers and action completion are independent.
  *
  * @example
- *   new InputMapSystem([new XRInputDeviceAdapter(engine.devices.xr, 'right')]);
+ *   // With a running engine and an active scene:
+ *   const system = new InputMapSystem([new XRInputDeviceAdapter(engine.devices.xr, 'right')]);
+ *   await engine.entityManager.addSystem(system);
+ *   const map = new InputMap();
  *   map.bindCoordinate('pressure', InputCoordinateDevice.fromXR('right', XRInputCoordinates.select));
+ *   const entity = engine.entityManager.dataset.createEntity();
+ *   engine.entityManager.dataset.addComponentToEntity(entity, map);
+ *   // Read after XRInputDevice.poll in the application's frame callback.
+ *   const pressure = new Vector1();
+ *   map.axis1(pressure, 'pressure');
  */
 export class XRInputDeviceAdapter extends InputDeviceAdapter {
-    /** @param {import('../../../devices/XRInputDevice.js').XRInputDevice} device @param {'left'|'right'|'none'} handedness */
+    /**
+     * @param {import('../../../devices/XRInputDevice.js').XRInputDevice} device
+     * @param {'left'|'right'|'none'} handedness
+     */
     constructor(device: import('../../../devices/XRInputDevice.js').XRInputDevice, handedness: 'left' | 'right' | 'none');
     #private;
 }

package/src/engine/input/ecs/ism/device/XRInputDeviceAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"XRInputDeviceAdapter.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/input/ecs/ism/device/XRInputDeviceAdapter.js"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH;IAII,0HAA0H;IAC1H,oBADY,OAAO,mCAAmC,EAAE,aAAa,cAAiB,MAAM,GAAC,OAAO,GAAC,MAAM,EAK1G;;CA8BJ;mCAnDkC,yBAAyB"}
+{"version":3,"file":"XRInputDeviceAdapter.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/input/ecs/ism/device/XRInputDeviceAdapter.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAII;;;OAGG;IACH,oBAHW,OAAO,mCAAmC,EAAE,aAAa,cACzD,MAAM,GAAC,OAAO,GAAC,MAAM,EAU/B;;CA6CJ;mCApFkC,yBAAyB"}

package/src/engine/input/ecs/ism/device/XRInputDeviceAdapter.js

@@ -4,39 +4,72 @@ import { InputDeviceAdapter } from "./InputDeviceAdapter.js";
 import { xr_input_device_id } from "./XR_INPUT_DEVICE_IDS.js";
 
 /**
- * A persistent XR handedness slot, usable before hardware exists and across source swaps.
- * Native pressed/touched switches are independent of semantic select/squeeze completion. Subscribe to
- * those outcomes directly through their Signals (or InputController paths such as xr/right/select/completed).
+ * Exposes one persistent XR handedness slot to {@link InputMapSystem}, including before hardware exists.
+ * Use {@link InputTriggerXRButton} for native pressed/touched switches and
+ * {@link InputCoordinateDevice.fromXR} for amounts, sticks and axes.
+ *
+ * Subscribe to select/squeeze completion directly through XRInputAction.completed or an InputController
+ * path such as 'xr/right/select/completed'. Button press triggers and action completion are independent.
  *
  * @example
- *   new InputMapSystem([new XRInputDeviceAdapter(engine.devices.xr, 'right')]);
+ *   // With a running engine and an active scene:
+ *   const system = new InputMapSystem([new XRInputDeviceAdapter(engine.devices.xr, 'right')]);
+ *   await engine.entityManager.addSystem(system);
+ *   const map = new InputMap();
  *   map.bindCoordinate('pressure', InputCoordinateDevice.fromXR('right', XRInputCoordinates.select));
+ *   const entity = engine.entityManager.dataset.createEntity();
+ *   engine.entityManager.dataset.addComponentToEntity(entity, map);
+ *   // Read after XRInputDevice.poll in the application's frame callback.
+ *   const pressure = new Vector1();
+ *   map.axis1(pressure, 'pressure');
  */
 export class XRInputDeviceAdapter extends InputDeviceAdapter {
     /** @type {import('../../../devices/xr/XRInputHandle.js').XRInputHandle} */
     #handle;
 
-    /** @param {import('../../../devices/XRInputDevice.js').XRInputDevice} device @param {'left'|'right'|'none'} handedness */
+    /**
+     * @param {import('../../../devices/XRInputDevice.js').XRInputDevice} device
+     * @param {'left'|'right'|'none'} handedness
+     */
     constructor(device, handedness) {
         super();
+
+        assert.defined(device, 'device');
+        assert.notNull(device, 'device');
+
         this.id = xr_input_device_id(handedness);
         this.#handle = device[handedness];
     }
 
-    /** @param {number} code Even codes are pressed, odd codes touched; button index is floor(code/2). */
+    /**
+     * @param {number} code Even codes are pressed, odd codes touched; button index is floor(code/2).
+     * @returns {import('../../../devices/InputDeviceSwitch.js').InputDeviceSwitch}
+     */
     getSwitch(code) {
         assert.isNonNegativeInteger(code, 'code');
+
         const button = this.#handle.getButton(Math.floor(code / 2));
         return code % 2 === 0 ? button.pressed : button.touched;
     }
 
-    /** @param {number[]|Float64Array} result @param {number} offset @param {number} code */
+    /**
+     * @param {number[]|Float64Array} result
+     * @param {number} offset
+     * @param {number} code
+     */
     readCoordinate(result, offset, code) {
+        assert.isArrayLike(result, 'result');
+        assert.isNonNegativeInteger(offset, 'offset');
         assert.isNonNegativeInteger(code, 'code');
+
         const handle = this.#handle;
         switch (code) {
-            case XRInputCoordinates.select: result[offset] = handle.select.x; return;
-            case XRInputCoordinates.squeeze: result[offset] = handle.squeeze.x; return;
+            case XRInputCoordinates.select:
+                result[offset] = handle.select.x;
+                return;
+            case XRInputCoordinates.squeeze:
+                result[offset] = handle.squeeze.x;
+                return;
             case XRInputCoordinates.thumbstick:
                 result[offset] = handle.thumbstick.value.x;
                 result[offset + 1] = handle.thumbstick.value.y;

package/src/engine/input/ecs/ism/device/XR_INPUT_DEVICE_IDS.d.ts

@@ -1,6 +1,12 @@
-/** @param {'left'|'right'|'none'} handedness @returns {string} */
+/**
+ * @param {'left'|'right'|'none'} handedness
+ * @returns {string}
+ */
 export function xr_input_device_id(handedness: 'left' | 'right' | 'none'): string;
-/** @readonly Stable IDs used in serialized input maps. */
+/**
+ * Stable IDs used in serialized input maps.
+ * @readonly
+ */
 export const XR_INPUT_DEVICE_IDS: Readonly<{
     left: "xr-left";
     right: "xr-right";

package/src/engine/input/ecs/ism/device/XR_INPUT_DEVICE_IDS.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"XR_INPUT_DEVICE_IDS.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/input/ecs/ism/device/XR_INPUT_DEVICE_IDS.js"],"names":[],"mappings":"AAGA,kEAAkE;AAClE,+CADY,MAAM,GAAC,OAAO,GAAC,MAAM,GAAuB,MAAM,CAQ7D;AAXD,0DAA0D;AAC1D;;;;GAA0G"}
+{"version":3,"file":"XR_INPUT_DEVICE_IDS.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/input/ecs/ism/device/XR_INPUT_DEVICE_IDS.js"],"names":[],"mappings":"AAaA;;;GAGG;AACH,+CAHW,MAAM,GAAC,OAAO,GAAC,MAAM,GACnB,MAAM,CAMlB;AAlBD;;;GAGG;AACH;;;;GAIG"}

package/src/engine/input/ecs/ism/device/XR_INPUT_DEVICE_IDS.js

@@ -1,12 +1,22 @@
-/** @readonly Stable IDs used in serialized input maps. */
-export const XR_INPUT_DEVICE_IDS = Object.freeze({ left: 'xr-left', right: 'xr-right', none: 'xr-none' });
+import { assert } from "../../../../../core/assert.js";
+import { XRHandedness } from "../../../devices/xr/XRHandedness.js";
 
-/** @param {'left'|'right'|'none'} handedness @returns {string} */
+/**
+ * Stable IDs used in serialized input maps.
+ * @readonly
+ */
+export const XR_INPUT_DEVICE_IDS = Object.freeze({
+    left: 'xr-left',
+    right: 'xr-right',
+    none: 'xr-none'
+});
+
+/**
+ * @param {'left'|'right'|'none'} handedness
+ * @returns {string}
+ */
 export function xr_input_device_id(handedness) {
-    switch (handedness) {
-        case 'left': return XR_INPUT_DEVICE_IDS.left;
-        case 'right': return XR_INPUT_DEVICE_IDS.right;
-        case 'none': return XR_INPUT_DEVICE_IDS.none;
-        default: throw new Error(`Invalid XR handedness: ${handedness}`);
-    }
+    assert.enum(handedness, XRHandedness, 'handedness');
+
+    return XR_INPUT_DEVICE_IDS[handedness];
 }

package/src/engine/input/ecs/ism/trigger/InputTriggerXRButton.d.ts

@@ -1,6 +1,14 @@
-/** Native button facts only. No pressure threshold or semantic action lifecycle is inferred. */
+/**
+ * Trigger on a native XR button's pressed or touched switch.
+ * Subscribe to XRInputAction.completed for semantic select/squeeze completion.
+ */
 export class InputTriggerXRButton extends InputTriggerSwitch {
-    /** @param {'left'|'right'|'none'} handedness @param {number} index @param {boolean} [touched=false] */
+    /**
+     * @param {'left'|'right'|'none'} handedness
+     * @param {number} index Native button index.
+     * @param {boolean} [touched=false] True selects touched; false selects pressed.
+     * @returns {InputTriggerXRButton}
+     */
     static from(handedness: 'left' | 'right' | 'none', index: number, touched?: boolean): InputTriggerXRButton;
 }
 import { InputTriggerSwitch } from "./InputTriggerSwitch.js";

package/src/engine/input/ecs/ism/trigger/InputTriggerXRButton.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InputTriggerXRButton.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/input/ecs/ism/trigger/InputTriggerXRButton.js"],"names":[],"mappings":"AAKA,gGAAgG;AAChG;IACI,uGAAuG;IACvG,wBADY,MAAM,GAAC,OAAO,GAAC,MAAM,SAAqB,MAAM,YAAgB,OAAO,wBAMlF;CACJ;mCAXkC,yBAAyB"}
+{"version":3,"file":"InputTriggerXRButton.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/input/ecs/ism/trigger/InputTriggerXRButton.js"],"names":[],"mappings":"AAKA;;;GAGG;AACH;IACI;;;;;OAKG;IACH,wBALW,MAAM,GAAC,OAAO,GAAC,MAAM,SACrB,MAAM,YACN,OAAO,GACL,oBAAoB,CAShC;CACJ;mCArBkC,yBAAyB"}

package/src/engine/input/ecs/ism/trigger/InputTriggerXRButton.js

@@ -3,11 +3,21 @@ import { xr_input_device_id } from "../device/XR_INPUT_DEVICE_IDS.js";
 import { InputSource } from "../InputSource.js";
 import { InputTriggerSwitch } from "./InputTriggerSwitch.js";
 
-/** Native button facts only. No pressure threshold or semantic action lifecycle is inferred. */
+/**
+ * Trigger on a native XR button's pressed or touched switch.
+ * Subscribe to XRInputAction.completed for semantic select/squeeze completion.
+ */
 export class InputTriggerXRButton extends InputTriggerSwitch {
-    /** @param {'left'|'right'|'none'} handedness @param {number} index @param {boolean} [touched=false] */
+    /**
+     * @param {'left'|'right'|'none'} handedness
+     * @param {number} index Native button index.
+     * @param {boolean} [touched=false] True selects touched; false selects pressed.
+     * @returns {InputTriggerXRButton}
+     */
     static from(handedness, index, touched = false) {
         assert.isNonNegativeInteger(index, 'index');
+        assert.isBoolean(touched, 'touched');
+
         const result = new InputTriggerXRButton();
         result.source = InputSource.from(xr_input_device_id(handedness), index * 2 + (touched ? 1 : 0));
         return result;