@driftengine/xr 3.61.0

package/dist/input.js

@@ -0,0 +1,92 @@
+/**
+ * Controllers, read the way the rest of this engine reads input.
+ *
+ * **A controller is a gamepad with a pose, and the specification says so**: an `XRInputSource`
+ * carries an ordinary `Gamepad` whose button order is fixed by the WebXR gamepad profile. So the
+ * buttons are named here rather than indexed at every call site, and the names are the profile's
+ * rather than any device's marketing: `trigger`, `squeeze`, `touchpad`, `thumbstick`.
+ *
+ * **What is deliberately absent is a binding layer.** This engine has `ActionMap`, and a second one
+ * that only XR could reach would be a second answer to what a button means. A consumer maps a
+ * trigger to an action the same way they map a key, which is why this reads state and never
+ * dispatches an intent.
+ *
+ * **Nothing here is deterministic and none of it belongs in a fixed step.** A controller pose
+ * arrives with a frame, from a device, at a rate the runtime chooses. `drift/ui` already settled
+ * that a pointer position is `input.read` and outside `DETERMINISTIC_EFFECTS`, and a hand is the
+ * same kind of fact.
+ */
+/**
+ * The buttons the WebXR gamepad profile fixes, in its order.
+ *
+ * Indexes and not a guess: the profile pins 0 to the trigger and 1 to the squeeze for every device
+ * that reports `xr-standard`, which is what makes reading them by name safe. A device offering
+ * fewer buttons simply has none at the higher indexes, which reads as zero rather than as an error.
+ */
+export const XR_BUTTON = {
+    trigger: 0,
+    squeeze: 1,
+    touchpad: 2,
+    thumbstick: 3,
+};
+const NO_BUTTONS = [];
+const NO_PRESSED = [];
+const NO_AXES = [];
+/**
+ * Read every input source a session currently reports.
+ *
+ * `out` is filled and returned, so a frame loop allocates nothing after the first call. Sources
+ * come and go as controllers wake and sleep, which is why the list is read from the session every
+ * frame rather than cached at `inputsourceschange`: the event exists for a consumer that wants to
+ * react, and this is the polling half.
+ */
+export function readControllers(session, frame, referenceSpace, out = []) {
+    out.length = 0;
+    for (const source of session.inputSources) {
+        out.push(readController(source, frame, referenceSpace));
+    }
+    return out;
+}
+function matrixOf(frame, space, referenceSpace) {
+    if (space === undefined || space === null || frame.getPose === undefined)
+        return null;
+    const pose = frame.getPose(space, referenceSpace);
+    const transform = pose?.transform;
+    return transform?.matrix ?? null;
+}
+export function readController(source, frame, referenceSpace) {
+    const gripMatrix = matrixOf(frame, source.gripSpace, referenceSpace);
+    const rayMatrix = matrixOf(frame, source.targetRaySpace, referenceSpace);
+    const pad = source.gamepad;
+    return {
+        handedness: source.handedness,
+        targetRayMode: source.targetRayMode,
+        /*
+         * Tracked means a pose came back this frame, which is a different question from whether the
+         * source is listed. A controller set down on a table is still an input source and has no pose,
+         * and a consumer drawing a model at a stale matrix would leave it floating where it was
+         * dropped.
+         */
+        tracked: gripMatrix !== null || rayMatrix !== null,
+        gripMatrix,
+        rayMatrix,
+        buttons: pad ? pad.buttons.map((button) => button.value) : NO_BUTTONS,
+        pressed: pad ? pad.buttons.map((button) => button.pressed) : NO_PRESSED,
+        axes: pad ? [...pad.axes] : NO_AXES,
+    };
+}
+/** One named button's analogue value, or zero where the device has no such button. */
+export function buttonValue(state, button) {
+    return state.buttons[XR_BUTTON[button]] ?? 0;
+}
+/** Whether a named button is pressed, false where the device has no such button. */
+export function buttonPressed(state, button) {
+    return state.pressed[XR_BUTTON[button]] ?? false;
+}
+/** The first source for a hand, or null. Two sources may share a handedness and rarely do. */
+export function controllerFor(states, handedness) {
+    for (const state of states)
+        if (state.handedness === handedness)
+            return state;
+    return null;
+}

