@driftengine/xr 3.61.0

package/src/hands.ts

@@ -0,0 +1,161 @@
+/**
+ * Twenty-five joints a hand, read into flat arrays.
+ *
+ * **The joint names are the specification's and their order is this file's**, fixed once as
+ * `HAND_JOINTS` so an index means the same thing in every frame, on every device and in a recording
+ * somebody kept. Reading them into a `Float32Array` rather than handing back objects is the same
+ * decision every other per-frame reader in this engine makes: a hand is twenty-five poses, twice,
+ * at ninety hertz, and an object per joint is four and a half thousand allocations a second on the
+ * device this arrangement exists for.
+ *
+ * **A joint that is not tracked is not zeroed**, and that is the interesting decision here. Hand
+ * tracking loses joints constantly, one at a time, as fingers occlude each other from the camera's
+ * view. Writing an identity matrix into an untracked joint would collapse that finger to the wrist
+ * for one frame and snap it back on the next, which reads as a violent twitch. So the last known
+ * pose stays, `tracked` says it is stale, and a consumer decides whether to hold, fade or hide.
+ * That is a policy a game owns, and this package refuses to make it for them.
+ */
+
+import type { XrFrame, XrHand, XrInputSource, XrJointPose } from './types.ts';
+
+/**
+ * Every joint WebXR defines, in the order this engine indexes them.
+ *
+ * Wrist first, then each finger from its base outward, which is the order the specification lists
+ * them in and the order a reader expects. **Never reordered**: an index is written into recordings
+ * and compared across runs, so moving one would change what a stored hand means.
+ */
+export const HAND_JOINTS = [
+  'wrist',
+  'thumb-metacarpal',
+  'thumb-phalanx-proximal',
+  'thumb-phalanx-distal',
+  'thumb-tip',
+  'index-finger-metacarpal',
+  'index-finger-phalanx-proximal',
+  'index-finger-phalanx-intermediate',
+  'index-finger-phalanx-distal',
+  'index-finger-tip',
+  'middle-finger-metacarpal',
+  'middle-finger-phalanx-proximal',
+  'middle-finger-phalanx-intermediate',
+  'middle-finger-phalanx-distal',
+  'middle-finger-tip',
+  'ring-finger-metacarpal',
+  'ring-finger-phalanx-proximal',
+  'ring-finger-phalanx-intermediate',
+  'ring-finger-phalanx-distal',
+  'ring-finger-tip',
+  'pinky-finger-metacarpal',
+  'pinky-finger-phalanx-proximal',
+  'pinky-finger-phalanx-intermediate',
+  'pinky-finger-phalanx-distal',
+  'pinky-finger-tip',
+] as const;
+
+export type HandJoint = (typeof HAND_JOINTS)[number];
+
+export const JOINT_COUNT = HAND_JOINTS.length;
+
+/** The index of a named joint, so a consumer never counts. */
+export const JOINT_INDEX: Readonly<Record<string, number>> = Object.freeze(
+  Object.fromEntries(HAND_JOINTS.map((name, index) => [name, index])),
+);
+
+/**
+ * One hand's joints, allocated once and written into every frame.
+ *
+ * Sixteen floats a joint because a joint carries a full transform: a fingertip has an orientation
+ * as well as a position, and a consumer drawing a mesh needs both.
+ */
+export class HandSkeleton {
+  /** Row-major transforms, `JOINT_COUNT * 16`, in world space. */
+  readonly matrices = new Float32Array(JOINT_COUNT * 16);
+  /** Joint radii in metres, or 0 where the runtime offered none. */
+  readonly radii = new Float32Array(JOINT_COUNT);
+  /** Whether each joint had a pose in the last frame that was read. */
+  readonly tracked = new Uint8Array(JOINT_COUNT);
+  /** How many joints were tracked in that frame. Zero means the hand is not visible. */
+  trackedCount = 0;
+
+  /** Whether anything at all was seen, which is what a consumer branches on before drawing. */
+  get visible(): boolean {
+    return this.trackedCount > 0;
+  }
+
+  /**
+   * Forget everything, which is what a source going away means.
+   *
+   * Separate from a frame where every joint is merely untracked: a hand that has left has no last
+   * known pose worth holding, and a consumer that fades on loss needs the two told apart.
+   */
+  clear(): void {
+    this.matrices.fill(0);
+    this.radii.fill(0);
+    this.tracked.fill(0);
+    this.trackedCount = 0;
+  }
+}
+
+/**
+ * Read one hand into a skeleton.
+ *
+ * Returns whether anything was tracked. `false` with the skeleton left holding its last poses is
+ * the ordinary case for a hand that has moved out of the cameras' view, and it is not an error.
+ */
+export function readHand(
+  source: XrInputSource,
+  frame: XrFrame,
+  referenceSpace: unknown,
+  into: HandSkeleton,
+): boolean {
+  const hand = source.hand as XrHand | undefined;
+  if (hand === undefined || frame.getJointPose === undefined) {
+    into.trackedCount = 0;
+    into.tracked.fill(0);
+    return false;
+  }
+
+  let tracked = 0;
+  for (let i = 0; i < JOINT_COUNT; i++) {
+    const space = hand.get(HAND_JOINTS[i] as string);
+    const pose =
+      space === undefined || space === null
+        ? null
+        : ((frame.getJointPose(space, referenceSpace) as XrJointPose | null | undefined) ?? null);
+
+    if (pose === null) {
+      /*
+       * Left as it was. See the header: zeroing an occluded joint collapses that finger onto the
+       * wrist for one frame and snaps it back on the next, and a hand tracker loses joints
+       * constantly. The flag says the pose is stale; what to do about it is the consumer's.
+       */
+      into.tracked[i] = 0;
+      continue;
+    }
+
+    into.matrices.set(pose.transform.matrix, i * 16);
+    into.radii[i] = pose.radius ?? 0;
+    into.tracked[i] = 1;
+    tracked++;
+  }
+
+  into.trackedCount = tracked;
+  return tracked > 0;
+}
+
+/** A joint's position, read out of the flat storage without allocating. */
+export function jointPosition(
+  skeleton: HandSkeleton,
+  joint: HandJoint | number,
+  out: Float32Array,
+): boolean {
+  const index = typeof joint === 'number' ? joint : (JOINT_INDEX[joint] ?? -1);
+  if (index < 0 || index >= JOINT_COUNT) return false;
+  /* Column-major, as every matrix in this engine is, so the translation is elements 12 to 14. */
+  const at = index * 16;
+  out[0] = skeleton.matrices[at + 12] as number;
+  out[1] = skeleton.matrices[at + 13] as number;
+  out[2] = skeleton.matrices[at + 14] as number;
+  return skeleton.tracked[index] === 1;
+}

