iwer 2.1.1 → 2.2.0

package/build/iwer.module.js

@@ -758,7 +758,7 @@ function cross(out, a, b) {
  * @param {Number} t interpolation amount, in the range [0-1], between the two inputs
  * @returns {vec3} out
  */
-function lerp(out, a, b, t) {
+function lerp$1(out, a, b, t) {
   var ax = a[0];
   var ay = a[1];
   var az = a[2];
@@ -768,6 +768,27 @@ function lerp(out, a, b, t) {
   return out;
 }
 
+/**
+ * Transforms the vec3 with a mat4.
+ * 4th vector component is implicitly '1'
+ *
+ * @param {vec3} out the receiving vector
+ * @param {ReadonlyVec3} a the vector to transform
+ * @param {ReadonlyMat4} m matrix to transform with
+ * @returns {vec3} out
+ */
+function transformMat4$1(out, a, m) {
+  var x = a[0],
+    y = a[1],
+    z = a[2];
+  var w = m[3] * x + m[7] * y + m[11] * z + m[15];
+  w = w || 1.0;
+  out[0] = (m[0] * x + m[4] * y + m[8] * z + m[12]) / w;
+  out[1] = (m[1] * x + m[5] * y + m[9] * z + m[13]) / w;
+  out[2] = (m[2] * x + m[6] * y + m[10] * z + m[14]) / w;
+  return out;
+}
+
 /**
  * Transforms the vec3 with a quat
  * Can also be used for dual quaternions. (Multiply it with the real part)
@@ -1532,6 +1553,1435 @@ class Quaternion {
     }
 }
 
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Convert a Vector3-like object to a plain Vec3 object
+ */
+function vec3ToObj(v) {
+    return { x: v.x, y: v.y, z: v.z };
+}
+/**
+ * Convert a Quaternion-like object to a plain Quat object
+ */
+function quatToObj(q) {
+    return { x: q.x, y: q.y, z: q.z, w: q.w };
+}
+/**
+ * Convert quaternion to euler angles (in degrees)
+ * Uses YXZ order (yaw-pitch-roll) which is standard for XR:
+ * - Yaw: rotation around Y axis (turning left/right)
+ * - Pitch: rotation around X axis (looking up/down)
+ * - Roll: rotation around Z axis (tilting head)
+ */
+function quatToEuler(q) {
+    const { x, y, z, w } = q;
+    const RAD_TO_DEG = 180 / Math.PI;
+    // YXZ order
+    const sinp = Math.max(-1, Math.min(1, 2 * (w * x - y * z)));
+    let pitch;
+    if (Math.abs(sinp) >= 1) {
+        pitch = (Math.sign(sinp) * Math.PI) / 2;
+    }
+    else {
+        pitch = Math.asin(sinp);
+    }
+    const siny_cosp = 2 * (w * y + x * z);
+    const cosy_cosp = 1 - 2 * (x * x + y * y);
+    const yaw = Math.atan2(siny_cosp, cosy_cosp);
+    const sinr_cosp = 2 * (w * z + x * y);
+    const cosr_cosp = 1 - 2 * (x * x + z * z);
+    const roll = Math.atan2(sinr_cosp, cosr_cosp);
+    return {
+        pitch: pitch * RAD_TO_DEG,
+        yaw: yaw * RAD_TO_DEG,
+        roll: roll * RAD_TO_DEG,
+    };
+}
+/**
+ * Convert euler angles (in degrees) to quaternion
+ * Uses YXZ order (yaw-pitch-roll) which is standard for XR:
+ * - Yaw: rotation around Y axis (turning left/right)
+ * - Pitch: rotation around X axis (looking up/down)
+ * - Roll: rotation around Z axis (tilting head)
+ * Missing angles default to 0.
+ */
+function eulerToQuat(euler) {
+    var _a, _b, _c;
+    const DEG_TO_RAD = Math.PI / 180;
+    const pitch = ((_a = euler.pitch) !== null && _a !== void 0 ? _a : 0) * DEG_TO_RAD; // X-axis
+    const yaw = ((_b = euler.yaw) !== null && _b !== void 0 ? _b : 0) * DEG_TO_RAD; // Y-axis
+    const roll = ((_c = euler.roll) !== null && _c !== void 0 ? _c : 0) * DEG_TO_RAD; // Z-axis
+    // Half angles
+    const cx = Math.cos(pitch * 0.5);
+    const sx = Math.sin(pitch * 0.5);
+    const cy = Math.cos(yaw * 0.5);
+    const sy = Math.sin(yaw * 0.5);
+    const cz = Math.cos(roll * 0.5);
+    const sz = Math.sin(roll * 0.5);
+    // YXZ order: first yaw, then pitch, then roll
+    return {
+        w: cx * cy * cz + sx * sy * sz,
+        x: sx * cy * cz + cx * sy * sz,
+        y: cx * sy * cz - sx * cy * sz,
+        z: cx * cy * sz - sx * sy * cz,
+    };
+}
+/**
+ * Calculate normalized direction vector from one point to another
+ * Returns default forward direction (0, 0, -1) if points are coincident
+ */
+function directionTo(from, to) {
+    const dx = to.x - from.x;
+    const dy = to.y - from.y;
+    const dz = to.z - from.z;
+    const length = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    if (length === 0) {
+        return { x: 0, y: 0, z: -1 }; // Default forward (WebXR convention)
+    }
+    return {
+        x: dx / length,
+        y: dy / length,
+        z: dz / length,
+    };
+}
+/**
+ * Calculate gimbal-style look rotation (yaw + pitch only, roll = 0)
+ * This keeps the camera/headset level while looking at a target.
+ * @param direction - The direction to look towards
+ * @returns Quaternion with only yaw and pitch, no roll
+ */
+function lookRotationGimbal(direction) {
+    // Calculate horizontal distance
+    const horizontalDist = Math.sqrt(direction.x * direction.x + direction.z * direction.z);
+    // Calculate yaw: rotation around Y axis to face target horizontally
+    // atan2(-z, -x) gives angle from negative Z axis (forward in WebXR)
+    // We use -z, x to match WebXR's -Z forward convention
+    let yaw = 0;
+    if (horizontalDist > 0.0001) {
+        yaw = Math.atan2(-direction.x, -direction.z);
+    }
+    // Calculate pitch: rotation around X axis to look up/down
+    // Positive direction.y (target above) = positive pitch (look up)
+    // Negative direction.y (target below) = negative pitch (look down)
+    const pitch = Math.atan2(direction.y, horizontalDist);
+    // Convert to degrees and create quaternion (roll = 0)
+    const RAD_TO_DEG = 180 / Math.PI;
+    return eulerToQuat({
+        pitch: pitch * RAD_TO_DEG,
+        yaw: yaw * RAD_TO_DEG,
+        roll: 0,
+    });
+}
+/**
+ * Calculate quaternion that looks from origin towards a direction
+ * @param direction - The direction to look towards (will be normalized)
+ * @param up - The up vector (default: world up Y-axis)
+ */
+function lookRotation(direction, up = { x: 0, y: 1, z: 0 }) {
+    // Normalize direction
+    const dirLen = Math.sqrt(direction.x * direction.x +
+        direction.y * direction.y +
+        direction.z * direction.z);
+    if (dirLen === 0) {
+        return { x: 0, y: 0, z: 0, w: 1 }; // Identity quaternion
+    }
+    const forward = {
+        x: direction.x / dirLen,
+        y: direction.y / dirLen,
+        z: direction.z / dirLen,
+    };
+    // Calculate right vector (cross product of forward and up, NOT up and forward)
+    // forward × up gives correct right-hand orientation
+    const right = {
+        x: forward.y * up.z - forward.z * up.y,
+        y: forward.z * up.x - forward.x * up.z,
+        z: forward.x * up.y - forward.y * up.x,
+    };
+    const rightLen = Math.sqrt(right.x * right.x + right.y * right.y + right.z * right.z);
+    if (rightLen === 0) {
+        // Direction is parallel to up, choose a different up
+        const altUp = { x: 1, y: 0, z: 0 };
+        right.x = forward.y * altUp.z - forward.z * altUp.y;
+        right.y = forward.z * altUp.x - forward.x * altUp.z;
+        right.z = forward.x * altUp.y - forward.y * altUp.x;
+        const altRightLen = Math.sqrt(right.x * right.x + right.y * right.y + right.z * right.z);
+        right.x /= altRightLen;
+        right.y /= altRightLen;
+        right.z /= altRightLen;
+    }
+    else {
+        right.x /= rightLen;
+        right.y /= rightLen;
+        right.z /= rightLen;
+    }
+    // Recalculate up (cross product of right and forward for proper orientation)
+    const newUp = {
+        x: right.y * forward.z - right.z * forward.y,
+        y: right.z * forward.x - right.x * forward.z,
+        z: right.x * forward.y - right.y * forward.x,
+    };
+    // Build rotation matrix and convert to quaternion
+    // Matrix: [right, newUp, -forward] (column vectors)
+    const m00 = right.x, m01 = newUp.x, m02 = -forward.x;
+    const m10 = right.y, m11 = newUp.y, m12 = -forward.y;
+    const m20 = right.z, m21 = newUp.z, m22 = -forward.z;
+    const trace = m00 + m11 + m22;
+    let qw, qx, qy, qz;
+    if (trace > 0) {
+        const s = 0.5 / Math.sqrt(trace + 1.0);
+        qw = 0.25 / s;
+        qx = (m21 - m12) * s;
+        qy = (m02 - m20) * s;
+        qz = (m10 - m01) * s;
+    }
+    else if (m00 > m11 && m00 > m22) {
+        const s = 2.0 * Math.sqrt(1.0 + m00 - m11 - m22);
+        qw = (m21 - m12) / s;
+        qx = 0.25 * s;
+        qy = (m01 + m10) / s;
+        qz = (m02 + m20) / s;
+    }
+    else if (m11 > m22) {
+        const s = 2.0 * Math.sqrt(1.0 + m11 - m00 - m22);
+        qw = (m02 - m20) / s;
+        qx = (m01 + m10) / s;
+        qy = 0.25 * s;
+        qz = (m12 + m21) / s;
+    }
+    else {
+        const s = 2.0 * Math.sqrt(1.0 + m22 - m00 - m11);
+        qw = (m10 - m01) / s;
+        qx = (m02 + m20) / s;
+        qy = (m12 + m21) / s;
+        qz = 0.25 * s;
+    }
+    // Normalize the quaternion to ensure unit length
+    const len = Math.sqrt(qx * qx + qy * qy + qz * qz + qw * qw);
+    if (len > 0) {
+        qx /= len;
+        qy /= len;
+        qz /= len;
+        qw /= len;
+    }
+    return { x: qx, y: qy, z: qz, w: qw };
+}
+/**
+ * Wait for a condition to become true, checking each animation frame
+ */
+function waitForCondition(condition, timeoutMs = 5000) {
+    return new Promise((resolve, reject) => {
+        const startTime = Date.now();
+        const check = () => {
+            if (condition()) {
+                resolve();
+            }
+            else if (Date.now() - startTime > timeoutMs) {
+                reject(new Error('Timeout waiting for condition'));
+            }
+            else {
+                requestAnimationFrame(check);
+            }
+        };
+        check();
+    });
+}
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Check if an orientation input is euler angles (has any of pitch, yaw, or roll)
+ */
+function isEulerRotation(orientation) {
+    return 'pitch' in orientation || 'yaw' in orientation || 'roll' in orientation;
+}
+/**
+ * Normalize an orientation input to a quaternion
+ */
+function normalizeOrientation(orientation) {
+    if (isEulerRotation(orientation)) {
+        return eulerToQuat(orientation);
+    }
+    return orientation;
+}
+/**
+ * Linear interpolation for numbers
+ */
+function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+/**
+ * Linear interpolation for Vec3
+ */
+function lerpVec3(a, b, t) {
+    return {
+        x: lerp(a.x, b.x, t),
+        y: lerp(a.y, b.y, t),
+        z: lerp(a.z, b.z, t),
+    };
+}
+/**
+ * Spherical linear interpolation for quaternions
+ */
+function slerpQuat(a, b, t) {
+    // Compute dot product
+    let dot = a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w;
+    // If dot is negative, negate one quaternion to take shorter path
+    let bx = b.x, by = b.y, bz = b.z, bw = b.w;
+    if (dot < 0) {
+        dot = -dot;
+        bx = -bx;
+        by = -by;
+        bz = -bz;
+        bw = -bw;
+    }
+    // If quaternions are very close, use linear interpolation
+    if (dot > 0.9995) {
+        const result = {
+            x: lerp(a.x, bx, t),
+            y: lerp(a.y, by, t),
+            z: lerp(a.z, bz, t),
+            w: lerp(a.w, bw, t),
+        };
+        // Normalize
+        const len = Math.sqrt(result.x * result.x +
+            result.y * result.y +
+            result.z * result.z +
+            result.w * result.w);
+        return {
+            x: result.x / len,
+            y: result.y / len,
+            z: result.z / len,
+            w: result.w / len,
+        };
+    }
+    // Standard slerp
+    const theta0 = Math.acos(dot);
+    const theta = theta0 * t;
+    const sinTheta = Math.sin(theta);
+    const sinTheta0 = Math.sin(theta0);
+    const s0 = Math.cos(theta) - (dot * sinTheta) / sinTheta0;
+    const s1 = sinTheta / sinTheta0;
+    return {
+        x: s0 * a.x + s1 * bx,
+        y: s0 * a.y + s1 * by,
+        z: s0 * a.z + s1 * bz,
+        w: s0 * a.w + s1 * bw,
+    };
+}
+/**
+ * RemoteControlInterface provides frame-synchronized programmatic control of an XRDevice.
+ *
+ * This class implements a command queue that processes actions during each frame update,
+ * enabling smooth animations and coordinated control with DevUI.
+ *
+ * Key features:
+ * - Frame-synchronized execution: Commands are queued and processed during frame update
+ * - Duration-based actions: Smooth animations via lerp over multiple frames
+ * - Automatic capture/release: Captures device on first command, releases 30s after queue empties
+ * - Unified device identifiers: 'headset', 'controller-left', 'hand-right', etc.
+ *
+ * Usage:
+ * ```typescript
+ * import { XRDevice, metaQuest3 } from 'iwer';
+ *
+ * const device = new XRDevice(metaQuest3);
+ * device.installRuntime();
+ *
+ * // Get transform
+ * const result = await device.remote.dispatch('get_transform', { device: 'headset' });
+ *
+ * // Animate headset to new position over 1 second
+ * await device.remote.dispatch('animate_to', {
+ *   device: 'headset',
+ *   position: { x: 0, y: 1.6, z: -1 },
+ *   duration: 1.0
+ * });
+ * ```
+ */
+class RemoteControlInterface {
+    constructor(device) {
+        this.commandQueue = [];
+        this._isCaptured = false;
+        this.releaseTimer = null;
+        this.actionIdCounter = 0;
+        /** Release timeout in milliseconds (default: 30000 = 30 seconds) */
+        this.RELEASE_TIMEOUT_MS = 30000;
+        this.device = device;
+    }
+    generateActionId() {
+        return `action_${++this.actionIdCounter}`;
+    }
+    // =============================================================================
+    // Public Properties
+    // =============================================================================
+    /**
+     * Whether the device is currently captured for programmatic control.
+     * When true, DevUI should go into passive mode (sync FROM device only).
+     */
+    get isCaptured() {
+        return this._isCaptured;
+    }
+    /**
+     * Number of pending actions in the queue
+     */
+    get queueLength() {
+        return this.commandQueue.length;
+    }
+    // =============================================================================
+    // Queue Management
+    // =============================================================================
+    /**
+     * Enqueue a discrete action for processing
+     */
+    enqueueDiscrete(method, params) {
+        return new Promise((resolve, reject) => {
+            const action = {
+                type: 'discrete',
+                id: this.generateActionId(),
+                method,
+                params,
+                resolve,
+                reject,
+            };
+            this.commandQueue.push(action);
+        });
+    }
+    /**
+     * Enqueue a duration action for processing
+     */
+    enqueueDuration(method, params, durationMs, startState, targetState) {
+        return new Promise((resolve, reject) => {
+            const action = {
+                type: 'duration',
+                id: this.generateActionId(),
+                method,
+                params,
+                durationMs,
+                elapsedMs: 0,
+                startState,
+                targetState,
+                resolve,
+                reject,
+            };
+            this.commandQueue.push(action);
+        });
+    }
+    /**
+     * Update method called each frame by XRDevice.
+     * Processes the command queue and handles duration-based animations.
+     *
+     * @param deltaTimeMs - Time since last frame in milliseconds
+     */
+    update(deltaTimeMs) {
+        if (this.commandQueue.length === 0) {
+            return;
+        }
+        // Always cancel pending release while queue is active
+        this.cancelReleaseTimer();
+        // Activate capture mode
+        if (!this._isCaptured) {
+            this._isCaptured = true;
+            this.device.controlMode = 'programmatic';
+        }
+        while (this.commandQueue.length > 0) {
+            const action = this.commandQueue[0];
+            if (action.type === 'discrete') {
+                // Execute discrete action immediately
+                try {
+                    const result = this.executeDiscreteAction(action);
+                    action.resolve(result);
+                }
+                catch (error) {
+                    action.reject(error);
+                }
+                this.commandQueue.shift();
+                // Continue to next action
+            }
+            else {
+                // Duration action - lerp by delta time
+                action.elapsedMs += deltaTimeMs;
+                if (action.elapsedMs >= action.durationMs) {
+                    // Complete - apply final state
+                    this.applyDurationFinalState(action);
+                    action.resolve(this.getDurationResult(action));
+                    this.commandQueue.shift();
+                    // Continue to next action
+                }
+                else {
+                    // In progress - lerp
+                    const t = action.elapsedMs / action.durationMs;
+                    this.applyDurationLerpState(action, t);
+                    // Stop processing - wait for next frame
+                    break;
+                }
+            }
+        }
+        // Notify state change
+        this.device.notifyStateChange();
+        // Start release timer if queue is empty
+        if (this.commandQueue.length === 0) {
+            this.startReleaseTimer();
+        }
+    }
+    startReleaseTimer() {
+        this.cancelReleaseTimer();
+        this.releaseTimer = setTimeout(() => {
+            this._isCaptured = false;
+            this.device.controlMode = 'manual';
+            this.releaseTimer = null;
+        }, this.RELEASE_TIMEOUT_MS);
+    }
+    cancelReleaseTimer() {
+        if (this.releaseTimer !== null) {
+            clearTimeout(this.releaseTimer);
+            this.releaseTimer = null;
+        }
+    }
+    // =============================================================================
+    // Device Resolution
+    // =============================================================================
+    /**
+     * Get the transform (position, quaternion) for a device
+     */
+    getDeviceTransform(deviceId) {
+        switch (deviceId) {
+            case 'headset':
+                return {
+                    position: vec3ToObj(this.device.position),
+                    orientation: quatToObj(this.device.quaternion),
+                };
+            case 'controller-left': {
+                const controller = this.device.controllers.left;
+                if (!controller)
+                    throw new Error('Left controller not available');
+                return {
+                    position: vec3ToObj(controller.position),
+                    orientation: quatToObj(controller.quaternion),
+                };
+            }
+            case 'controller-right': {
+                const controller = this.device.controllers.right;
+                if (!controller)
+                    throw new Error('Right controller not available');
+                return {
+                    position: vec3ToObj(controller.position),
+                    orientation: quatToObj(controller.quaternion),
+                };
+            }
+            case 'hand-left': {
+                const hand = this.device.hands.left;
+                if (!hand)
+                    throw new Error('Left hand not available');
+                return {
+                    position: vec3ToObj(hand.position),
+                    orientation: quatToObj(hand.quaternion),
+                };
+            }
+            case 'hand-right': {
+                const hand = this.device.hands.right;
+                if (!hand)
+                    throw new Error('Right hand not available');
+                return {
+                    position: vec3ToObj(hand.position),
+                    orientation: quatToObj(hand.quaternion),
+                };
+            }
+            default:
+                throw new Error(`Unknown device: ${deviceId}`);
+        }
+    }
+    /**
+     * Set the transform for a device
+     */
+    setDeviceTransform(deviceId, position, orientation) {
+        switch (deviceId) {
+            case 'headset':
+                if (position) {
+                    this.device.position.set(position.x, position.y, position.z);
+                }
+                if (orientation) {
+                    this.device.quaternion.set(orientation.x, orientation.y, orientation.z, orientation.w);
+                }
+                break;
+            case 'controller-left': {
+                const controller = this.device.controllers.left;
+                if (!controller)
+                    throw new Error('Left controller not available');
+                if (position) {
+                    controller.position.set(position.x, position.y, position.z);
+                }
+                if (orientation) {
+                    controller.quaternion.set(orientation.x, orientation.y, orientation.z, orientation.w);
+                }
+                break;
+            }
+            case 'controller-right': {
+                const controller = this.device.controllers.right;
+                if (!controller)
+                    throw new Error('Right controller not available');
+                if (position) {
+                    controller.position.set(position.x, position.y, position.z);
+                }
+                if (orientation) {
+                    controller.quaternion.set(orientation.x, orientation.y, orientation.z, orientation.w);
+                }
+                break;
+            }
+            case 'hand-left': {
+                const hand = this.device.hands.left;
+                if (!hand)
+                    throw new Error('Left hand not available');
+                if (position) {
+                    hand.position.set(position.x, position.y, position.z);
+                }
+                if (orientation) {
+                    hand.quaternion.set(orientation.x, orientation.y, orientation.z, orientation.w);
+                }
+                break;
+            }
+            case 'hand-right': {
+                const hand = this.device.hands.right;
+                if (!hand)
+                    throw new Error('Right hand not available');
+                if (position) {
+                    hand.position.set(position.x, position.y, position.z);
+                }
+                if (orientation) {
+                    hand.quaternion.set(orientation.x, orientation.y, orientation.z, orientation.w);
+                }
+                break;
+            }
+            default:
+                throw new Error(`Unknown device: ${deviceId}`);
+        }
+    }
+    /**
+     * Transform a position from XR-origin-relative coordinates to GlobalSpace.
+     * The XR origin is defined by the first reference space requested by the app.
+     * This is necessary because device positions are in GlobalSpace, but positions
+     * from get_object_transform are relative to the XR origin.
+     */
+    transformXROriginToGlobal(position) {
+        var _a, _b;
+        const session = this.device.activeSession;
+        if (!session) {
+            return position;
+        }
+        const refSpaces = (_a = session[P_SESSION]) === null || _a === void 0 ? void 0 : _a.referenceSpaces;
+        if (!refSpaces || refSpaces.length === 0) {
+            return position;
+        }
+        // Use the first reference space (primary one requested by app)
+        const primaryRefSpace = refSpaces[0];
+        const offsetMatrix = (_b = primaryRefSpace[P_SPACE]) === null || _b === void 0 ? void 0 : _b.offsetMatrix;
+        if (!offsetMatrix) {
+            return position;
+        }
+        // Transform position from XR-origin space to GlobalSpace
+        const posVec = fromValues$2(position.x, position.y, position.z);
+        transformMat4$1(posVec, posVec, offsetMatrix);
+        return {
+            x: posVec[0],
+            y: posVec[1],
+            z: posVec[2],
+        };
+    }
+    /**
+     * Get the select value for an input device (trigger for controller, pinch for hand)
+     */
+    getDeviceSelectValue(deviceId) {
+        var _a, _b, _c, _d, _e, _f, _g, _h;
+        switch (deviceId) {
+            case 'controller-left':
+                return (_b = (_a = this.device.controllers.left) === null || _a === void 0 ? void 0 : _a.getButtonValue('trigger')) !== null && _b !== void 0 ? _b : 0;
+            case 'controller-right':
+                return (_d = (_c = this.device.controllers.right) === null || _c === void 0 ? void 0 : _c.getButtonValue('trigger')) !== null && _d !== void 0 ? _d : 0;
+            case 'hand-left':
+                return (_f = (_e = this.device.hands.left) === null || _e === void 0 ? void 0 : _e.pinchValue) !== null && _f !== void 0 ? _f : 0;
+            case 'hand-right':
+                return (_h = (_g = this.device.hands.right) === null || _g === void 0 ? void 0 : _g.pinchValue) !== null && _h !== void 0 ? _h : 0;
+            default:
+                throw new Error(`Unknown input device: ${deviceId}`);
+        }
+    }
+    /**
+     * Set the select value for an input device
+     */
+    setDeviceSelectValue(deviceId, value) {
+        var _a, _b, _c, _d;
+        switch (deviceId) {
+            case 'controller-left':
+                (_a = this.device.controllers.left) === null || _a === void 0 ? void 0 : _a.updateButtonValue('trigger', value);
+                break;
+            case 'controller-right':
+                (_b = this.device.controllers.right) === null || _b === void 0 ? void 0 : _b.updateButtonValue('trigger', value);
+                break;
+            case 'hand-left':
+                (_c = this.device.hands.left) === null || _c === void 0 ? void 0 : _c.updatePinchValue(value);
+                break;
+            case 'hand-right':
+                (_d = this.device.hands.right) === null || _d === void 0 ? void 0 : _d.updatePinchValue(value);
+                break;
+            default:
+                throw new Error(`Unknown input device: ${deviceId}`);
+        }
+    }
+    /**
+     * Set connected state for an input device
+     */
+    setDeviceConnected(deviceId, connected) {
+        switch (deviceId) {
+            case 'controller-left':
+                if (this.device.controllers.left) {
+                    this.device.controllers.left.connected = connected;
+                }
+                break;
+            case 'controller-right':
+                if (this.device.controllers.right) {
+                    this.device.controllers.right.connected = connected;
+                }
+                break;
+            case 'hand-left':
+                if (this.device.hands.left) {
+                    this.device.hands.left.connected = connected;
+                }
+                break;
+            case 'hand-right':
+                if (this.device.hands.right) {
+                    this.device.hands.right.connected = connected;
+                }
+                break;
+            default:
+                throw new Error(`Unknown input device: ${deviceId}`);
+        }
+    }
+    // =============================================================================
+    // Discrete Action Execution
+    // =============================================================================
+    executeDiscreteAction(action) {
+        const { method, params } = action;
+        switch (method) {
+            // Session tools
+            case 'get_session_status':
+                return this.executeGetSessionStatus();
+            case 'accept_session':
+                return this.executeAcceptSession();
+            case 'end_session':
+                return this.executeEndSession();
+            // Transform tools
+            case 'get_transform':
+                return this.executeGetTransform(params);
+            case 'set_transform':
+                return this.executeSetTransform(params);
+            case 'look_at':
+                return this.executeLookAt(params);
+            // Input tools
+            case 'set_input_mode':
+                return this.executeSetInputMode(params);
+            case 'set_connected':
+                return this.executeSetConnected(params);
+            case 'get_select_value':
+                return this.executeGetSelectValue(params);
+            case 'set_select_value':
+                return this.executeSetSelectValue(params);
+            // Gamepad tools
+            case 'get_gamepad_state':
+                return this.executeGetGamepadState(params);
+            case 'set_gamepad_state':
+                return this.executeSetGamepadState(params);
+            // State tools
+            case 'get_device_state':
+                return this.executeGetDeviceState();
+            case 'set_device_state':
+                return this.executeSetDeviceState(params);
+            case 'capture_canvas':
+                return this.executeCaptureCanvas(params);
+            // Internal select sequence actions
+            case '_select_press': {
+                const deviceId = params.device;
+                this.setDeviceSelectValue(deviceId, 1);
+                return undefined;
+            }
+            case '_select_release': {
+                const deviceId = params.device;
+                this.setDeviceSelectValue(deviceId, 0);
+                return undefined;
+            }
+            default:
+                throw new Error(`Unknown method: ${method}`);
+        }
+    }
+    // =============================================================================
+    // Session Tool Implementations
+    // =============================================================================
+    executeGetSessionStatus() {
+        const session = this.device.activeSession;
+        return {
+            deviceName: this.device.name,
+            isRuntimeInstalled: true,
+            sessionActive: !!session,
+            sessionOffered: this.device.sessionOffered,
+            sessionMode: session ? session.mode : null,
+            enabledFeatures: session
+                ? Array.from(session.enabledFeatures || [])
+                : [],
+            visibilityState: this.device.visibilityState,
+        };
+    }
+    executeAcceptSession() {
+        if (!this.device.sessionOffered) {
+            throw new Error('No session has been offered');
+        }
+        this.device.grantOfferedSession();
+        // Session activation is async - caller should use get_session_status to poll
+        return { success: true };
+    }
+    executeEndSession() {
+        const session = this.device.activeSession;
+        if (!session) {
+            throw new Error('No active session');
+        }
+        session.end();
+        return { success: true };
+    }
+    // =============================================================================
+    // Transform Tool Implementations
+    // =============================================================================
+    executeGetTransform(params) {
+        const { device: deviceId } = params;
+        const transform = this.getDeviceTransform(deviceId);
+        return {
+            device: deviceId,
+            position: transform.position,
+            orientation: transform.orientation,
+            euler: quatToEuler(transform.orientation),
+        };
+    }
+    executeSetTransform(params) {
+        const { device: deviceId, position, orientation } = params;
+        const targetOrientation = orientation
+            ? normalizeOrientation(orientation)
+            : undefined;
+        this.setDeviceTransform(deviceId, position, targetOrientation);
+        const newTransform = this.getDeviceTransform(deviceId);
+        return {
+            device: deviceId,
+            position: newTransform.position,
+            orientation: newTransform.orientation,
+        };
+    }
+    executeLookAt(params) {
+        const { device: deviceId, target, moveToDistance } = params;
+        const currentTransform = this.getDeviceTransform(deviceId);
+        // Transform target from XR-origin-relative to GlobalSpace
+        const targetInGlobal = this.transformXROriginToGlobal(target);
+        // Calculate direction to target
+        const direction = directionTo(currentTransform.position, targetInGlobal);
+        // Calculate look rotation
+        // Use gimbal rotation for headset (keeps it level, no roll)
+        // Use standard lookRotation for controllers/hands (can tilt freely)
+        const lookQuat = deviceId === 'headset'
+            ? lookRotationGimbal(direction)
+            : lookRotation(direction);
+        // Optionally move to a specific distance from target
+        let newPosition;
+        if (moveToDistance !== undefined) {
+            newPosition = {
+                x: targetInGlobal.x - direction.x * moveToDistance,
+                y: targetInGlobal.y - direction.y * moveToDistance,
+                z: targetInGlobal.z - direction.z * moveToDistance,
+            };
+        }
+        this.setDeviceTransform(deviceId, newPosition, lookQuat);
+        const newTransform = this.getDeviceTransform(deviceId);
+        return {
+            device: deviceId,
+            position: newTransform.position,
+            orientation: newTransform.orientation,
+        };
+    }
+    // =============================================================================
+    // Input Tool Implementations
+    // =============================================================================
+    executeSetInputMode(params) {
+        var _a, _b, _c, _d;
+        const { mode } = params;
+        this.device.primaryInputMode = mode;
+        const activeDevices = [];
+        if (mode === 'controller') {
+            if ((_a = this.device.controllers.left) === null || _a === void 0 ? void 0 : _a.connected) {
+                activeDevices.push('controller-left');
+            }
+            if ((_b = this.device.controllers.right) === null || _b === void 0 ? void 0 : _b.connected) {
+                activeDevices.push('controller-right');
+            }
+        }
+        else {
+            if ((_c = this.device.hands.left) === null || _c === void 0 ? void 0 : _c.connected) {
+                activeDevices.push('hand-left');
+            }
+            if ((_d = this.device.hands.right) === null || _d === void 0 ? void 0 : _d.connected) {
+                activeDevices.push('hand-right');
+            }
+        }
+        return { mode, activeDevices };
+    }
+    executeSetConnected(params) {
+        const { device: deviceId, connected } = params;
+        this.setDeviceConnected(deviceId, connected);
+        return { device: deviceId, connected };
+    }
+    executeGetSelectValue(params) {
+        const { device: deviceId } = params;
+        const value = this.getDeviceSelectValue(deviceId);
+        return { device: deviceId, value };
+    }
+    executeSetSelectValue(params) {
+        const { device: deviceId, value } = params;
+        this.setDeviceSelectValue(deviceId, value);
+        return { device: deviceId, value };
+    }
+    // =============================================================================
+    // Gamepad Tool Implementations
+    // =============================================================================
+    executeGetGamepadState(params) {
+        const { device: deviceId } = params;
+        const hand = deviceId === 'controller-left' ? 'left' : 'right';
+        const controller = this.device.controllers[hand];
+        if (!controller) {
+            throw new Error(`Controller ${hand} not available`);
+        }
+        // Button layout for Meta Quest Touch Plus controllers
+        // Use hand-conditional internal names for lookup
+        const buttonInternalNames = [
+            'trigger',
+            'squeeze',
+            'thumbstick',
+            hand === 'left' ? 'x-button' : 'a-button',
+            hand === 'left' ? 'y-button' : 'b-button',
+            'thumbrest',
+        ];
+        const buttons = buttonInternalNames.map((name, index) => ({
+            index,
+            name: name
+                .replace('x-button', 'x')
+                .replace('y-button', 'y')
+                .replace('a-button', 'a')
+                .replace('b-button', 'b'),
+            value: controller.getButtonValue(name),
+            touched: controller.getButtonTouched(name),
+            pressed: controller.getButtonValue(name) > 0.5,
+        }));
+        const axesData = controller.getAxes();
+        const axes = [
+            { index: 0, name: 'thumbstick-x', value: axesData.x },
+            { index: 1, name: 'thumbstick-y', value: axesData.y },
+        ];
+        return {
+            device: deviceId,
+            connected: controller.connected,
+            buttons,
+            axes,
+        };
+    }
+    executeSetGamepadState(params) {
+        const { device: deviceId, buttons, axes } = params;
+        const hand = deviceId === 'controller-left' ? 'left' : 'right';
+        const controller = this.device.controllers[hand];
+        if (!controller) {
+            throw new Error(`Controller ${hand} not available`);
+        }
+        let buttonsSet = 0;
+        let axesSet = 0;
+        // Button index to name mapping
+        const buttonIndexToName = [
+            'trigger',
+            'squeeze',
+            'thumbstick',
+            hand === 'left' ? 'x-button' : 'a-button',
+            hand === 'left' ? 'y-button' : 'b-button',
+            'thumbrest',
+        ];
+        if (buttons) {
+            for (const btn of buttons) {
+                const buttonName = buttonIndexToName[btn.index];
+                if (buttonName) {
+                    // Use updateButtonValue for proper event triggering
+                    controller.updateButtonValue(buttonName, btn.value);
+                    if (btn.touched !== undefined) {
+                        controller.updateButtonTouch(buttonName, btn.touched);
+                    }
+                    buttonsSet++;
+                }
+            }
+        }
+        if (axes) {
+            let xValue;
+            let yValue;
+            for (const axis of axes) {
+                if (axis.index === 0) {
+                    xValue = axis.value;
+                    axesSet++;
+                }
+                else if (axis.index === 1) {
+                    yValue = axis.value;
+                    axesSet++;
+                }
+            }
+            if (xValue !== undefined || yValue !== undefined) {
+                const currentAxes = controller.getAxes();
+                controller.updateAxes('thumbstick', xValue !== null && xValue !== void 0 ? xValue : currentAxes.x, yValue !== null && yValue !== void 0 ? yValue : currentAxes.y);
+            }
+        }
+        return { device: deviceId, buttonsSet, axesSet };
+    }
+    // =============================================================================
+    // State Tool Implementations
+    // =============================================================================
+    executeGetDeviceState() {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z;
+        return {
+            headset: {
+                position: vec3ToObj(this.device.position),
+                orientation: quatToObj(this.device.quaternion),
+            },
+            inputMode: this.device.primaryInputMode,
+            controllers: {
+                left: {
+                    connected: (_b = (_a = this.device.controllers.left) === null || _a === void 0 ? void 0 : _a.connected) !== null && _b !== void 0 ? _b : false,
+                    position: vec3ToObj((_d = (_c = this.device.controllers.left) === null || _c === void 0 ? void 0 : _c.position) !== null && _d !== void 0 ? _d : { x: 0, y: 0, z: 0 }),
+                    orientation: quatToObj((_f = (_e = this.device.controllers.left) === null || _e === void 0 ? void 0 : _e.quaternion) !== null && _f !== void 0 ? _f : {
+                        x: 0,
+                        y: 0,
+                        z: 0,
+                        w: 1,
+                    }),
+                },
+                right: {
+                    connected: (_h = (_g = this.device.controllers.right) === null || _g === void 0 ? void 0 : _g.connected) !== null && _h !== void 0 ? _h : false,
+                    position: vec3ToObj((_k = (_j = this.device.controllers.right) === null || _j === void 0 ? void 0 : _j.position) !== null && _k !== void 0 ? _k : { x: 0, y: 0, z: 0 }),
+                    orientation: quatToObj((_m = (_l = this.device.controllers.right) === null || _l === void 0 ? void 0 : _l.quaternion) !== null && _m !== void 0 ? _m : {
+                        x: 0,
+                        y: 0,
+                        z: 0,
+                        w: 1,
+                    }),
+                },
+            },
+            hands: {
+                left: {
+                    connected: (_p = (_o = this.device.hands.left) === null || _o === void 0 ? void 0 : _o.connected) !== null && _p !== void 0 ? _p : false,
+                    position: vec3ToObj((_r = (_q = this.device.hands.left) === null || _q === void 0 ? void 0 : _q.position) !== null && _r !== void 0 ? _r : { x: 0, y: 0, z: 0 }),
+                    orientation: quatToObj((_t = (_s = this.device.hands.left) === null || _s === void 0 ? void 0 : _s.quaternion) !== null && _t !== void 0 ? _t : { x: 0, y: 0, z: 0, w: 1 }),
+                },
+                right: {
+                    connected: (_v = (_u = this.device.hands.right) === null || _u === void 0 ? void 0 : _u.connected) !== null && _v !== void 0 ? _v : false,
+                    position: vec3ToObj((_x = (_w = this.device.hands.right) === null || _w === void 0 ? void 0 : _w.position) !== null && _x !== void 0 ? _x : { x: 0, y: 0, z: 0 }),
+                    orientation: quatToObj((_z = (_y = this.device.hands.right) === null || _y === void 0 ? void 0 : _y.quaternion) !== null && _z !== void 0 ? _z : { x: 0, y: 0, z: 0, w: 1 }),
+                },
+            },
+            stereoEnabled: this.device.stereoEnabled,
+            fov: this.device.fovy * (180 / Math.PI), // Convert to degrees
+        };
+    }
+    executeSetDeviceState(params) {
+        const { state } = params;
+        if (!state) {
+            // Reset to initial state
+            this.device.position.set(0, 1.6, 0);
+            this.device.quaternion.set(0, 0, 0, 1);
+            this.device.primaryInputMode = 'controller';
+            this.device.stereoEnabled = false;
+            // Reset controllers and hands to default positions
+            if (this.device.controllers.left) {
+                this.device.controllers.left.position.set(-0.2, 1.4, -0.3);
+                this.device.controllers.left.quaternion.set(0, 0, 0, 1);
+                this.device.controllers.left.connected = true;
+            }
+            if (this.device.controllers.right) {
+                this.device.controllers.right.position.set(0.2, 1.4, -0.3);
+                this.device.controllers.right.quaternion.set(0, 0, 0, 1);
+                this.device.controllers.right.connected = true;
+            }
+            if (this.device.hands.left) {
+                this.device.hands.left.position.set(-0.15, 1.3, -0.4);
+                this.device.hands.left.quaternion.set(0, 0, 0, 1);
+                this.device.hands.left.connected = true;
+            }
+            if (this.device.hands.right) {
+                this.device.hands.right.position.set(0.15, 1.3, -0.4);
+                this.device.hands.right.quaternion.set(0, 0, 0, 1);
+                this.device.hands.right.connected = true;
+            }
+        }
+        else {
+            // Apply partial state
+            if (state.headset) {
+                if (state.headset.position) {
+                    this.device.position.set(state.headset.position.x, state.headset.position.y, state.headset.position.z);
+                }
+                if (state.headset.orientation) {
+                    this.device.quaternion.set(state.headset.orientation.x, state.headset.orientation.y, state.headset.orientation.z, state.headset.orientation.w);
+                }
+            }
+            if (state.inputMode !== undefined) {
+                this.device.primaryInputMode = state.inputMode;
+            }
+            if (state.stereoEnabled !== undefined) {
+                this.device.stereoEnabled = state.stereoEnabled;
+            }
+            if (state.fov !== undefined) {
+                this.device.fovy = state.fov * (Math.PI / 180); // Convert to radians
+            }
+            if (state.controllers) {
+                this.applyInputState('controller-left', state.controllers.left);
+                this.applyInputState('controller-right', state.controllers.right);
+            }
+            if (state.hands) {
+                this.applyInputState('hand-left', state.hands.left);
+                this.applyInputState('hand-right', state.hands.right);
+            }
+        }
+        return { state: this.executeGetDeviceState() };
+    }
+    applyInputState(deviceId, state) {
+        if (!state)
+            return;
+        if (state.connected !== undefined) {
+            this.setDeviceConnected(deviceId, state.connected);
+        }
+        if (state.position || state.orientation) {
+            this.setDeviceTransform(deviceId, state.position, state.orientation);
+        }
+    }
+    executeCaptureCanvas(params) {
+        const { maxWidth = 800, format = 'png', quality = 0.92 } = params;
+        // Get the app canvas - try device first, then fallback to DOM query
+        let canvas = this.device.appCanvas;
+        if (!canvas) {
+            // No active session - try to find the canvas in the DOM
+            // Before XR session, only the app's canvas is in the DOM
+            // (IWER's canvases are not added until session starts)
+            const canvases = document.querySelectorAll('canvas');
+            if (canvases.length === 1) {
+                canvas = canvases[0];
+            }
+            else if (canvases.length > 1) {
+                // Multiple canvases - try to find the most likely app canvas
+                // Prefer the largest visible canvas
+                let bestCanvas = null;
+                let bestArea = 0;
+                canvases.forEach((c) => {
+                    const rect = c.getBoundingClientRect();
+                    const area = rect.width * rect.height;
+                    if (area > bestArea && rect.width > 0 && rect.height > 0) {
+                        bestArea = area;
+                        bestCanvas = c;
+                    }
+                });
+                canvas = bestCanvas;
+            }
+        }
+        if (!canvas) {
+            throw new Error('No canvas available. Either start an XR session or ensure an app canvas is in the DOM.');
+        }
+        // Create a temporary canvas for scaling
+        const tempCanvas = document.createElement('canvas');
+        const ctx = tempCanvas.getContext('2d');
+        if (!ctx) {
+            throw new Error('Failed to create canvas context');
+        }
+        // Calculate scaled dimensions
+        const aspectRatio = canvas.height / canvas.width;
+        const targetWidth = Math.min(canvas.width, maxWidth);
+        const targetHeight = Math.round(targetWidth * aspectRatio);
+        tempCanvas.width = targetWidth;
+        tempCanvas.height = targetHeight;
+        // Draw scaled image
+        ctx.drawImage(canvas, 0, 0, targetWidth, targetHeight);
+        // Convert to base64
+        const mimeType = `image/${format}`;
+        const dataUrl = tempCanvas.toDataURL(mimeType, quality);
+        const imageData = dataUrl.split(',')[1]; // Remove data URL prefix
+        return {
+            imageData,
+            width: targetWidth,
+            height: targetHeight,
+            format,
+            timestamp: Date.now(),
+        };
+    }
+    // =============================================================================
+    // Duration Action Handling
+    // =============================================================================
+    applyDurationLerpState(action, t) {
+        const { startState, targetState, params } = action;
+        const deviceId = params.device;
+        let newPosition;
+        let newOrientation;
+        if (startState.position && targetState.position) {
+            newPosition = lerpVec3(startState.position, targetState.position, t);
+        }
+        if (startState.orientation && targetState.orientation) {
+            newOrientation = slerpQuat(startState.orientation, targetState.orientation, t);
+        }
+        this.setDeviceTransform(deviceId, newPosition, newOrientation);
+    }
+    applyDurationFinalState(action) {
+        const { targetState, params } = action;
+        const deviceId = params.device;
+        this.setDeviceTransform(deviceId, targetState.position, targetState.orientation);
+    }
+    getDurationResult(action) {
+        const { params, elapsedMs } = action;
+        const deviceId = params.device;
+        const transform = this.getDeviceTransform(deviceId);
+        return {
+            device: deviceId,
+            position: transform.position,
+            orientation: transform.orientation,
+            actualDuration: elapsedMs / 1000,
+        };
+    }
+    /**
+     * Activate capture mode for programmatic control.
+     * Called when active methods are executed.
+     */
+    activateCaptureMode() {
+        if (!this._isCaptured) {
+            this._isCaptured = true;
+            this.cancelReleaseTimer();
+            this.device.controlMode = 'programmatic';
+        }
+        // Reset the release timer
+        this.startReleaseTimer();
+    }
+    /**
+     * Dispatch a method call.
+     *
+     * Immediate methods (queries, session management) execute synchronously.
+     * State-modifying methods require an active session and are queued for frame-synchronized execution.
+     *
+     * @param method - The method name (e.g., 'get_transform', 'animate_to')
+     * @param params - The method parameters
+     * @returns Promise that resolves with the method result
+     */
+    async dispatch(method, params = {}) {
+        var _a;
+        // Immediate methods execute synchronously without queue
+        if (RemoteControlInterface.IMMEDIATE_METHODS.has(method)) {
+            // Active immediate methods trigger capture mode
+            if (RemoteControlInterface.ACTIVE_IMMEDIATE_METHODS.has(method)) {
+                this.activateCaptureMode();
+            }
+            return this.executeImmediateMethod(method, params);
+        }
+        // Methods that modify state require an active session
+        if (RemoteControlInterface.SESSION_REQUIRED_METHODS.has(method)) {
+            if (!this.device.activeSession) {
+                throw new Error(`Cannot execute '${method}': No active XR session. ` +
+                    `Use 'get_session_status' to check session state, and 'accept_session' to start a session.`);
+            }
+        }
+        // Handle animate_to specially - it's a duration action
+        if (method === 'animate_to') {
+            const animateParams = params;
+            const currentTransform = this.getDeviceTransform(animateParams.device);
+            const durationMs = ((_a = animateParams.duration) !== null && _a !== void 0 ? _a : 0.5) * 1000;
+            const targetOrientation = animateParams.orientation
+                ? normalizeOrientation(animateParams.orientation)
+                : undefined;
+            // Transform target position from XR-origin-relative to GlobalSpace
+            const targetPosition = animateParams.position
+                ? this.transformXROriginToGlobal(animateParams.position)
+                : undefined;
+            return this.enqueueDuration(method, params, durationMs, {
+                position: animateParams.position
+                    ? currentTransform.position
+                    : undefined,
+                orientation: targetOrientation
+                    ? currentTransform.orientation
+                    : undefined,
+            }, {
+                position: targetPosition,
+                orientation: targetOrientation,
+            });
+        }
+        // Handle select specially - it's a discrete action that enqueues multiple sub-actions
+        if (method === 'select') {
+            const selectParams = params;
+            return this.executeSelectSequence(selectParams);
+        }
+        // All other methods are discrete actions that go through the queue
+        return this.enqueueDiscrete(method, params);
+    }
+    /**
+     * Execute an immediate method synchronously (not queued).
+     * Used for queries and session management that must work outside XR frames.
+     */
+    executeImmediateMethod(method, params) {
+        switch (method) {
+            case 'get_session_status':
+                return this.executeGetSessionStatus();
+            case 'accept_session':
+                return this.executeAcceptSession();
+            case 'end_session':
+                return this.executeEndSession();
+            case 'get_transform':
+                return this.executeGetTransform(params);
+            case 'get_select_value':
+                return this.executeGetSelectValue(params);
+            case 'get_gamepad_state':
+                return this.executeGetGamepadState(params);
+            case 'get_device_state':
+                return this.executeGetDeviceState();
+            case 'capture_canvas':
+                return this.executeCaptureCanvas(params);
+            default:
+                throw new Error(`Unknown immediate method: ${method}`);
+        }
+    }
+    /**
+     * Execute select action - this directly enqueues the three sub-actions without awaiting
+     * The caller's promise resolves when all sub-actions complete
+     */
+    executeSelectSequence(params) {
+        const { device: deviceId, duration = 0.15 } = params;
+        return new Promise((resolve, reject) => {
+            // Track completion of all three actions
+            let actionsCompleted = 0;
+            const totalActions = 3;
+            const checkComplete = () => {
+                actionsCompleted++;
+                if (actionsCompleted === totalActions) {
+                    resolve({
+                        device: deviceId,
+                        duration,
+                    });
+                }
+            };
+            // Enqueue: set value to 1
+            const action1 = {
+                type: 'discrete',
+                id: this.generateActionId(),
+                method: '_select_press',
+                params: { device: deviceId },
+                resolve: checkComplete,
+                reject,
+            };
+            // Enqueue: wait for duration
+            const action2 = {
+                type: 'duration',
+                id: this.generateActionId(),
+                method: '_select_wait',
+                params: { device: deviceId },
+                durationMs: duration * 1000,
+                elapsedMs: 0,
+                startState: {},
+                targetState: {},
+                resolve: checkComplete,
+                reject,
+            };
+            // Enqueue: set value to 0
+            const action3 = {
+                type: 'discrete',
+                id: this.generateActionId(),
+                method: '_select_release',
+                params: { device: deviceId },
+                resolve: checkComplete,
+                reject,
+            };
+            this.commandQueue.push(action1, action2, action3);
+        });
+    }
+    /**
+     * Accept an offered XR session (async wrapper for proper session activation)
+     */
+    async acceptSession() {
+        if (!this.device.sessionOffered) {
+            throw new Error('No session has been offered');
+        }
+        this.device.grantOfferedSession();
+        // Wait for session to become active
+        await waitForCondition(() => !!this.device.activeSession, 5000);
+        // Just return success - caller can use get_session_status for details
+        return { success: true };
+    }
+    /**
+     * Force release capture mode (for testing/cleanup)
+     */
+    forceRelease() {
+        this.cancelReleaseTimer();
+        this._isCaptured = false;
+        this.device.controlMode = 'manual';
+        // Clear pending actions
+        for (const action of this.commandQueue) {
+            action.reject(new Error('Capture released'));
+        }
+        this.commandQueue = [];
+        // Reset any stuck select/trigger values
+        for (const hand of ['left', 'right']) {
+            const controller = this.device.controllers[hand];
+            if (controller) {
+                controller.updateButtonValue('trigger', 0);
+                controller.updateButtonValue('squeeze', 0);
+            }
+        }
+    }
+}
+// =============================================================================
+// Public API - Dispatch
+// =============================================================================
+/**
+ * Set of methods that execute immediately (synchronously) without going through the queue.
+ * These are queries and session management commands that need to work outside of XR frames.
+ */
+RemoteControlInterface.IMMEDIATE_METHODS = new Set([
+    // Session management - must work before/after XR session
+    'get_session_status',
+    'accept_session',
+    'end_session',
+    // Pure queries - just read current state
+    'get_transform',
+    'get_select_value',
+    'get_gamepad_state',
+    'get_device_state',
+    // Canvas capture - reads current canvas state
+    'capture_canvas',
+]);
+/**
+ * Set of immediate methods that are "active" - they modify state and should trigger capture mode.
+ * Passive methods (queries) should NOT trigger capture mode.
+ */
+RemoteControlInterface.ACTIVE_IMMEDIATE_METHODS = new Set([
+    'accept_session',
+    'end_session',
+]);
+/**
+ * Set of methods that require an active XR session.
+ * These are state-modifying methods that are processed during frame updates.
+ */
+RemoteControlInterface.SESSION_REQUIRED_METHODS = new Set([
+    'set_transform',
+    'look_at',
+    'animate_to',
+    'set_input_mode',
+    'set_connected',
+    'set_select_value',
+    'select',
+    'set_gamepad_state',
+    'set_device_state',
+]);
+
 /**
  * Copyright (c) Meta Platforms, Inc. and affiliates.
  *
@@ -1878,6 +3328,31 @@ class XRController extends XRTrackedInput {
             console.warn(`Current controller does not have button ${id}.`);
         }
     }
+    /**
+     * Set button value immediately (bypasses pending mechanism).
+     * Use this for programmatic control where value should be readable immediately.
+     */
+    setButtonValueImmediate(id, value) {
+        if (value > 1 || value < 0) {
+            console.warn(`Out-of-range value ${value} provided for button ${id}.`);
+            return;
+        }
+        const gamepadButton = this[P_TRACKED_INPUT].inputSource.gamepad[P_GAMEPAD].buttonsMap[id];
+        if (gamepadButton) {
+            if (gamepadButton[P_GAMEPAD].type === 'binary' &&
+                value != 1 &&
+                value != 0) {
+                console.warn(`Non-binary value ${value} provided for binary button ${id}.`);
+                return;
+            }
+            // Set both value and pendingValue for immediate effect
+            gamepadButton[P_GAMEPAD].value = value;
+            gamepadButton[P_GAMEPAD].pendingValue = value;
+        }
+        else {
+            console.warn(`Current controller does not have button ${id}.`);
+        }
+    }
     updateButtonTouch(id, touched) {
         const gamepadButton = this[P_TRACKED_INPUT].inputSource.gamepad[P_GAMEPAD].buttonsMap[id];
         if (gamepadButton) {
@@ -1919,6 +3394,37 @@ class XRController extends XRTrackedInput {
             console.warn(`Current controller does not have ${id} axes.`);
         }
     }
+    /**
+     * Get the current value of a button by id
+     */
+    getButtonValue(id) {
+        var _a;
+        const gamepadButton = this[P_TRACKED_INPUT].inputSource.gamepad[P_GAMEPAD].buttonsMap[id];
+        if (gamepadButton) {
+            return (_a = gamepadButton[P_GAMEPAD].pendingValue) !== null && _a !== void 0 ? _a : gamepadButton.value;
+        }
+        return 0;
+    }
+    /**
+     * Get the touched state of a button by id
+     */
+    getButtonTouched(id) {
+        const gamepadButton = this[P_TRACKED_INPUT].inputSource.gamepad[P_GAMEPAD].buttonsMap[id];
+        if (gamepadButton) {
+            return gamepadButton.touched;
+        }
+        return false;
+    }
+    /**
+     * Get the current axes values for a given id (e.g., 'thumbstick')
+     */
+    getAxes(id = 'thumbstick') {
+        const axesById = this[P_TRACKED_INPUT].inputSource.gamepad[P_GAMEPAD].axesMap[id];
+        if (axesById) {
+            return { x: axesById.x, y: axesById.y };
+        }
+        return { x: 0, y: 0 };
+    }
 }
 
 /**
@@ -4175,9 +5681,9 @@ const interpolateMatrix = (out, fromMatrix, toMatrix, alpha) => {
     getTranslation(toPosition, toMatrix);
     getRotation(toQuaternion, toMatrix);
     getScaling(toScale, toMatrix);
-    lerp(interpolatedPosition, fromPosition, toPosition, alpha);
+    lerp$1(interpolatedPosition, fromPosition, toPosition, alpha);
     slerp(interpolatedQuaternion, fromQuaternion, toQuaternion, alpha);
-    lerp(interpolatedScale, fromScale, toScale, alpha);
+    lerp$1(interpolatedScale, fromScale, toScale, alpha);
     fromRotationTranslationScale(out, interpolatedQuaternion, interpolatedPosition, interpolatedScale);
     return out;
 };
@@ -4502,7 +6008,7 @@ class ActionPlayer {
         const f1q = fromValues(lastTransform[3], lastTransform[4], lastTransform[5], lastTransform[6]);
         const f2p = fromValues$2(nextTransform[0], nextTransform[1], nextTransform[2]);
         const f2q = fromValues(nextTransform[3], nextTransform[4], nextTransform[5], nextTransform[6]);
-        lerp(this[P_ACTION_PLAYER].vec3, f1p, f2p, alpha);
+        lerp$1(this[P_ACTION_PLAYER].vec3, f1p, f2p, alpha);
         slerp(this[P_ACTION_PLAYER].quat, f1q, f2q, alpha);
         fromRotationTranslation(space[P_SPACE].offsetMatrix, this[P_ACTION_PLAYER].quat, this[P_ACTION_PLAYER].vec3);
     }
@@ -4527,7 +6033,7 @@ class ActionPlayer {
     }
 }
 
-const VERSION = "2.1.1";
+const VERSION = "2.2.0";
 
 /**
  * Copyright (c) Meta Platforms, Inc. and affiliates.
@@ -7834,6 +9340,16 @@ class XRDevice {
             },
             onFrameStart: (frame) => {
                 var _a;
+                // Calculate delta time for remote control
+                const now = performance.now();
+                const deltaTimeMs = this[P_DEVICE].lastFrameTime > 0
+                    ? now - this[P_DEVICE].lastFrameTime
+                    : 16.67; // Default to ~60fps
+                this[P_DEVICE].lastFrameTime = now;
+                // Update remote control interface
+                if (this[P_DEVICE].remote) {
+                    this[P_DEVICE].remote.update(deltaTimeMs);
+                }
                 if ((_a = this[P_DEVICE].actionPlayer) === null || _a === void 0 ? void 0 : _a.playing) {
                     this[P_DEVICE].actionPlayer.playFrame();
                 }
@@ -7867,7 +9383,17 @@ class XRDevice {
                 }
                 this[P_DEVICE].updateViews();
             },
+            // control mode for programmatic access
+            controlMode: 'manual',
+            controlModeListeners: new Set(),
+            stateChangeListeners: new Set(),
+            // remote control interface - initialized after this object
+            remote: null,
+            // frame timing for remote update
+            lastFrameTime: 0,
         };
+        // Initialize remote control interface
+        this[P_DEVICE].remote = new RemoteControlInterface(this);
         this[P_DEVICE].updateViews();
     }
     installRuntime(options) {
@@ -8030,6 +9556,14 @@ class XRDevice {
         }
         return;
     }
+    /**
+     * Get the app canvas when an XR session is active.
+     * Returns undefined if no session is active or no canvas is available.
+     */
+    get appCanvas() {
+        var _a;
+        return (_a = this[P_DEVICE].canvasData) === null || _a === void 0 ? void 0 : _a.canvas;
+    }
     get activeSession() {
         var _a;
         return (_a = this[P_DEVICE].xrSystem) === null || _a === void 0 ? void 0 : _a[P_SYSTEM].activeSession;
@@ -8095,6 +9629,65 @@ class XRDevice {
     get sem() {
         return this[P_DEVICE].sem;
     }
+    get remote() {
+        return this[P_DEVICE].remote;
+    }
+    // =============================================================================
+    // Control Mode API
+    // =============================================================================
+    /**
+     * Get the current control mode
+     * - 'manual': User controls device via DevUI (default)
+     * - 'programmatic': External API controls device
+     */
+    get controlMode() {
+        return this[P_DEVICE].controlMode;
+    }
+    /**
+     * Set the control mode
+     * Notifies all registered listeners of the change
+     */
+    set controlMode(mode) {
+        if (mode !== 'manual' && mode !== 'programmatic') {
+            console.warn('control mode can only be "manual" or "programmatic"');
+            return;
+        }
+        const prevMode = this[P_DEVICE].controlMode;
+        if (prevMode !== mode) {
+            this[P_DEVICE].controlMode = mode;
+            this[P_DEVICE].controlModeListeners.forEach((listener) => listener(mode));
+        }
+    }
+    /**
+     * Register a listener to be notified when control mode changes
+     * @param listener - Callback function that receives the new mode
+     * @returns Unsubscribe function to remove the listener
+     */
+    onControlModeChange(listener) {
+        this[P_DEVICE].controlModeListeners.add(listener);
+        return () => {
+            this[P_DEVICE].controlModeListeners.delete(listener);
+        };
+    }
+    /**
+     * Register a listener to be notified when device state changes
+     * Called after programmatic state modifications
+     * @param listener - Callback function
+     * @returns Unsubscribe function to remove the listener
+     */
+    onStateChange(listener) {
+        this[P_DEVICE].stateChangeListeners.add(listener);
+        return () => {
+            this[P_DEVICE].stateChangeListeners.delete(listener);
+        };
+    }
+    /**
+     * Notify all state change listeners that device state has been modified
+     * Should be called after programmatic state modifications
+     */
+    notifyStateChange() {
+        this[P_DEVICE].stateChangeListeners.forEach((listener) => listener());
+    }
 }
 
 /**
@@ -8528,4 +10121,4 @@ class ActionRecorder {
     }
 }
 
-export { ActionRecorder, NativeMesh, NativePlane, P_ACTION_PLAYER, P_ACTION_RECORDER, P_ANCHOR, P_CONTROLLER, P_DEVICE, P_FRAME, P_GAMEPAD, P_HAND_INPUT, P_HIT_TEST, P_INPUT_SOURCE, P_JOINT_POSE, P_JOINT_SPACE, P_MESH, P_PLANE, P_POSE, P_RAY, P_REF_SPACE, P_RENDER_STATE, P_RIGID_TRANSFORM, P_SESSION, P_SPACE, P_SYSTEM, P_TRACKED_INPUT, P_VIEW, P_VIEWER_POSE, P_VIEWPORT, P_WEBGL_LAYER, XRAnchor, XRAnchorSet, XRDevice, XRFrame, XRHand, XRInputSource, XRInputSourceArray, XRInputSourceEvent, XRInputSourcesChangeEvent, XRJointPose, XRJointSpace, XRLayer, XRMesh, XRMeshSet, XRPlane, XRPlaneSet, XRPose, XRRay, XRReferenceSpace, XRReferenceSpaceEvent, XRRenderState, XRRigidTransform, XRSemanticLabels, XRSession, XRSessionEvent, XRSpace, XRSystem, XRView, XRViewerPose, XRViewport, XRWebGLLayer, metaQuest2, metaQuest3, metaQuestPro, oculusQuest1 };
+export { ActionRecorder, NativeMesh, NativePlane, P_ACTION_PLAYER, P_ACTION_RECORDER, P_ANCHOR, P_CONTROLLER, P_DEVICE, P_FRAME, P_GAMEPAD, P_HAND_INPUT, P_HIT_TEST, P_INPUT_SOURCE, P_JOINT_POSE, P_JOINT_SPACE, P_MESH, P_PLANE, P_POSE, P_RAY, P_REF_SPACE, P_RENDER_STATE, P_RIGID_TRANSFORM, P_SESSION, P_SPACE, P_SYSTEM, P_TRACKED_INPUT, P_VIEW, P_VIEWER_POSE, P_VIEWPORT, P_WEBGL_LAYER, RemoteControlInterface, XRAnchor, XRAnchorSet, XRDevice, XRFrame, XRHand, XRInputSource, XRInputSourceArray, XRInputSourceEvent, XRInputSourcesChangeEvent, XRJointPose, XRJointSpace, XRLayer, XRMesh, XRMeshSet, XRPlane, XRPlaneSet, XRPose, XRRay, XRReferenceSpace, XRReferenceSpaceEvent, XRRenderState, XRRigidTransform, XRSemanticLabels, XRSession, XRSessionEvent, XRSpace, XRSystem, XRView, XRViewerPose, XRViewport, XRWebGLLayer, directionTo, eulerToQuat, lookRotation, metaQuest2, metaQuest3, metaQuestPro, oculusQuest1, quatToEuler, quatToObj, vec3ToObj, waitForCondition };