package/dist/layers.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Where a session draws, on either backend.
+ *
+ * **Both paths are built, and the WebGPU one is newer than the engine that uses it.** Measured
+ * 2026-09-05 in Chrome 151: `XRGPUBinding` is undefined under ordinary flags and present under
+ * `--enable-experimental-web-platform-features`, isolated from three other flags that do not do it.
+ * Chrome's own note calls WebGPU in WebXR available for developer testing on Windows and Android.
+ *
+ * So the choice is made from what the runtime **has**, never from a preference:
+ *
+ * - `XRGPUBinding` present and a device to hand: a projection layer, and the session composites it.
+ * - Otherwise `XRWebGLLayer`, which every WebXR implementation has had since the first one.
+ *
+ * **A backend the session cannot bind is not a failure to report, it is the other path.** A game
+ * running on WebGPU on a browser whose WebXR is WebGL-only should enter a session on WebGL2 rather
+ * than refuse, which is why `chooseLayer` answers with what it built and which backend it is for
+ * instead of throwing.
+ */
+import type { XrSession, XrWebGlLayer } from './types.ts';
+export type LayerBackend = 'webgl2' | 'webgpu';
+export interface XrLayer {
+    readonly backend: LayerBackend;
+    /** Set on the session's render state. A WebGL layer here; a projection layer goes in `layers`. */
+    readonly baseLayer: XrWebGlLayer | null;
+    /** The WebGPU projection layer, when that is the path taken. */
+    readonly projectionLayer: unknown | null;
+    /** A whole sentence when the chosen path was not the one asked for. Empty when it was. */
+    readonly reason: string;
+}
+/** What a caller offers. Whichever of the two it has; both is allowed and neither is not. */
+export interface LayerSources {
+    /** A WebGL2 context, already made XR compatible by the caller. */
+    readonly gl?: unknown;
+    /** A `GPUDevice`. */
+    readonly device?: unknown;
+}
+/**
+ * Build the layer this session and these sources allow.
+ *
+ * Never throws. It is called at the moment a session starts, which is a moment a consumer is
+ * showing a user something, and `AGENTS.md`'s rule about not throwing in a frame loop is the same
+ * rule one step earlier: a session that cannot draw should say so and leave the page alive.
+ */
+export declare function chooseLayer(session: XrSession, sources: LayerSources): XrLayer;

package/dist/layers.js