package/src/index.ts

@@ -0,0 +1,71 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * WebXR: sessions, stereo views, controller input and hand joints.
+ *
+ * **A package and not part of core**, so a game that never enters a session carries none of it.
+ * `size-gate.test.mjs` keeps that a measurement rather than an intention.
+ *
+ * **It supplies views to a camera and core never reaches back for a session.** That is the whole
+ * shape of the dependency: `Camera.adoptView` lives in core because the camera is core's, and the
+ * reason a camera cannot derive an XR eye's matrices is written beside it. Everything about
+ * sessions, layers, poses and hands is here.
+ *
+ * ## What is measured, and what is written down instead
+ *
+ * A real immersive session has never been run against this code. The machine it was written on has
+ * no headset: `immersive-vr` reports false, and `makeXRCompatible` throws, so no `XRFrame` can be
+ * produced there at all. What that machine does reach is asserted by `scripts/xr-check.mjs`, and
+ * everything past the first frame is exercised against a synthetic `XRSystem` in the unit tests.
+ *
+ * So **stereo on hardware, controller input, hand tracking, device performance and the compositor's
+ * reprojection are unmeasured**, and are tracked as such rather than claimed. Nothing
+ * here says otherwise.
+ */
+
+export type {
+  XrFrame,
+  XrGamepad,
+  XrHand,
+  XrInputSource,
+  XrJointPose,
+  XrMode,
+  XrRigidTransform,
+  XrSession,
+  XrSystem,
+  XrView,
+  XrViewerPose,
+  XrViewport,
+  XrWebGlLayer,
+} from './types.ts';
+
+export type { XrCompatibleContext, XrSupport } from './support.ts';
+export { bestMode, probeXrSupport } from './support.ts';
+
+export type { LayerBackend, LayerSources, XrLayer } from './layers.ts';
+export { chooseLayer } from './layers.ts';
+
+export type { EnterXrOptions, EnterXrResult, XrRun } from './session.ts';
+export { enterXr } from './session.ts';
+
+export type { EyeView } from './views.ts';
+export { aimCameraAtEye, eyeViews } from './views.ts';
+
+export type { ControllerState, Handedness, XrButton } from './input.ts';
+export {
+  XR_BUTTON,
+  buttonPressed,
+  buttonValue,
+  controllerFor,
+  readController,
+  readControllers,
+} from './input.ts';
+
+export type { HandJoint } from './hands.ts';
+export {
+  HAND_JOINTS,
+  HandSkeleton,
+  JOINT_COUNT,
+  JOINT_INDEX,
+  jointPosition,
+  readHand,
+} from './hands.ts';

package/src/input.ts

