@woosh/meep-engine 3.34.0 → 3.36.0

package/package.json

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

package/src/engine/Engine.d.ts

@@ -114,6 +114,7 @@ declare class Engine {
         pointer: PointerDevice;
         keyboard: KeyboardDevice;
         gamepad: GamepadDevice;
+        xr: XRInputDevice;
     };
     /**
      * Toggles GraphicsEngine rendering on and off
@@ -179,6 +180,7 @@ import SceneManager from "./scene/SceneManager.js";
 import { PointerDevice } from "./input/devices/PointerDevice.js";
 import KeyboardDevice from "./input/devices/KeyboardDevice.js";
 import { GamepadDevice } from "./input/devices/GamepadDevice.js";
+import { XRInputDevice } from "./input/devices/XRInputDevice.js";
 import EmptyView from "../view/elements/EmptyView.js";
 import { AssetPreloader } from "./asset/preloader/AssetPreloader.js";
 import ObservedBoolean from "../core/model/ObservedBoolean.js";

package/src/engine/Engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Engine.d.ts","sourceRoot":"","sources":["../../../src/engine/Engine.js"],"names":[],"mappings":";6BAoCa,OAAO,8BAA8B,EAAE,cAAc;AAwClE;IAiGI;;;;;;;;;OASG;IACH,sBARW,cAAc;QAEU,aAAa,GAArC,aAAa;QACK,cAAc,GAAhC,OAAO;QACW,WAAW,GAA7B,OAAO;QACW,KAAK,GAAvB,OAAO;OA+OjB;IApSD;;;OAGG;IACH,UAFU,cAAc,GAAC,IAAI,CAEb;IAEhB;;;OAGG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb,qBAA4B;IAE5B;;;;;;;;;OASG;IACH,0BAFU,uBAAuB,CAEe;IAEhD;;;OAGG;IACH,kBAFU,mBAAmB,CAEO;IAEpC;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,mBAFU,kBAAkB,CAEa;IAoBrC;;;OAGG;IACH,UAFU,cAAc,CAEA;IAKxB;;;OAGG;IACH,aAFU,gBAAgB,CAEe;IAGzC,yCAAkE;IAK9D,6BAAkC;IAMtC;;;OAGG;IACH,cAFU,aAAa,MAAM,CAAC,CAK5B;IAEF,8CAiCE;IAgCF;;;OAGG;IACH,SAFU,WAAW,CAEoB;IAEzC;;;OAGG;IACH,oCAA0C;IAE1C;;;OAGG;IACH,sCAFU,2BAA2B,CAE+B;IAEpE,yBAAoC;IAGpC;;OAEG;IACH,aAAkB;IAElB;;;OAGG;IACH,SAFU,OAAO,CAEwB;IAGzC,2BAAsC;IAuCtC;;;OAGG;IACH,KAFU,SAAS,CAEO;IAE1B;;;OAGG;IACH,uBAFU,YAAY,CAEqD;IAI3E;;;;MAIC;IA6BD;;;OAGG;IACH,kBAFU,OAAO,CAEW;IAwIhC,wBAgCC;IApBG,oBAAwB;IAsB5B,2BA8CC;IAED,oBAiBC;IAED;;;OAGG;IACH,+CAUC;IAED,eAkDC;IAED;;;OAGG;IACH,sBAuGC;IAqBD;;OAEG;IACH,sBA+DC;IAED,aAEC;IAED;;OAEG;IACH,4BAOC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;;CAPxB;+BA94B8B,+BAA+B;wBAUtC,wBAAwB;0BApBtB,0CAA0C;wCAcN,iDAAiD;oCAG3E,iCAAiC;mBAElD,wBAAwB;+BArBZ,gDAAgD;iCAO9C,+CAA+C;8BAGlD,wBAAwB;6BALzB,yBAAyB;uCAIf,6DAA6D;4BASxE,0BAA0B;+BApBvB,iCAAiC;4CAapB,qDAAqD;AAejG;;GAEG;AAGH;IACI,gDAA2D;IAC3D,0BAAkC;IAClC,iCAAyC;CAC5C;6BAtC4B,sCAAsC;sBA2B7C,mBAAmB;yBAJhB,yBAAyB;8BALpB,kCAAkC;2BADrC,mCAAmC;8BADhC,kCAAkC;sBAZ1C,+BAA+B;+BAKtB,qCAAqC;4BAPxC,kCAAkC;oBAH1C,yBAAyB"}
+{"version":3,"file":"Engine.d.ts","sourceRoot":"","sources":["../../../src/engine/Engine.js"],"names":[],"mappings":";6BAqCa,OAAO,8BAA8B,EAAE,cAAc;AAwClE;IAiGI;;;;;;;;;OASG;IACH,sBARW,cAAc;QAEU,aAAa,GAArC,aAAa;QACK,cAAc,GAAhC,OAAO;QACW,WAAW,GAA7B,OAAO;QACW,KAAK,GAAvB,OAAO;OAiPjB;IAtSD;;;OAGG;IACH,UAFU,cAAc,GAAC,IAAI,CAEb;IAEhB;;;OAGG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb,qBAA4B;IAE5B;;;;;;;;;OASG;IACH,0BAFU,uBAAuB,CAEe;IAEhD;;;OAGG;IACH,kBAFU,mBAAmB,CAEO;IAEpC;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,mBAFU,kBAAkB,CAEa;IAoBrC;;;OAGG;IACH,UAFU,cAAc,CAEA;IAKxB;;;OAGG;IACH,aAFU,gBAAgB,CAEe;IAGzC,yCAAkE;IAK9D,6BAAkC;IAMtC;;;OAGG;IACH,cAFU,aAAa,MAAM,CAAC,CAK5B;IAEF,8CAiCE;IAgCF;;;OAGG;IACH,SAFU,WAAW,CAEoB;IAEzC;;;OAGG;IACH,oCAA0C;IAE1C;;;OAGG;IACH,sCAFU,2BAA2B,CAE+B;IAEpE,yBAAoC;IAGpC;;OAEG;IACH,aAAkB;IAElB;;;OAGG;IACH,SAFU,OAAO,CAEwB;IAGzC,2BAAsC;IAuCtC;;;OAGG;IACH,KAFU,SAAS,CAEO;IAE1B;;;OAGG;IACH,uBAFU,YAAY,CAEqD;IAI3E;;;;;MAKC;IA8BD;;;OAGG;IACH,kBAFU,OAAO,CAEW;IAwIhC,wBAgCC;IApBG,oBAAwB;IAsB5B,2BA8CC;IAED,oBAiBC;IAED;;;OAGG;IACH,+CAUC;IAED,eAkDC;IAED;;;OAGG;IACH,sBAuGC;IAqBD;;OAEG;IACH,sBAgEC;IAED,aAEC;IAED;;OAEG;IACH,4BAOC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;;CAPxB;+BAl5B8B,+BAA+B;wBAWtC,wBAAwB;0BArBtB,0CAA0C;wCAeN,iDAAiD;oCAG3E,iCAAiC;mBAElD,wBAAwB;+BAtBZ,gDAAgD;iCAO9C,+CAA+C;8BAGlD,wBAAwB;6BALzB,yBAAyB;uCAIf,6DAA6D;4BAUxE,0BAA0B;+BArBvB,iCAAiC;4CAapB,qDAAqD;AAgBjG;;GAEG;AAGH;IACI,gDAA2D;IAC3D,0BAAkC;IAClC,iCAAyC;CAC5C;6BAvC4B,sCAAsC;sBA4B7C,mBAAmB;yBAJhB,yBAAyB;8BALpB,kCAAkC;2BADrC,mCAAmC;8BAFhC,kCAAkC;8BAClC,kCAAkC;sBAb1C,+BAA+B;+BAKtB,qCAAqC;4BAPxC,kCAAkC;oBAH1C,yBAAyB"}

package/src/engine/Engine.js

@@ -21,6 +21,7 @@ import { EntityManager } from "./ecs/EntityManager.js";
 import { BinarySerializationRegistry } from "./ecs/storage/binary/BinarySerializationRegistry.js";
 import { GraphicsEngine } from './graphics3/GraphicsEngine.js';
 import { GamepadDevice } from "./input/devices/GamepadDevice.js";
+import { XRInputDevice } from "./input/devices/XRInputDevice.js";
 import KeyboardDevice from "./input/devices/KeyboardDevice.js";
 import { PointerDevice } from "./input/devices/PointerDevice.js";
 import { StaticKnowledgeDatabase, StaticKnowledgeState } from "./knowledge/database/StaticKnowledgeDatabase.js";
@@ -379,12 +380,14 @@ class Engine {
         this.devices = {
             pointer: new PointerDevice(this.viewStack.el),
             keyboard: new KeyboardDevice(this.viewStack.el),
-            gamepad: new GamepadDevice()
+            gamepad: new GamepadDevice(),
+            xr: new XRInputDevice()
         };
 
         this.devices.pointer.start();
         this.devices.keyboard.start();
         this.devices.gamepad.start();
+        this.devices.xr.start();
 
         /*
          Only the focused element receives keyboard events. `ViewStack` sets `tabindex` on its
@@ -869,6 +872,7 @@ class Engine {
         this.devices.pointer.stop();
         this.devices.keyboard.stop();
         this.devices.gamepad.stop();
+        this.devices.xr.stop();
 
         // shutdown entity manager
         if (!this.__using_external_entity_manager) {

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

@@ -0,0 +1,63 @@
+/**
+ * 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:
+ *
+ * @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(() => { });
+ *
+ * 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 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.
+ */
+export class XRInputDevice {
+    /** @readonly */
+    readonly left: XRInputHandle;
+    /** @readonly */
+    readonly right: XRInputHandle;
+    /** @readonly */
+    readonly none: XRInputHandle;
+    /** @readonly @type {XRInputHandle[]} Read only; membership is owned by the device. */
+    readonly sources: XRInputHandle[];
+    /** @readonly */
+    readonly on: {
+        /** @type {Signal} Dispatches the connected XRInputHandle. */
+        connected: Signal;
+        /** @type {Signal} Dispatches the XRInputHandle, already neutral and detached. */
+        disconnected: Signal;
+    };
+    /** @readonly @type {import('./xr/XRInputTypes.js').XRSession|null} Change through setSession. */
+    readonly session: import('./xr/XRInputTypes.js').XRSession | null;
+    /** @readonly @type {EventTarget|null} Change through setReferenceSpace. */
+    readonly referenceSpace: EventTarget | null;
+    get isRunning(): boolean;
+    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().
+     * @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 */
+    setReferenceSpace(referenceSpace: EventTarget | null): void;
+    /**
+     * No-op without a running session. Otherwise call only within that session's active frame callback.
+     * @param {import('./xr/XRInputTypes.js').XRFrame} [frame]
+     */
+    poll(frame?: import('./xr/XRInputTypes.js').XRFrame): void;
+    #private;
+}
+import { XRInputHandle } from "./xr/XRInputHandle.js";
+import Signal from "../../../core/events/signal/Signal.js";
+//# sourceMappingURL=XRInputDevice.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,386 @@
+import { assert } from "../../../core/assert.js";
+import Signal from "../../../core/events/signal/Signal.js";
+import { XRInputHandle } from "./xr/XRInputHandle.js";
+
+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:
+ *
+ * @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(() => { });
+ *
+ * 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 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.
+ */
+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. */
+    sources = [];
+    /** @readonly */
+    on = {
+        /** @type {Signal} Dispatches the connected XRInputHandle. */
+        connected: new Signal(),
+        /** @type {Signal} Dispatches the XRInputHandle, already neutral and detached. */
+        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. */
+    session = null;
+    /** @readonly @type {EventTarget|null} Change through setReferenceSpace. */
+    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; }
+
+    start() {
+        if (this.#busy) {
+            this.#pending.push(() => this.start());
+            return;
+        }
+        if (this.#running) {
+            return;
+        }
+        this.#busy = true;
+        try {
+            this.#running = true;
+            this.#listen(true);
+            this.#reconcile();
+            this.#sample(null);
+        } finally {
+            this.#finish();
+        }
+    }
+
+    /** Detach without ending the application's native XRSession. */
+    stop() {
+        if (this.#busy) {
+            this.#pending.push(() => this.stop());
+            return;
+        }
+        this.#busy = true;
+        try {
+            this.#detach();
+            this.#running = false;
+        } finally {
+            this.#finish();
+        }
+    }
+
+    /**
+     * May be called before start. Null detaches; attaching does not request permission or own session.end().
+     * @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;
+        }
+        if (this.#busy) {
+            this.#pending.push(() => this.setSession(session, referenceSpace));
+            return;
+        }
+        if (session === this.session) {
+            this.setReferenceSpace(referenceSpace);
+            return;
+        }
+        this.#busy = true;
+        try {
+            this.#detach();
+            this.session = session;
+            this.referenceSpace = session === null ? null : referenceSpace;
+            if (this.#running) {
+                this.#listen(true);
+                this.#reconcile();
+                this.#sample(null);
+            }
+        } finally {
+            this.#finish();
+        }
+    }
+
+    /** @param {EventTarget|null} referenceSpace */
+    setReferenceSpace(referenceSpace) {
+        assert.defined(referenceSpace, 'referenceSpace');
+        if (this.#busy) {
+            this.#pending.push(() => this.setReferenceSpace(referenceSpace));
+            return;
+        }
+        if (referenceSpace === this.referenceSpace) {
+            return;
+        }
+        this.#busy = true;
+        try {
+            if (this.referenceSpace !== null && this.#running) {
+                this.referenceSpace.removeEventListener('reset', this.#onReset);
+            }
+            this.referenceSpace = referenceSpace;
+            if (referenceSpace !== null && this.#running) {
+                referenceSpace.addEventListener('reset', this.#onReset);
+            }
+            this.#invalidatePoses();
+        } finally {
+            this.#finish();
+        }
+    }
+
+    /**
+     * No-op without a running session. Otherwise call only within that session's active frame callback.
+     * @param {import('./xr/XRInputTypes.js').XRFrame} [frame]
+     */
+    poll(frame) {
+        if (!this.#running || this.session === null || this.#busy) {
+            return;
+        }
+        assert.defined(frame, 'frame');
+        assert.equal(frame.session, this.session, 'frame.session');
+        this.#busy = true;
+        try {
+            this.#reconcile();
+            this.#sample(frame);
+        } finally {
+            this.#finish();
+        }
+    }
+
+    /** @param {boolean} add */
+    #listen(add) {
+        const method = add ? 'addEventListener' : 'removeEventListener';
+        if (this.session !== null) {
+            for (let i = 0; i < SESSION_EVENTS.length; i++) {
+                this.session[method](SESSION_EVENTS[i], this.#onEvent);
+            }
+        }
+        if (this.referenceSpace !== null) {
+            this.referenceSpace[method]('reset', this.#onReset);
+        }
+    }
+
+    #detach() {
+        this.#listen(false);
+        this.session = null;
+        this.referenceSpace = null;
+        this.#clear();
+        for (let i = 0; i < this.#slots.length; i++) {
+            this.#slots[i].bind(null);
+        }
+        while (this.sources.length > 0) {
+            const handle = this.sources.pop();
+            this.#handles.delete(handle.nativeSource);
+            handle.bind(null);
+            this.on.disconnected.send1(handle);
+        }
+        this.#connected.length = 0;
+    }
+
+    /** @param {import('./xr/XRInputTypes.js').XRInputSource} source */
+    #contains(source) {
+        const sources = this.session.inputSources;
+        for (let i = 0; i < sources.length; i++) {
+            if (sources[i] === source) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    #reconcile() {
+        if (this.session === null) {
+            return;
+        }
+        for (let i = this.sources.length - 1; i >= 0; i--) {
+            const handle = this.sources[i];
+            const source = handle.nativeSource;
+            if (!this.#contains(source)) {
+                this.sources.splice(i, 1);
+                this.#handles.delete(source);
+                for (let j = 0; j < this.#slots.length; j++) {
+                    if (this.#slots[j].nativeSource === source) {
+                        this.#slots[j].bind(null);
+                    }
+                }
+                handle.bind(null);
+                this.on.disconnected.send1(handle);
+            }
+        }
+        const sources = this.session.inputSources;
+        for (let i = 0; i < sources.length; i++) {
+            const source = sources[i];
+            if (!this.#handles.has(source)) {
+                const handle = new XRInputHandle();
+                handle.bind(source);
+                this.#handles.set(source, handle);
+                this.sources.push(handle);
+                this.#connected.push(handle);
+            }
+        }
+        this.#bindSlot(this.left, 'left');
+        this.#bindSlot(this.right, 'right');
+        this.#bindSlot(this.none, 'none');
+    }
+
+    /** @param {XRInputHandle} slot @param {string} handedness */
+    #bindSlot(slot, handedness) {
+        if (slot.connected) {
+            return;
+        }
+        for (let i = 0; i < this.sources.length; i++) {
+            const source = this.sources[i].nativeSource;
+            if (source.handedness === handedness) {
+                slot.bind(source);
+                return;
+            }
+        }
+    }
+
+    /** @param {import('./xr/XRInputTypes.js').XRFrame|null} frame */
+    #sample(frame) {
+        if (this.session !== null && this.session.visibilityState === 'visible') {
+            for (let i = 0; i < this.sources.length; i++) {
+                this.sources[i].sample(frame, this.referenceSpace);
+            }
+            for (let i = 0; i < this.#slots.length; i++) {
+                this.#slots[i].sample(frame, this.referenceSpace);
+            }
+            this.#flush();
+        } else {
+            this.#clear();
+        }
+        for (let i = 0; i < this.#connected.length; i++) {
+            this.on.connected.send1(this.#connected[i]);
+        }
+        this.#connected.length = 0;
+    }
+
+    #clear() {
+        for (let i = 0; i < this.sources.length; i++) {
+            this.sources[i].clear();
+        }
+        for (let i = 0; i < this.#slots.length; i++) {
+            this.#slots[i].clear();
+        }
+        this.#flush();
+    }
+
+    #flush() {
+        for (let i = 0; i < this.sources.length; i++) {
+            this.sources[i].flush();
+        }
+        for (let i = 0; i < this.#slots.length; i++) {
+            this.#slots[i].flush();
+        }
+    }
+
+    #invalidatePoses() {
+        for (let i = 0; i < this.sources.length; i++) {
+            this.sources[i].invalidatePoses();
+        }
+        for (let i = 0; i < this.#slots.length; i++) {
+            this.#slots[i].invalidatePoses();
+        }
+    }
+
+    #onReset = () => {
+        if (this.#busy) {
+            this.#pending.push(() => this.#onReset());
+            return;
+        }
+        this.#busy = true;
+        try {
+            this.#invalidatePoses();
+        } finally {
+            this.#finish();
+        }
+    };
+
+    /** @param {import('./xr/XRInputTypes.js').XRSessionInputEvent} event */
+    #onEvent = (event) => {
+        if (!this.#running || event.currentTarget !== this.session || this.#busy) {
+            return;
+        }
+        this.#busy = true;
+        try {
+            if (event.type === 'end') {
+                this.#detach();
+                return;
+            }
+            this.#reconcile();
+            const frame = event.frame === undefined ? null : event.frame;
+            if (frame !== null && frame.session !== this.session) {
+                return;
+            }
+            this.#sample(frame);
+            if (this.session.visibilityState !== 'visible' || event.inputSource === undefined) {
+                return;
+            }
+            const handle = this.#handles.get(event.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) {
+                    this.#actionEvent(slot, event.type);
+                }
+            }
+        } finally {
+            this.#finish();
+        }
+    };
+
+    /** @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;
+        }
+    }
+
+    #finish() {
+        this.#busy = false;
+        if (this.#draining) {
+            return;
+        }
+        this.#draining = true;
+        try {
+            while (this.#pending.length > 0) {
+                this.#pending.shift()();
+            }
+        } finally {
+            this.#draining = false;
+        }
+    }
+}

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

@@ -0,0 +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.
+ *
+ * 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.
+ */
+export class XRInputAction extends Vector1 {
+    /** @readonly @type {Signal} No arguments. */
+    readonly completed: Signal;
+    /** @readonly @type {Signal} No arguments. */
+    readonly cancelled: Signal;
+    /** @type {XRInputValueSource} Do not modify directly. */
+    valueSource: XRInputValueSource;
+    /**
+     * @internal
+     * @param {XRInputValueSource} source
+     * @param {number} value
+     */
+    update(source: XRInputValueSource, value: number): 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. */
+    complete(): void;
+    /** @internal */
+    end(): void;
+    /** @internal Stage cancellation so the whole handle can become neutral before its notification. */
+    reset(): void;
+    /** @internal */
+    flushCancellation(): void;
+    #private;
+}
+import { Vector1 } from "../../../../core/geom/Vector1.js";
+import Signal from "../../../../core/events/signal/Signal.js";
+import { XRInputValueSource } from "./XRInputValueSource.js";
+//# sourceMappingURL=XRInputAction.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,85 @@
+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.
+ *
+ * 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.
+ */
+export class XRInputAction extends Vector1 {
+    /** @readonly @type {Signal} No arguments. */
+    completed = new Signal();
+
+    /** @readonly @type {Signal} No arguments. */
+    cancelled = new Signal();
+
+    /** @type {XRInputValueSource} Do not modify directly. */
+    valueSource = XRInputValueSource.Unavailable;
+
+    /** 0: idle, 1: awaiting outcome, 2: completed, awaiting native end. */
+    #interaction = 0;
+
+    #cancelled = false;
+
+    /**
+     * @internal
+     * @param {XRInputValueSource} source
+     * @param {number} value
+     */
+    update(source, value) {
+        this.valueSource = source;
+        this.set(source === XRInputValueSource.Gamepad ? value : source === XRInputValueSource.Action && this.#interaction !== 0 ? 1 : 0);
+    }
+
+    /** @internal Called only for a native start, never inferred from the amount. */
+    begin() {
+        if (this.#interaction !== 0) {
+            return;
+        }
+        this.#interaction = 1;
+        if (this.valueSource === XRInputValueSource.Action) {
+            this.set(1);
+        }
+    }
+
+    /** @internal A completion without an observed start is not replayed after a rebind/interruption. */
+    complete() {
+        if (this.#interaction !== 1) {
+            return;
+        }
+        this.#interaction = 2;
+        this.completed.send0();
+    }
+
+    /** @internal */
+    end() {
+        const cancelled = this.#interaction === 1;
+        this.#interaction = 0;
+        if (this.valueSource === XRInputValueSource.Action) {
+            this.set(0);
+        }
+        if (cancelled) {
+            this.cancelled.send0();
+        }
+    }
+
+    /** @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);
+    }
+
+    /** @internal */
+    flushCancellation() {
+        if (this.#cancelled) {
+            this.#cancelled = false;
+            this.cancelled.send0();
+        }
+    }
+}

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

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+export class XRInputButton extends Vector1 {
+    /** @readonly */
+    readonly pressed: InputDeviceSwitch;
+    /** @readonly */
+    readonly touched: InputDeviceSwitch;
+    /**
+     * 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
+     */
+    update(button: {
+        value: number;
+        pressed: boolean;
+        touched: boolean;
+    } | undefined): void;
+    /** @internal */
+    flushSwitches(): void;
+    #private;
+}
+import { Vector1 } from "../../../../core/geom/Vector1.js";
+import { InputDeviceSwitch } from "../InputDeviceSwitch.js";
+//# sourceMappingURL=XRInputButton.d.ts.map

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

@@ -0,0 +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"}