@driftengine/xr 3.61.0

package/dist/testing/synthetic.js

@@ -0,0 +1,238 @@
+/**
+ * A WebXR runtime that answers, so everything past the first frame can be exercised.
+ *
+ * **This stands in for a browser API and not for an engine capability**, which is the distinction
+ * R1 drew when it withdrew the mock capability providers: a mock with no first implementation to
+ * check it against is only ever agreeing with itself. The first implementation of WebXR is a
+ * browser's, and `DeterministicProvider` already lives on the same footing, standing in for a thing
+ * that is genuinely elsewhere.
+ *
+ * **It exists because no frame can be produced on the machine this was written on.** Measured
+ * 2026-09-05, Chrome 151, no headset: an inline session starts and `makeXRCompatible` throws, so
+ * there is no base layer and therefore no `XRFrame` at all. Every path from the first frame onward
+ * would otherwise be code nobody had run.
+ *
+ * **What it cannot do is prove a real runtime accepts what the engine hands back.** It produces the
+ * shapes the specification describes; whether a compositor is happy with them is a question only
+ * hardware answers, and that is tracked as unmeasured rather than this file
+ * pretending otherwise.
+ *
+ * The numbers are deliberately asymmetric and deliberately not round. An eye projection is off-axis
+ * and the two eyes differ; a synthetic runtime handing back two identical symmetric matrices would
+ * let a stereo path that drew the same picture twice pass as correct.
+ */
+import { mat4 } from 'gl-matrix';
+import { HAND_JOINTS } from '../hands.js';
+function transform(matrix) {
+    return {
+        matrix: matrix,
+        inverse: { matrix: mat4.invert(mat4.create(), matrix) },
+    };
+}
+/** Two eyes, 64 mm apart, with off-axis frusta that differ from each other. */
+function stereoViews(headHeight) {
+    const half = 0.032;
+    const make = (eye, offset, left, right) => {
+        const world = mat4.create();
+        mat4.translate(world, world, [offset, headHeight, 0]);
+        return {
+            eye,
+            projectionMatrix: mat4.frustum(mat4.create(), left, right, -0.08, 0.08, 0.1, 1000),
+            /* The eye's pose in the reference space, which is what `XRView.transform` is. An earlier
+               draft inverted this twice by accident, which typechecked as `mat4 | null` and said so. */
+            transform: transform(world),
+        };
+    };
+    /* Each eye's frustum is off-centre towards its own side, which is what a headset's optics do. */
+    return [make('left', -half, -0.11, 0.09), make('right', half, -0.09, 0.11)];
+}
+/**
+ * Build a runtime.
+ *
+ * Nothing is on a timer: `advance` is the only thing that produces a frame, so a test asserting
+ * about frame N is asserting about a frame it caused rather than one it waited for.
+ */
+export function syntheticXr(options = {}) {
+    const modes = options.modes ?? ['immersive-vr', 'inline'];
+    const spaces = options.spaces ?? ['local-floor', 'local', 'viewer'];
+    const headHeight = options.headHeight ?? 1.6;
+    const wanted = options.controllers ?? [
+        { handedness: 'left', hand: true },
+        { handedness: 'right' },
+    ];
+    const sessions = [];
+    const system = {
+        sessions,
+        async isSessionSupported(mode) {
+            return modes.includes(mode);
+        },
+        async requestSession(mode) {
+            if (!modes.includes(mode)) {
+                const error = new Error(`no ${mode} device`);
+                error.name = 'NotSupportedError';
+                throw error;
+            }
+            const session = buildSession(mode);
+            sessions.push(session);
+            return session;
+        },
+        advance(timeMs = 16) {
+            for (const session of sessions)
+                session.fire(timeMs);
+        },
+        endLatest() {
+            const session = sessions.at(-1);
+            void session?.end();
+        },
+    };
+    function buildSession(mode) {
+        let pending = null;
+        let handle = 0;
+        let ended = 0;
+        let clock = 0;
+        const listeners = new Map();
+        const renderState = {};
+        const buttons = new Map();
+        const untracked = new Set();
+        for (const controller of wanted)
+            buttons.set(controller.handedness, [0, 0, 0, 0]);
+        const inputSources = wanted.map((controller) => {
+            const gripSpace = { kind: 'grip', handedness: controller.handedness };
+            const targetRaySpace = { kind: 'ray', handedness: controller.handedness };
+            const gamepad = {
+                get buttons() {
+                    const values = buttons.get(controller.handedness) ?? [];
+                    return values.map((value) => ({ pressed: value > 0.5, touched: value > 0, value }));
+                },
+                axes: [0, 0, 0.25, -0.5],
+            };
+            const hand = controller.hand
+                ? {
+                    size: HAND_JOINTS.length,
+                    get: (joint) => ({ kind: 'joint', joint, handedness: controller.handedness }),
+                    keys: () => HAND_JOINTS[Symbol.iterator](),
+                }
+                : undefined;
+            return {
+                handedness: controller.handedness,
+                targetRayMode: 'tracked-pointer',
+                targetRaySpace,
+                gripSpace,
+                gamepad,
+                hand,
+            };
+        });
+        const viewport = (index) => ({
+            x: index * 512,
+            y: 0,
+            width: 512,
+            height: 512,
+        });
+        const frameFor = (session) => ({
+            session,
+            getViewerPose() {
+                const views = options.views === 'mono'
+                    ? [stereoViews(headHeight)[0]]
+                    : stereoViews(headHeight);
+                const head = mat4.create();
+                mat4.translate(head, head, [0, headHeight, 0]);
+                return { views, transform: transform(head) };
+            },
+            getPose(space) {
+                const described = space;
+                if (described?.handedness === undefined)
+                    return null;
+                const world = mat4.create();
+                mat4.translate(world, world, [described.handedness === 'left' ? -0.25 : 0.25, 1.1, -0.35]);
+                return { transform: transform(world) };
+            },
+            getJointPose(joint) {
+                const described = joint;
+                if (described?.joint === undefined)
+                    return null;
+                if (untracked.has(`${described.handedness}:${described.joint}`))
+                    return null;
+                const index = HAND_JOINTS.indexOf(described.joint);
+                const world = mat4.create();
+                mat4.translate(world, world, [
+                    described.handedness === 'left' ? -0.25 : 0.25,
+                    1.1 + index * 0.005,
+                    -0.35,
+                ]);
+                return { transform: transform(world), radius: 0.008 };
+            },
+        });
+        const session = {
+            renderState,
+            get endedCount() {
+                return ended;
+            },
+            get inputSources() {
+                return inputSources;
+            },
+            async requestReferenceSpace(type) {
+                if (!spaces.includes(type)) {
+                    const error = new Error(`no ${type}`);
+                    error.name = 'NotSupportedError';
+                    throw error;
+                }
+                return { kind: 'space', type };
+            },
+            updateRenderState(state) {
+                if (state.baseLayer !== undefined)
+                    renderState.baseLayer = state.baseLayer;
+                if (state.layers !== undefined)
+                    renderState.layers = state.layers;
+            },
+            requestAnimationFrame(callback) {
+                pending = callback;
+                return ++handle;
+            },
+            cancelAnimationFrame() {
+                pending = null;
+            },
+            async end() {
+                ended++;
+                for (const listener of listeners.get('end') ?? [])
+                    listener();
+            },
+            addEventListener(type, listener) {
+                const list = listeners.get(type) ?? [];
+                list.push(listener);
+                listeners.set(type, list);
+            },
+            setButton(handedness, index, value) {
+                const values = buttons.get(handedness);
+                if (values !== undefined)
+                    values[index] = value;
+            },
+            setJointTracked(handedness, joint, tracked) {
+                const key = `${handedness}:${joint}`;
+                if (tracked)
+                    untracked.delete(key);
+                else
+                    untracked.add(key);
+            },
+        };
+        session.fire = (timeMs) => {
+            const callback = pending;
+            pending = null;
+            clock += timeMs;
+            callback?.(clock, frameFor(session));
+        };
+        void mode;
+        return session;
+    }
+    return system;
+}
+/** A layer a synthetic session accepts, so the render-state path can be exercised too. */
+export function syntheticGlLayer() {
+    return {
+        framebuffer: { kind: 'framebuffer' },
+        framebufferWidth: 1024,
+        framebufferHeight: 512,
+        getViewport(view) {
+            return { x: view.eye === 'right' ? 512 : 0, y: 0, width: 512, height: 512 };
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The parts of WebXR this package touches, declared here.
+ *
+ * **Declared and not imported, because `tsconfig.json` sets `"types": []`.** The engine's config
+ * says why: `@types/node` is installed for the tools, and TypeScript pulls in every `@types`
+ * package it can find unless a config says otherwise, so a stray `Buffer` would compile here and
+ * fail in somebody's game. `@types/webxr` would be the same trade in the other direction, and its
+ * own note already sanctions the alternative: *`src/` and `demo/` reach the DOM through the `lib`
+ * above and declare anything else they need themselves.*
+ *
+ * So these are the shapes this package reads, written out. They are deliberately **narrower than
+ * the specification**: what is here is what the code below touches, and a field nobody reads is a
+ * field nobody has to keep in step with a moving standard.
+ */
+/** A pose's transform. Only the matrix is read; the decomposed parts are the runtime's convenience. */
+export interface XrRigidTransform {
+    readonly matrix: Float32Array;
+    readonly inverse?: {
+        readonly matrix: Float32Array;
+    };
+}
+/** One eye, or the single view an inline session offers. */
+export interface XrView {
+    readonly eye: 'left' | 'right' | 'none';
+    readonly projectionMatrix: Float32Array;
+    readonly transform: XrRigidTransform;
+}
+export interface XrViewerPose {
+    readonly views: readonly XrView[];
+    readonly transform: XrRigidTransform;
+}
+/** Where in the layer's texture one eye draws. */
+export interface XrViewport {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface XrWebGlLayer {
+    readonly framebuffer: unknown;
+    readonly framebufferWidth: number;
+    readonly framebufferHeight: number;
+    getViewport(view: XrView): XrViewport | undefined;
+}
+/** A joint of a hand, keyed by the twenty-five names the specification fixes. */
+export interface XrJointPose {
+    readonly transform: XrRigidTransform;
+    readonly radius: number | null;
+}
+export interface XrHand {
+    readonly size: number;
+    get(joint: string): unknown;
+    keys(): IterableIterator<string>;
+}
+export interface XrGamepadButton {
+    readonly pressed: boolean;
+    readonly touched: boolean;
+    readonly value: number;
+}
+export interface XrGamepad {
+    readonly buttons: readonly XrGamepadButton[];
+    readonly axes: readonly number[];
+}
+export interface XrInputSource {
+    readonly handedness: 'left' | 'right' | 'none';
+    readonly targetRayMode: string;
+    readonly targetRaySpace: unknown;
+    readonly gripSpace?: unknown;
+    readonly gamepad?: XrGamepad;
+    readonly hand?: XrHand;
+}
+export interface XrFrame {
+    readonly session: XrSession;
+    getViewerPose(space: unknown): XrViewerPose | null | undefined;
+    getPose?(space: unknown, base: unknown): {
+        readonly transform: XrRigidTransform;
+    } | null | undefined;
+    getJointPose?(joint: unknown, base: unknown): XrJointPose | null | undefined;
+}
+export interface XrRenderState {
+    baseLayer?: XrWebGlLayer;
+    layers?: readonly unknown[];
+    depthNear?: number;
+    depthFar?: number;
+}
+export interface XrSession {
+    readonly inputSources: Iterable<XrInputSource>;
+    requestReferenceSpace(type: string): Promise<unknown>;
+    updateRenderState(state: XrRenderState): void;
+    requestAnimationFrame(callback: (timeMs: number, frame: XrFrame) => void): number;
+    cancelAnimationFrame(handle: number): void;
+    end(): Promise<void>;
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener?(type: string, listener: () => void): void;
+}
+export interface XrSystem {
+    isSessionSupported(mode: string): Promise<boolean>;
+    requestSession(mode: string, options?: {
+        optionalFeatures?: readonly string[];
+    }): Promise<XrSession>;
+}
+/** The session modes this package will ask for. */
+export type XrMode = 'immersive-vr' | 'immersive-ar' | 'inline';

package/dist/types.js

@@ -0,0 +1,15 @@
+/**
+ * The parts of WebXR this package touches, declared here.
+ *
+ * **Declared and not imported, because `tsconfig.json` sets `"types": []`.** The engine's config
+ * says why: `@types/node` is installed for the tools, and TypeScript pulls in every `@types`
+ * package it can find unless a config says otherwise, so a stray `Buffer` would compile here and
+ * fail in somebody's game. `@types/webxr` would be the same trade in the other direction, and its
+ * own note already sanctions the alternative: *`src/` and `demo/` reach the DOM through the `lib`
+ * above and declare anything else they need themselves.*
+ *
+ * So these are the shapes this package reads, written out. They are deliberately **narrower than
+ * the specification**: what is here is what the code below touches, and a field nobody reads is a
+ * field nobody has to keep in step with a moving standard.
+ */
+export {};

package/dist/views.d.ts

@@ -0,0 +1,43 @@
+/**
+ * An `XRView` turned into something the engine's camera can adopt.
+ *
+ * **The whole of the stereo path is here, and it is smaller than it sounds.** A frame carries one
+ * view per eye; each has a projection the runtime computed for that eye's optics and a transform
+ * giving where that eye is in the reference space. The engine draws the scene once per view, into
+ * that view's slice of one layer texture.
+ *
+ * **A view matrix is the inverse of the eye's transform**, and that is the only arithmetic in this
+ * file. WebXR hands over the transform's own `inverse` when it has one, because it usually does and
+ * inverting a matrix per eye per frame to recompute a number already sitting there would be work
+ * for nothing. When it does not, this inverts. Both paths are exercised, because a runtime is free
+ * to omit it and a path taken only on somebody else's hardware is a path nobody has run.
+ */
+import { mat4 } from 'gl-matrix';
+import type { Camera } from '@driftengine/core';
+import type { XrViewerPose, XrViewport, XrWebGlLayer } from './types.ts';
+/** One eye's matrices and where it draws. */
+export interface EyeView {
+    readonly eye: 'left' | 'right' | 'none';
+    /** The inverse of the eye's transform, which is what a camera calls its view. */
+    readonly view: mat4;
+    readonly projection: mat4;
+    /** Where in the layer's texture this eye belongs, or null when the layer offered none. */
+    readonly viewport: XrViewport | null;
+}
+/**
+ * Turn a pose's views into eye views, into reused storage.
+ *
+ * `out` is filled and returned so a caller in a frame loop allocates nothing. Its length is set to
+ * the number of views the pose carried, which is one for an inline session and two for a stereo
+ * one, and which this package never assumes.
+ */
+export declare function eyeViews(pose: XrViewerPose, layer: XrWebGlLayer | null, out?: EyeView[]): EyeView[];
+/**
+ * Point a camera at one eye.
+ *
+ * A one-line function on purpose: the interesting half is `Camera.adoptView`, which lives in core
+ * because the camera is core's and the reason it cannot derive these matrices is written there.
+ * What this adds is the direction of the dependency. `@driftengine/xr` supplies views to a camera;
+ * nothing in core reaches back for a session.
+ */
+export declare function aimCameraAtEye(camera: Camera, eye: EyeView): void;

package/dist/views.js

@@ -0,0 +1,74 @@
+/**
+ * An `XRView` turned into something the engine's camera can adopt.
+ *
+ * **The whole of the stereo path is here, and it is smaller than it sounds.** A frame carries one
+ * view per eye; each has a projection the runtime computed for that eye's optics and a transform
+ * giving where that eye is in the reference space. The engine draws the scene once per view, into
+ * that view's slice of one layer texture.
+ *
+ * **A view matrix is the inverse of the eye's transform**, and that is the only arithmetic in this
+ * file. WebXR hands over the transform's own `inverse` when it has one, because it usually does and
+ * inverting a matrix per eye per frame to recompute a number already sitting there would be work
+ * for nothing. When it does not, this inverts. Both paths are exercised, because a runtime is free
+ * to omit it and a path taken only on somebody else's hardware is a path nobody has run.
+ */
+import { mat4 } from 'gl-matrix';
+/**
+ * Reused across frames and eyes, because this runs twice a frame forever.
+ *
+ * Two of each, so a caller holding the left eye's matrices while it draws the right one still has
+ * them. A single scratch would be the kind of reuse that works until somebody keeps a reference.
+ */
+const scratch = [
+    { view: mat4.create(), projection: mat4.create() },
+    { view: mat4.create(), projection: mat4.create() },
+];
+/** Grown only if a runtime ever offers more views than eyes. Nothing does today. */
+function slotFor(index) {
+    while (scratch.length <= index)
+        scratch.push({ view: mat4.create(), projection: mat4.create() });
+    return scratch[index];
+}
+/**
+ * Turn a pose's views into eye views, into reused storage.
+ *
+ * `out` is filled and returned so a caller in a frame loop allocates nothing. Its length is set to
+ * the number of views the pose carried, which is one for an inline session and two for a stereo
+ * one, and which this package never assumes.
+ */
+export function eyeViews(pose, layer, out = []) {
+    out.length = 0;
+    for (let i = 0; i < pose.views.length; i++) {
+        const view = pose.views[i];
+        const slot = slotFor(i);
+        /*
+         * The runtime's own inverse where there is one. A transform's `inverse` is a spec field and is
+         * normally present; inverting to recompute it would be a matrix inversion per eye per frame for
+         * a number already in memory.
+         */
+        const inverse = view.transform.inverse?.matrix;
+        if (inverse !== undefined)
+            mat4.copy(slot.view, inverse);
+        else
+            mat4.invert(slot.view, view.transform.matrix);
+        mat4.copy(slot.projection, view.projectionMatrix);
+        out.push({
+            eye: view.eye,
+            view: slot.view,
+            projection: slot.projection,
+            viewport: layer?.getViewport(view) ?? null,
+        });
+    }
+    return out;
+}
+/**
+ * Point a camera at one eye.
+ *
+ * A one-line function on purpose: the interesting half is `Camera.adoptView`, which lives in core
+ * because the camera is core's and the reason it cannot derive these matrices is written there.
+ * What this adds is the direction of the dependency. `@driftengine/xr` supplies views to a camera;
+ * nothing in core reaches back for a session.
+ */
+export function aimCameraAtEye(camera, eye) {
+    camera.adoptView(eye.view, eye.projection);
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@driftengine/xr",
+  "version": "3.61.0",
+  "description": "WebXR sessions, stereo views, controller input and hand joints, over both backends",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "drift-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.mjs",
+    "!src/**/__snapshots__",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@driftengine/core": "3.61.0"
+  },
+  "author": "Drift Technologies",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drftrun/driftengine.git",
+    "directory": "packages/xr"
+  },
+  "homepage": "https://github.com/drftrun/driftengine#readme",
+  "bugs": "https://github.com/drftrun/driftengine/issues",
+  "keywords": [
+    "driftengine",
+    "3d",
+    "webgl",
+    "webgpu",
+    "typescript",
+    "webxr",
+    "virtual-reality",
+    "augmented-reality",
+    "hand-tracking"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}