@@ -0,0 +1,134 @@
+/**
+ * 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.
+ */
+
+import type { XrFrame, XrInputSource, XrRigidTransform, XrSession } from './types.ts';
+
+/** Which hand, as WebXR reports it. `none` is a source with no handedness, like a gaze pointer. */
+export type Handedness = 'left' | 'right' | 'none';
+
+/**
+ * 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,
+} as const;
+
+export type XrButton = keyof typeof XR_BUTTON;
+
+/** One controller, as much of it as this engine reads. */
+export interface ControllerState {
+  readonly handedness: Handedness;
+  /** How the source is aimed: `tracked-pointer`, `gaze` or `screen`. */
+  readonly targetRayMode: string;
+  /** Whether a pose was available this frame. False while a controller is out of view. */
+  readonly tracked: boolean;
+  /** The grip transform's matrix, valid only while `tracked`. */
+  readonly gripMatrix: Float32Array | null;
+  /** Where the source is aiming, which is not where it is held. */
+  readonly rayMatrix: Float32Array | null;
+  /** Analogue values in the profile's order, and zero for a button the device does not have. */
+  readonly buttons: readonly number[];
+  readonly pressed: readonly boolean[];
+  readonly axes: readonly number[];
+}
+
+const NO_BUTTONS: readonly number[] = [];
+const NO_PRESSED: readonly boolean[] = [];
+const NO_AXES: readonly number[] = [];
+
+/**
+ * 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: XrSession,
+  frame: XrFrame,
+  referenceSpace: unknown,
+  out: ControllerState[] = [],
+): ControllerState[] {
+  out.length = 0;
+  for (const source of session.inputSources) {
+    out.push(readController(source, frame, referenceSpace));
+  }
+  return out;
+}
+
+function matrixOf(frame: XrFrame, space: unknown, referenceSpace: unknown): Float32Array | null {
+  if (space === undefined || space === null || frame.getPose === undefined) return null;
+  const pose = frame.getPose(space, referenceSpace);
+  const transform = pose?.transform as XrRigidTransform | undefined;
+  return transform?.matrix ?? null;
+}
+
+export function readController(
+  source: XrInputSource,
+  frame: XrFrame,
+  referenceSpace: unknown,
+): ControllerState {
+  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: ControllerState, button: XrButton): number {
+  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: ControllerState, button: XrButton): boolean {
+  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: readonly ControllerState[],
+  handedness: Handedness,
+): ControllerState | null {
+  for (const state of states) if (state.handedness === handedness) return state;
+  return null;
+}

package/src/layers.ts

@@ -0,0 +1,151 @@
+/**
+ * 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;
+}
+
+interface WebGlLayerCtor {
+  new (session: XrSession, gl: unknown): XrWebGlLayer;
+}
+
+interface GpuBindingCtor {
+  new (
+    session: XrSession,
+    device: unknown,
+  ): {
+    createProjectionLayer(options: { colorFormat: unknown }): unknown;
+  };
+  getPreferredColorFormat?(): unknown;
+}
+
+function webGlLayerCtor(): WebGlLayerCtor | null {
+  return (globalThis as { XRWebGLLayer?: WebGlLayerCtor }).XRWebGLLayer ?? null;
+}
+
+function gpuBindingCtor(): GpuBindingCtor | null {
+  return (globalThis as { XRGPUBinding?: GpuBindingCtor }).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: XrSession, sources: LayerSources): XrLayer {
+  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 as 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: XrSession, sources: LayerSources): XrLayer {
+  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 as 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/src/session.ts

@@ -0,0 +1,167 @@
+/**
+ * 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 { chooseLayer } from './layers.ts';
+import type { LayerBackend, LayerSources, XrLayer } from './layers.ts';
+import type { XrFrame, XrMode, XrSession, XrSystem } from './types.ts';
+
+/**
+ * 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: readonly string[] = ['local-floor', 'local', 'viewer'];
+
+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 };
+
+function systemOf(override?: XrSystem | null): XrSystem | null {
+  if (override !== undefined) return override;
+  return (globalThis.navigator as { xr?: XrSystem } | undefined)?.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: EnterXrOptions): Promise<EnterXrResult> {
+  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: XrSession;
+  try {
+    session = await system.requestSession(mode, { optionalFeatures: options.optionalFeatures });
+  } catch (error) {
+    const name = (error as 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: (() => void)[] = [];
+  session.addEventListener('end', () => {
+    ended = true;
+    for (const listener of listeners) listener();
+  });
+
+  const frameSource: 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: (timeMs: number, frame?: unknown) => void): number =>
+      session.requestAnimationFrame((timeMs: number, frame: XrFrame) => callback(timeMs, frame)),
+    cancelAnimationFrame: (handle: number): void => {
+      session.cancelAnimationFrame(handle);
+    },
+  };
+
+  return {
+    ok: true,
+    run: {
+      session,
+      referenceSpace: space.space,
+      referenceSpaceType: space.type,
+      layer,
+      backend: layer.backend,
+      frameSource,
+      async end(): Promise<void> {
+        if (ended) return;
+        ended = true;
+        await session.end().catch(() => {});
+      },
+      onEnd(listener: () => void): void {
+        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: XrSession): Promise<{ space: unknown; type: string } | null> {
+  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;
+}