@@ -0,0 +1,107 @@
+/**
+ * Where a session draws, on either backend.
+ *
+ * **Both paths are built, and the WebGPU one is newer than the engine that uses it.** Measured
+ * 2026-09-05 in Chrome 151: `XRGPUBinding` is undefined under ordinary flags and present under
+ * `--enable-experimental-web-platform-features`, isolated from three other flags that do not do it.
+ * Chrome's own note calls WebGPU in WebXR available for developer testing on Windows and Android.
+ *
+ * So the choice is made from what the runtime **has**, never from a preference:
+ *
+ * - `XRGPUBinding` present and a device to hand: a projection layer, and the session composites it.
+ * - Otherwise `XRWebGLLayer`, which every WebXR implementation has had since the first one.
+ *
+ * **A backend the session cannot bind is not a failure to report, it is the other path.** A game
+ * running on WebGPU on a browser whose WebXR is WebGL-only should enter a session on WebGL2 rather
+ * than refuse, which is why `chooseLayer` answers with what it built and which backend it is for
+ * instead of throwing.
+ */
+function webGlLayerCtor() {
+    return globalThis.XRWebGLLayer ?? null;
+}
+function gpuBindingCtor() {
+    return globalThis.XRGPUBinding ?? null;
+}
+/**
+ * Build the layer this session and these sources allow.
+ *
+ * Never throws. It is called at the moment a session starts, which is a moment a consumer is
+ * showing a user something, and `AGENTS.md`'s rule about not throwing in a frame loop is the same
+ * rule one step earlier: a session that cannot draw should say so and leave the page alive.
+ */
+export function chooseLayer(session, sources) {
+    const binding = gpuBindingCtor();
+    if (sources.device !== undefined && binding !== null) {
+        try {
+            const bound = new binding(session, sources.device);
+            const colorFormat = binding.getPreferredColorFormat?.() ?? 'bgra8unorm';
+            const projectionLayer = bound.createProjectionLayer({ colorFormat });
+            session.updateRenderState({ layers: [projectionLayer] });
+            return { backend: 'webgpu', baseLayer: null, projectionLayer, reason: '' };
+        }
+        catch (error) {
+            /*
+             * Falling through to WebGL2 rather than failing. The binding constructs on a browser whose
+             * runtime cannot actually composite a WebGPU layer, so the honest test of this path is
+             * building the layer, and the honest answer to it failing is the path that has worked since
+             * WebXR shipped.
+             */
+            const name = error?.name ?? 'Error';
+            const fallback = buildWebGlLayer(session, sources);
+            return fallback.baseLayer === null
+                ? {
+                    ...fallback,
+                    reason: `the WebGPU layer could not be built (${name}) and no WebGL2 context was offered to ` +
+                        'fall back to.',
+                }
+                : {
+                    ...fallback,
+                    reason: `the WebGPU layer could not be built (${name}), so this session draws through ` +
+                        'WebGL2. WebGPU in WebXR is experimental and is behind a flag in current browsers.',
+                };
+        }
+    }
+    const layer = buildWebGlLayer(session, sources);
+    if (layer.baseLayer !== null && sources.device !== undefined && binding === null) {
+        return {
+            ...layer,
+            reason: 'this browser has no XRGPUBinding, so a WebGPU device cannot be bound to a session and ' +
+                'this one draws through WebGL2.',
+        };
+    }
+    return layer;
+}
+function buildWebGlLayer(session, sources) {
+    const ctor = webGlLayerCtor();
+    if (ctor === null) {
+        return {
+            backend: 'webgl2',
+            baseLayer: null,
+            projectionLayer: null,
+            reason: 'this browser has no XRWebGLLayer, so a session has nothing to draw into.',
+        };
+    }
+    if (sources.gl === undefined) {
+        return {
+            backend: 'webgl2',
+            baseLayer: null,
+            projectionLayer: null,
+            reason: 'no WebGL2 context was offered, so a session has nothing to draw into.',
+        };
+    }
+    try {
+        const baseLayer = new ctor(session, sources.gl);
+        session.updateRenderState({ baseLayer });
+        return { backend: 'webgl2', baseLayer, projectionLayer: null, reason: '' };
+    }
+    catch (error) {
+        const name = error?.name ?? 'Error';
+        return {
+            backend: 'webgl2',
+            baseLayer: null,
+            projectionLayer: null,
+            reason: `the WebGL2 layer could not be built (${name}), which is what happens when the context ` +
+                'was never made XR compatible.',
+        };
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A session, from asking for one to giving it back.
+ *
+ * **`requestSession` must be called from a user gesture** and no wrapper can change that, so this
+ * takes the call rather than deciding when to make it: a consumer's button handler calls
+ * `enterXr`, and everything after that is this file's.
+ *
+ * What it owns is the order, which has four steps and fails differently at each:
+ *
+ * 1. the session itself, which a browser refuses without a device or a gesture,
+ * 2. a layer to draw into, which needs a context the runtime accepts,
+ * 3. a reference space, which decides what the poses in every frame are relative to,
+ * 4. the frame source, which is what makes the engine's loop run on the headset's clock.
+ *
+ * **Every failure answers with a sentence and none of them throws.** A consumer whose button did
+ * nothing is owed the difference between a browser without WebXR, a machine without a headset, a
+ * context that would not become XR compatible, and a reference space the runtime declined. Those
+ * are four different things to do next, and `reason` is where they are told apart.
+ */
+import type { FrameSource } from '@driftengine/core';
+import type { LayerBackend, LayerSources, XrLayer } from './layers.ts';
+import type { XrMode, XrSession, XrSystem } from './types.ts';
+export interface EnterXrOptions {
+    readonly mode?: XrMode;
+    /** Passed to `requestSession`. `hand-tracking` is here rather than required. */
+    readonly optionalFeatures?: readonly string[];
+    readonly sources: LayerSources;
+    /** Override the system, which is how a test drives this without a headset. */
+    readonly system?: XrSystem | null;
+}
+export interface XrRun {
+    readonly session: XrSession;
+    readonly referenceSpace: unknown;
+    readonly referenceSpaceType: string;
+    readonly layer: XrLayer;
+    readonly backend: LayerBackend;
+    /** Hand this to `startLoop` and the engine runs on the session's clock. */
+    readonly frameSource: FrameSource;
+    /** Ends the session. Safe to call twice. */
+    end(): Promise<void>;
+    /** Runs when the session ends, however it ends, including the user taking the headset off. */
+    onEnd(listener: () => void): void;
+}
+export type EnterXrResult = {
+    readonly ok: true;
+    readonly run: XrRun;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Ask for a session and set everything up behind it.
+ *
+ * Call it from a click. Everything it can go wrong at is a `reason` and never a throw.
+ */
+export declare function enterXr(options: EnterXrOptions): Promise<EnterXrResult>;

package/dist/session.js

@@ -0,0 +1,131 @@
+/**
+ * A session, from asking for one to giving it back.
+ *
+ * **`requestSession` must be called from a user gesture** and no wrapper can change that, so this
+ * takes the call rather than deciding when to make it: a consumer's button handler calls
+ * `enterXr`, and everything after that is this file's.
+ *
+ * What it owns is the order, which has four steps and fails differently at each:
+ *
+ * 1. the session itself, which a browser refuses without a device or a gesture,
+ * 2. a layer to draw into, which needs a context the runtime accepts,
+ * 3. a reference space, which decides what the poses in every frame are relative to,
+ * 4. the frame source, which is what makes the engine's loop run on the headset's clock.
+ *
+ * **Every failure answers with a sentence and none of them throws.** A consumer whose button did
+ * nothing is owed the difference between a browser without WebXR, a machine without a headset, a
+ * context that would not become XR compatible, and a reference space the runtime declined. Those
+ * are four different things to do next, and `reason` is where they are told apart.
+ */
+import { chooseLayer } from './layers.js';
+/**
+ * Which space poses are reported in.
+ *
+ * `local-floor` first, because a scene authored in metres from a floor is what a room-scale
+ * experience is, and `local` puts the origin at the headset's starting height instead, which stands
+ * a player's feet wherever their head happened to be. `viewer` is the last resort and the only one
+ * an inline session is guaranteed.
+ */
+const SPACE_ORDER = ['local-floor', 'local', 'viewer'];
+function systemOf(override) {
+    if (override !== undefined)
+        return override;
+    return globalThis.navigator?.xr ?? null;
+}
+/**
+ * Ask for a session and set everything up behind it.
+ *
+ * Call it from a click. Everything it can go wrong at is a `reason` and never a throw.
+ */
+export async function enterXr(options) {
+    const system = systemOf(options.system);
+    if (system === null) {
+        return { ok: false, reason: 'this browser has no WebXR: navigator.xr is not defined.' };
+    }
+    const mode = options.mode ?? 'immersive-vr';
+    let session;
+    try {
+        session = await system.requestSession(mode, { optionalFeatures: options.optionalFeatures });
+    }
+    catch (error) {
+        const name = error?.name ?? 'Error';
+        return {
+            ok: false,
+            reason: `the browser refused an immersive session (${mode}, ${name}). That is what it answers when no device ` +
+                'is attached, and also when the call did not come from a user gesture.',
+        };
+    }
+    const layer = chooseLayer(session, options.sources);
+    if (layer.baseLayer === null && layer.projectionLayer === null) {
+        await session.end().catch(() => { });
+        return { ok: false, reason: layer.reason };
+    }
+    const space = await firstSpace(session);
+    if (space === null) {
+        await session.end().catch(() => { });
+        return {
+            ok: false,
+            reason: `the session offered none of ${SPACE_ORDER.join(', ')} as a reference space, so there is ` +
+                'nothing to report poses relative to.',
+        };
+    }
+    let ended = false;
+    const listeners = [];
+    session.addEventListener('end', () => {
+        ended = true;
+        for (const listener of listeners)
+            listener();
+    });
+    const frameSource = {
+        /*
+         * Narrowed here and nowhere else. `core`'s loop types this argument `unknown` because it has no
+         * business naming an `XRFrame`; this is the one place that knows what arrived, and it hands it
+         * straight on rather than reading it, because the reading belongs to whoever draws.
+         */
+        requestAnimationFrame: (callback) => session.requestAnimationFrame((timeMs, frame) => callback(timeMs, frame)),
+        cancelAnimationFrame: (handle) => {
+            session.cancelAnimationFrame(handle);
+        },
+    };
+    return {
+        ok: true,
+        run: {
+            session,
+            referenceSpace: space.space,
+            referenceSpaceType: space.type,
+            layer,
+            backend: layer.backend,
+            frameSource,
+            async end() {
+                if (ended)
+                    return;
+                ended = true;
+                await session.end().catch(() => { });
+            },
+            onEnd(listener) {
+                if (ended)
+                    listener();
+                else
+                    listeners.push(listener);
+            },
+        },
+    };
+}
+/**
+ * The best reference space this session will give, in the order that matters to a scene.
+ *
+ * Asked one at a time rather than in parallel, because a runtime may charge for a space it then has
+ * to discard and because the order is the whole point: taking whichever resolves first would be a
+ * race deciding where a player's floor is.
+ */
+async function firstSpace(session) {
+    for (const type of SPACE_ORDER) {
+        try {
+            return { space: await session.requestReferenceSpace(type), type };
+        }
+        catch {
+            /* Declined. The next one is not a fallback so much as the next preference. */
+        }
+    }
+    return null;
+}

package/dist/support.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What this browser can actually do, asked by doing it.
+ *
+ * **`isSessionSupported` is a promise about a mode and not an answer about this machine**, and the
+ * difference is not academic. Measured on 2026-09-05, Chrome 151 on Linux with no headset:
+ * `isSessionSupported('inline')` answers **true**, `requestSession('inline')` **succeeds**,
+ * `requestReferenceSpace('viewer')` **succeeds**, and then `gl.makeXRCompatible()` throws
+ * `InvalidStateError` because there is no XR device. Without that call there is no base layer, and
+ * without a base layer a session delivers **no frame at all**. Every promise along the way was
+ * kept, and nothing could be drawn.
+ *
+ * So this asks the question `probeDevice` asks about a GPU, and for the reason `probeDevice`'s own
+ * header gives: *a device that reports support and then draws nothing is a device that lied.* It
+ * tries the step that fails.
+ *
+ * **`reason` is a whole sentence and never empty when something is missing.** A consumer whose
+ * button does nothing is owed the difference between a browser with no WebXR, a machine with no
+ * headset, and a context that refused to become XR compatible, because those are three different
+ * things to do next. The island pool's `parallelism.reason` and `createSplatSortWorker`'s single
+ * warning are the same discipline; a silent false is the one outcome none of them allows.
+ */
+import type { XrMode, XrSystem } from './types.ts';
+export interface XrSupport {
+    /** Whether `navigator.xr` exists at all. Everything else is false without it. */
+    readonly present: boolean;
+    readonly immersiveVr: boolean;
+    readonly immersiveAr: boolean;
+    readonly inline: boolean;
+    /**
+     * Whether a rendering context could be made XR compatible.
+     *
+     * The step that actually fails without a device, and the one no `isSessionSupported` reports on.
+     */
+    readonly compatible: boolean;
+    /** Empty when a session could be entered. A whole sentence otherwise. */
+    readonly reason: string;
+}
+/** A context that can be asked to become XR compatible. Both backends' contexts satisfy it. */
+export interface XrCompatibleContext {
+    makeXRCompatible?(): Promise<void>;
+}
+/**
+ * Ask, and try the step that lies.
+ *
+ * `context` is optional because a consumer may want the modes before they have built a renderer.
+ * Without one, `compatible` is false and `reason` says the question was not asked, which is a
+ * different thing from asked and refused.
+ */
+export declare function probeXrSupport(context?: XrCompatibleContext | null, override?: XrSystem | null): Promise<XrSupport>;
+/** The best mode this support answer allows, or null when none is worth asking for. */
+export declare function bestMode(support: XrSupport): XrMode | null;

package/dist/support.js

@@ -0,0 +1,123 @@
+/**
+ * What this browser can actually do, asked by doing it.
+ *
+ * **`isSessionSupported` is a promise about a mode and not an answer about this machine**, and the
+ * difference is not academic. Measured on 2026-09-05, Chrome 151 on Linux with no headset:
+ * `isSessionSupported('inline')` answers **true**, `requestSession('inline')` **succeeds**,
+ * `requestReferenceSpace('viewer')` **succeeds**, and then `gl.makeXRCompatible()` throws
+ * `InvalidStateError` because there is no XR device. Without that call there is no base layer, and
+ * without a base layer a session delivers **no frame at all**. Every promise along the way was
+ * kept, and nothing could be drawn.
+ *
+ * So this asks the question `probeDevice` asks about a GPU, and for the reason `probeDevice`'s own
+ * header gives: *a device that reports support and then draws nothing is a device that lied.* It
+ * tries the step that fails.
+ *
+ * **`reason` is a whole sentence and never empty when something is missing.** A consumer whose
+ * button does nothing is owed the difference between a browser with no WebXR, a machine with no
+ * headset, and a context that refused to become XR compatible, because those are three different
+ * things to do next. The island pool's `parallelism.reason` and `createSplatSortWorker`'s single
+ * warning are the same discipline; a silent false is the one outcome none of them allows.
+ */
+const NOTHING = {
+    present: false,
+    immersiveVr: false,
+    immersiveAr: false,
+    inline: false,
+    compatible: false,
+    reason: 'this browser has no WebXR: navigator.xr is not defined.',
+};
+function systemOf() {
+    const nav = globalThis.navigator;
+    return nav?.xr ?? null;
+}
+async function supports(system, mode) {
+    try {
+        return await system.isSessionSupported(mode);
+    }
+    catch {
+        /*
+         * A rejection is an answer and not an error. `isSessionSupported` rejects rather than resolving
+         * false where a permissions policy forbids the mode, which is a `false` a consumer can do
+         * nothing about and must not be a thrown exception on a page that merely asked.
+         */
+        return false;
+    }
+}
+/**
+ * Ask, and try the step that lies.
+ *
+ * `context` is optional because a consumer may want the modes before they have built a renderer.
+ * Without one, `compatible` is false and `reason` says the question was not asked, which is a
+ * different thing from asked and refused.
+ */
+export async function probeXrSupport(context, 
+/*
+ * The system, overridable for the same reason `enterXr` takes one: a test cannot assign
+ * `globalThis.navigator`, which is getter-only, and stubbing a global to ask a question about a
+ * pure function would be surgery on the environment to avoid a parameter.
+ */
+override) {
+    const system = override === undefined ? systemOf() : override;
+    if (system === null)
+        return NOTHING;
+    const [immersiveVr, immersiveAr, inline] = await Promise.all([
+        supports(system, 'immersive-vr'),
+        supports(system, 'immersive-ar'),
+        supports(system, 'inline'),
+    ]);
+    let compatible = false;
+    let compatibleReason = '';
+    if (context?.makeXRCompatible === undefined) {
+        compatibleReason =
+            'no rendering context was offered, so whether one can be made XR compatible is unasked.';
+    }
+    else {
+        try {
+            await context.makeXRCompatible();
+            compatible = true;
+        }
+        catch (error) {
+            const name = error?.name ?? 'Error';
+            compatibleReason =
+                `the rendering context refused to become XR compatible (${name}), which is what happens ` +
+                    'when the browser has WebXR but this machine has no XR device attached.';
+        }
+    }
+    /*
+     * **The deepest failure wins, and the first draft had this backwards.** It reported the mode
+     * message before the compatibility one, so a machine whose context had actually been offered and
+     * refused was told "only an inline session is available here" — true, and not the thing that had
+     * just gone wrong. `xr-check.mjs` caught it: `compatible` was false while `reason` said nothing
+     * about it.
+     *
+     * A refusal that was *tried* outranks a report about what a mode list says, because it is the
+     * concrete step that failed and the one a consumer can do something about.
+     */
+    const anyMode = immersiveVr || immersiveAr || inline;
+    let reason = '';
+    if (context?.makeXRCompatible !== undefined && !compatible) {
+        reason = compatibleReason;
+    }
+    else if (!anyMode) {
+        reason =
+            'this browser has WebXR but reports no session mode as supported, which is what a machine ' +
+                'with no headset answers.';
+    }
+    else if (!immersiveVr && !immersiveAr) {
+        reason =
+            'only an inline session is available here. An inline session has one view and no headset ' +
+                'pose, so it draws a window into the scene and does not present to a device.';
+    }
+    return { present: true, immersiveVr, immersiveAr, inline, compatible, reason };
+}
+/** The best mode this support answer allows, or null when none is worth asking for. */
+export function bestMode(support) {
+    if (support.immersiveVr)
+        return 'immersive-vr';
+    if (support.immersiveAr)
+        return 'immersive-ar';
+    if (support.inline)
+        return 'inline';
+    return null;
+}

package/dist/testing/synthetic.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 type { XrSession, XrSystem, XrWebGlLayer } from '../types.ts';
+export interface SyntheticOptions {
+    /** Modes the system reports and will grant. Everything else is refused. */
+    readonly modes?: readonly string[];
+    /** Reference spaces the session will grant, in the order it is asked. */
+    readonly spaces?: readonly string[];
+    readonly headHeight?: number;
+    /** One entry per controller. `hand` gives it twenty-five joints as well. */
+    readonly controllers?: readonly {
+        handedness: 'left' | 'right';
+        hand?: boolean;
+    }[];
+    /** Views a frame carries. Two by default, which is what a headset gives. */
+    readonly views?: 'stereo' | 'mono';
+}
+export interface SyntheticSystem extends XrSystem {
+    /** Deliver one frame to whoever asked. Nothing happens on its own. */
+    advance(timeMs?: number): void;
+    /** Sessions this system has granted, in order. */
+    readonly sessions: SyntheticSession[];
+    /** End the newest session the way a runtime does when a headset is removed. */
+    endLatest(): void;
+}
+export interface SyntheticSession extends XrSession {
+    readonly renderState: {
+        baseLayer?: XrWebGlLayer;
+        layers?: readonly unknown[];
+    };
+    readonly endedCount: number;
+    /** Set a button's analogue value on a controller, which also sets `pressed` past a half. */
+    setButton(handedness: 'left' | 'right', index: number, value: number): void;
+    /** Stop reporting a joint, the way an occluded finger stops being tracked. */
+    setJointTracked(handedness: 'left' | 'right', joint: string, tracked: boolean): void;
+}
+/**
+ * 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 declare function syntheticXr(options?: SyntheticOptions): SyntheticSystem;
+/** A layer a synthetic session accepts, so the render-state path can be exercised too. */
+export declare function syntheticGlLayer(): XrWebGlLayer;