@opsydyn/effect-three-foldkit 0.0.0-stage → 0.2.0

package/src/dom/xrInputs.ts

@@ -0,0 +1,309 @@
+/**
+ * A session's input sources, each frame: where each points (`Aim`), its gamepad's sticks
+ * and buttons, in AR where its ray meets a real surface, and drawing its ray and a hand's
+ * joints into the presented scene.
+ *
+ * Behavioural references: pmndrs/xr at `0e1acd8` (`packages/xr/src/pointer` ray-casts
+ * along every source's target ray each frame; `controller-locomotion.ts` reads the
+ * `xr-standard` thumbstick, axes 2 and 3, forward negative; `hit-test.ts` requests a hit
+ * test source per space and reads `getHitTestResults` each frame), and three.js's
+ * `XRHandPrimitiveModel` at 0.186.1 (a sphere per hand joint, sized by its radius).
+ *
+ * @module
+ */
+import type {
+  Ray,
+  Vec3,
+  Xr,
+  XrButtonName,
+  XrHand,
+  XrInput,
+  XrStickDirection,
+} from '@opsydyn/effect-three';
+import {
+  BufferGeometry,
+  Float32BufferAttribute,
+  Group,
+  InstancedMesh,
+  Line,
+  LineBasicMaterial,
+  Matrix4,
+  MeshBasicMaterial,
+  Quaternion,
+  SphereGeometry,
+  Vector3,
+} from 'three';
+
+/** A target ray pose as a ray in the reference space: from its position along its −z. */
+export const rayOf = (pose: XRPose): Ray => {
+  const { position, orientation } = pose.transform;
+  const { x, y, z, w } = orientation;
+  // −z rotated by the orientation quaternion.
+  return {
+    origin: [position.x, position.y, position.z],
+    direction: [-2 * (x * z + w * y), -2 * (y * z - w * x), -(1 - 2 * (x * x + y * y))],
+  };
+};
+
+/** The `xr-standard` mapping's buttons, by index. */
+const buttonNames: ReadonlyArray<XrButtonName> = [
+  'trigger',
+  'squeeze',
+  'touchpad',
+  'thumbstick',
+  'primary',
+  'secondary',
+];
+
+/** Past this far a stick is pushed; back under the lower mark it is centred again. */
+const stickThresholds = { push: 0.6, release: 0.3 } as const;
+
+/** Where a stick at `(x, y)` points, keeping `previous` until it clearly changes. */
+export const stickDirection = (
+  x: number,
+  y: number,
+  previous: XrStickDirection,
+): XrStickDirection => {
+  if (Math.max(Math.abs(x), Math.abs(y)) < stickThresholds.release) return 'center';
+  if (Math.max(Math.abs(x), Math.abs(y)) < stickThresholds.push) return previous;
+  if (Math.abs(x) >= Math.abs(y)) return x < 0 ? 'left' : 'right';
+  return y < 0 ? 'forward' : 'back';
+};
+
+const handOf = (source: XRInputSource): XrHand => source.handedness;
+
+/** What the visuals show: a line along each ray, spheres on each hand's joints. */
+const rayLength = 1.5;
+const jointCount = 25;
+const rayMaterial = new LineBasicMaterial({ color: 0xffffff, transparent: true, opacity: 0.6 });
+const jointMaterial = new MeshBasicMaterial({ color: 0xe8e4dc });
+const jointGeometry = new SphereGeometry(1, 10, 8);
+
+type Visual = { readonly ray: Line; readonly joints: InstancedMesh | undefined };
+
+const makeVisual = (source: XRInputSource, group: Group): Visual => {
+  const geometry = new BufferGeometry();
+  geometry.setAttribute('position', new Float32BufferAttribute([0, 0, 0, 0, 0, -rayLength], 3));
+  const ray = new Line(geometry, rayMaterial);
+  ray.raycast = () => undefined;
+  ray.matrixAutoUpdate = false;
+  group.add(ray);
+  const joints =
+    source.hand === undefined
+      ? undefined
+      : new InstancedMesh(jointGeometry, jointMaterial, jointCount);
+  if (joints !== undefined) {
+    joints.raycast = () => undefined;
+    joints.frustumCulled = false;
+    group.add(joints);
+  }
+  return { ray, joints };
+};
+
+const disposeVisual = (visual: Visual): void => {
+  visual.ray.removeFromParent();
+  visual.ray.geometry.dispose();
+  visual.joints?.removeFromParent();
+  visual.joints?.dispose();
+};
+
+const matrix = new Matrix4();
+const up = new Vector3(0, 1, 0);
+const position = new Vector3();
+const turn = new Quaternion();
+const size = new Vector3();
+
+/** Places a hand's joint spheres from this frame's joint poses. */
+const placeJoints = (
+  joints: InstancedMesh,
+  hand: XRHand,
+  frame: XRFrame,
+  space: XRReferenceSpace,
+): void => {
+  let slot = 0;
+  for (const jointSpace of hand.values()) {
+    const pose = frame.getJointPose?.(jointSpace, space);
+    if (pose !== undefined && pose !== null && slot < jointCount) {
+      const { x, y, z } = pose.transform.position;
+      const o = pose.transform.orientation;
+      const radius = pose.radius ?? 0.008;
+      matrix.compose(position.set(x, y, z), turn.set(o.x, o.y, o.z, o.w), size.setScalar(radius));
+      joints.setMatrixAt(slot, matrix);
+      slot++;
+    }
+  }
+  joints.count = slot;
+  joints.instanceMatrix.needsUpdate = true;
+};
+
+type Tracked = {
+  readonly id: number;
+  visual: Visual | undefined;
+  stick: XrStickDirection;
+  /** The thumbstick's axes this frame, `[x, y]`. */
+  axes: readonly [number, number];
+  readonly pressed: Array<boolean>;
+  hitTest: XRHitTestSource | undefined;
+  /** Where its ray last met a real surface. */
+  surface: { readonly point: Vec3; readonly normal: Vec3 } | undefined;
+};
+
+/** A hit test result's pose as a point and the surface's normal (the pose's +y). */
+const surfaceOf = (pose: XRPose): { readonly point: Vec3; readonly normal: Vec3 } => {
+  const { position: p, orientation: q } = pose.transform;
+  // +y rotated by the orientation quaternion.
+  return {
+    point: [p.x, p.y, p.z],
+    normal: [
+      2 * (q.x * q.y - q.w * q.z),
+      1 - 2 * (q.x * q.x + q.z * q.z),
+      2 * (q.y * q.z + q.w * q.x),
+    ],
+  };
+};
+
+export type XrInputs = {
+  /** Reads every input source in this frame, in `space` (the scene's). */
+  readonly frame: (frame: XRFrame, space: XRReferenceSpace) => void;
+  /** A source's id, the same for its selects as for its aims. */
+  readonly idOf: (source: XRInputSource) => number;
+  /** A select ended: in AR with hit tests, report where its ray met a surface. */
+  readonly selected: (source: XRInputSource) => void;
+  /** Ends tracking: every source is lost, and the visuals go. */
+  readonly stop: () => void;
+  /** Each hand's thumbstick this frame (`[0, 0]` without one). */
+  readonly sticks: () => {
+    readonly left: readonly [number, number];
+    readonly right: readonly [number, number];
+  };
+};
+
+/**
+ * Tracks `session`'s input sources, sending what they do to `input` and drawing them into
+ * `group` (added to the presented scene) while `settings().showInputs`.
+ */
+export const trackInputs = (
+  session: XRSession,
+  group: Group,
+  settings: () => Xr | null,
+  input: (input: XrInput) => void,
+): XrInputs => {
+  const tracked = new Map<XRInputSource, Tracked>();
+  let nextId = 0;
+
+  const trackedOf = (source: XRInputSource): Tracked => {
+    const known = tracked.get(source);
+    if (known !== undefined) return known;
+    const created: Tracked = {
+      id: nextId++,
+      visual: undefined,
+      stick: 'center',
+      axes: [0, 0],
+      pressed: [],
+      hitTest: undefined,
+      surface: undefined,
+    };
+    tracked.set(source, created);
+    if (settings()?.hitTest === true && session.requestHitTestSource !== undefined) {
+      // Refused where the session lacks hit testing (it is optional): no surfaces, then.
+      void session.requestHitTestSource({ space: source.targetRaySpace })?.then(
+        (hitTest) => {
+          if (tracked.get(source) === created) created.hitTest = hitTest;
+          else hitTest.cancel();
+        },
+        () => undefined,
+      );
+    }
+    return created;
+  };
+
+  const forget = (source: XRInputSource, state: Tracked): void => {
+    tracked.delete(source);
+    if (state.visual !== undefined) disposeVisual(state.visual);
+    state.hitTest?.cancel();
+    input({ _tag: 'Lost', source: state.id });
+  };
+
+  const gamepad = (source: XRInputSource, state: Tracked): void => {
+    const pad = source.gamepad;
+    if (pad === undefined || pad === null || pad.mapping !== 'xr-standard') return;
+    const hand = handOf(source);
+    buttonNames.forEach((button, index) => {
+      const pressed = pad.buttons[index]?.pressed ?? false;
+      if (pressed !== (state.pressed[index] ?? false)) {
+        state.pressed[index] = pressed;
+        input({ _tag: 'Button', source: state.id, hand, button, pressed });
+      }
+    });
+    state.axes = [pad.axes[2] ?? 0, pad.axes[3] ?? 0];
+    const direction = stickDirection(state.axes[0], state.axes[1], state.stick);
+    if (direction !== state.stick) {
+      state.stick = direction;
+      input({ _tag: 'Stick', source: state.id, hand, direction });
+    }
+  };
+
+  const show = (
+    source: XRInputSource,
+    state: Tracked,
+    ray: Ray,
+    frame: XRFrame,
+    space: XRReferenceSpace,
+  ) => {
+    if (settings()?.showInputs !== true) {
+      if (state.visual !== undefined) disposeVisual(state.visual);
+      state.visual = undefined;
+      return;
+    }
+    state.visual ??= makeVisual(source, group);
+    const [ox, oy, oz] = ray.origin;
+    const [dx, dy, dz] = ray.direction;
+    // Turn −z (along which the line runs) to the ray: lookAt points +z from the target.
+    matrix.lookAt(position.set(0, 0, 0), size.set(dx, dy, dz), up);
+    matrix.setPosition(ox, oy, oz);
+    state.visual.ray.matrix.copy(matrix);
+    // A tracked hand points from its wrist; its joints show where it is, not a ray.
+    state.visual.ray.visible = source.hand === undefined;
+    if (state.visual.joints !== undefined && source.hand !== undefined) {
+      placeJoints(state.visual.joints, source.hand, frame, space);
+    }
+  };
+
+  return {
+    frame: (frame, space) => {
+      const present = new Set<XRInputSource>();
+      for (const source of session.inputSources) {
+        present.add(source);
+        const state = trackedOf(source);
+        const pose = frame.getPose(source.targetRaySpace, space);
+        if (pose !== undefined && pose !== null) {
+          const ray = rayOf(pose);
+          input({ _tag: 'Aim', source: state.id, ray });
+          show(source, state, ray, frame, space);
+        }
+        gamepad(source, state);
+        if (state.hitTest !== undefined) {
+          const result = frame.getHitTestResults(state.hitTest)[0]?.getPose(space);
+          state.surface = result === undefined || result === null ? undefined : surfaceOf(result);
+        }
+      }
+      for (const [source, state] of tracked) if (!present.has(source)) forget(source, state);
+    },
+    idOf: (source) => trackedOf(source).id,
+    selected: (source) => {
+      const state = tracked.get(source);
+      if (state?.surface === undefined) return;
+      input({ _tag: 'Surface', source: state.id, hand: handOf(source), ...state.surface });
+    },
+    sticks: () => {
+      const axesOf = (hand: XrHand): readonly [number, number] => {
+        for (const [source, state] of tracked) if (source.handedness === hand) return state.axes;
+        return [0, 0];
+      };
+      return { left: axesOf('left'), right: axesOf('right') };
+    },
+    stop: () => {
+      for (const [source, state] of tracked) forget(source, state);
+    },
+  };
+};

package/src/dom/xrSpaces.ts

@@ -0,0 +1,287 @@
+/**
+ * What a session tracks for the scene's description, each frame: where every space a
+ * group follows is (`group({ follow })`), the anchors the scene placed
+ * (`xr({ anchors })`), and the planes the session detected (`xr({ planes: true })`).
+ *
+ * Behavioural reference: pmndrs/xr at `0e1acd8`: `space.ts` `createGetXRSpaceMatrix` (an
+ * object on a space takes the space's pose in the reference space each frame, and none
+ * while the frame has no pose for it), `anchor.ts` `requestXRAnchor` (`frame.createAnchor`
+ * with a rigid transform in the origin's reference space), `store.ts` `updateSession` (the
+ * frame's `detectedPlanes` and `detectedMeshes` read each frame, passed on when the set
+ * changes), `plane.ts` (a plane is made again once it changes) and `mesh.ts` (a detected
+ * mesh's geometry built from its `vertices` and `indices`, again when they change).
+ *
+ * @module
+ */
+import {
+  type BodyPose,
+  type Vec3,
+  type Xr,
+  type XrAnchor,
+  type XrInput,
+  type XrMesh,
+  xrMeshGeometryId,
+  type XrPlane,
+  type XrSpace,
+} from '@opsydyn/effect-three';
+import { BufferAttribute, BufferGeometry, Euler, Quaternion } from 'three';
+
+/** Places the scene's following groups where `locate` finds their spaces. */
+export type Follow = (locate: (space: XrSpace) => BodyPose | undefined) => void;
+
+/** Lends a geometry to the scene's store under `id`; returns a function that withdraws it. */
+export type LendGeometry = (id: string, geometry: BufferGeometry) => () => void;
+
+export type XrSpaces = {
+  /** Brings anchors and planes up to date in this frame, then places the following groups. */
+  readonly frame: (frame: XRFrame, space: XRReferenceSpace) => void;
+  /** Ends tracking: anchors are deleted, and every following group is hidden. */
+  readonly stop: () => void;
+};
+
+const turn = new Quaternion();
+const angles = new Euler();
+
+const poseOf = (pose: XRPose | null | undefined): BodyPose | undefined => {
+  if (pose === null || pose === undefined) return undefined;
+  const { position: p, orientation: o } = pose.transform;
+  return { position: [p.x, p.y, p.z], quaternion: [o.x, o.y, o.z, o.w] };
+};
+
+const sameVec3 = (a: Vec3, b: Vec3): boolean => a.every((value, i) => value === b[i]);
+
+const sameAnchor = (a: XrAnchor, b: XrAnchor): boolean =>
+  sameVec3(a.position, b.position) && sameVec3(a.rotation, b.rotation);
+
+/** An anchor's place as a rigid transform: its position, its Euler rotation turned. */
+const transformOf = ({ position: [x, y, z], rotation }: XrAnchor): XRRigidTransform => {
+  turn.setFromEuler(angles.fromArray([...rotation]));
+  return new XRRigidTransform({ x, y, z }, { x: turn.x, y: turn.y, z: turn.z, w: turn.w });
+};
+
+/** A plane as the scene's data: its pose in the scene, its outline in its own space. */
+const planeOf = (id: string, plane: XRPlane, pose: BodyPose): XrPlane => {
+  angles.setFromQuaternion(turn.fromArray([...pose.quaternion]));
+  return {
+    id,
+    orientation: plane.orientation,
+    label: plane.semanticLabel ?? '',
+    position: pose.position,
+    rotation: [angles.x, angles.y, angles.z],
+    polygon: plane.polygon.map((point): Vec3 => [point.x, point.y, point.z]),
+  };
+};
+
+/** A plane's report in a few characters, to tell when one changes. */
+const signatureOf = (plane: XrPlane): string =>
+  [plane.id, plane.orientation, plane.label, ...plane.position, ...plane.rotation]
+    .concat(plane.polygon.flat())
+    .join(',');
+
+/** A detected mesh's report in a few characters, to tell when one changes. */
+const meshSignatureOf = (mesh: XrMesh): string =>
+  [mesh.id, mesh.label, ...mesh.position, ...mesh.rotation].join(',');
+
+/** A detected mesh's geometry, as pmndrs/xr's `updateXRMeshGeometry` builds it. */
+const meshGeometryOf = (mesh: XRMesh): BufferGeometry => {
+  const geometry = new BufferGeometry();
+  geometry.setIndex(new BufferAttribute(mesh.indices, 1));
+  geometry.setAttribute('position', new BufferAttribute(mesh.vertices, 3));
+  geometry.computeVertexNormals();
+  return geometry;
+};
+
+/** A detected mesh's lent geometry: what it was built from, and how to take it back. */
+type Lent = {
+  readonly vertices: Float32Array;
+  readonly indices: Uint32Array;
+  readonly geometry: BufferGeometry;
+  readonly withdraw: () => void;
+};
+
+const withdrawLent = (lent: Lent): void => {
+  lent.withdraw();
+  lent.geometry.dispose();
+};
+
+type Made = { readonly spec: XrAnchor; anchor: XRAnchor | undefined };
+
+/**
+ * Tracks the spaces `session` can locate for the description `settings()`, placing its
+ * following groups with `follow` and reporting detected planes to `input`.
+ */
+export const trackSpaces = (
+  session: XRSession,
+  settings: () => Xr | null,
+  follow: Follow,
+  input: (input: XrInput) => void,
+  lend: LendGeometry,
+): XrSpaces => {
+  const anchors = new Map<string, Made>();
+  const planeIds = new WeakMap<XRPlane, string>();
+  const planes = new Map<string, XRPlane>();
+  let nextPlane = 0;
+  /** The planes last reported. */
+  let reported: string | undefined;
+  const meshIds = new WeakMap<XRMesh, string>();
+  const meshes = new Map<string, XRMesh>();
+  const lentMeshes = new Map<string, Lent>();
+  let nextMesh = 0;
+  let reportedMeshes: string | undefined;
+
+  /** Anchors made, made again where they moved, and deleted where they went. */
+  const syncAnchors = (frame: XRFrame, space: XRReferenceSpace): void => {
+    const wanted = settings()?.anchors ?? [];
+    const seen = new Set<string>();
+    for (const spec of wanted) {
+      seen.add(spec.id);
+      const made = anchors.get(spec.id);
+      if (made !== undefined && sameAnchor(made.spec, spec)) continue;
+      made?.anchor?.delete();
+      const entry: Made = { spec, anchor: undefined };
+      anchors.set(spec.id, entry);
+      // Refused where the session lacks anchors (they are optional): never found, then.
+      void frame.createAnchor?.(transformOf(spec), space).then(
+        (anchor) => {
+          if (anchors.get(spec.id) === entry) entry.anchor = anchor;
+          else anchor.delete();
+        },
+        () => undefined,
+      );
+    }
+    for (const [id, made] of anchors) {
+      if (seen.has(id)) continue;
+      made.anchor?.delete();
+      anchors.delete(id);
+    }
+  };
+
+  /**
+   * Reports the detected planes when what is reported changes: one found or lost,
+   * reshaped, or seen from where the player has moved to. (Compared by content, not
+   * `lastChangedTime`, which some runtimes move on every frame.)
+   */
+  const syncPlanes = (frame: XRFrame, space: XRReferenceSpace): void => {
+    planes.clear();
+    if (settings()?.planes !== true || frame.detectedPlanes === undefined) return;
+    const found: Array<XrPlane> = [];
+    for (const plane of frame.detectedPlanes) {
+      const id = planeIds.get(plane) ?? `plane-${nextPlane++}`;
+      planeIds.set(plane, id);
+      planes.set(id, plane);
+      const pose = poseOf(frame.getPose(plane.planeSpace, space));
+      if (pose !== undefined) found.push(planeOf(id, plane, pose));
+    }
+    const now = found.map(signatureOf).join(' ');
+    if (now === reported) return;
+    reported = now;
+    input({ _tag: 'Planes', planes: found });
+  };
+
+  /** Lends each detected mesh's geometry, again when its vertices change; takes back the lost. */
+  const lendMesh = (id: string, mesh: XRMesh): void => {
+    const lent = lentMeshes.get(id);
+    // Runtimes hand over new arrays when a mesh changes (IWER moves `lastChangedTime` every
+    // frame, keeping them): rebuild only then.
+    if (lent?.vertices === mesh.vertices && lent.indices === mesh.indices) return;
+    if (lent !== undefined) withdrawLent(lent);
+    const geometry = meshGeometryOf(mesh);
+    lentMeshes.set(id, {
+      vertices: mesh.vertices,
+      indices: mesh.indices,
+      geometry,
+      withdraw: lend(xrMeshGeometryId(id), geometry),
+    });
+  };
+
+  /** Reports the detected meshes when what is reported changes, and lends their geometry. */
+  const syncMeshes = (frame: XRFrame, space: XRReferenceSpace): void => {
+    meshes.clear();
+    if (settings()?.meshes === true && frame.detectedMeshes !== undefined) {
+      const found: Array<XrMesh> = [];
+      for (const mesh of frame.detectedMeshes) {
+        const id = meshIds.get(mesh) ?? `mesh-${nextMesh++}`;
+        meshIds.set(mesh, id);
+        meshes.set(id, mesh);
+        lendMesh(id, mesh);
+        const pose = poseOf(frame.getPose(mesh.meshSpace, space));
+        if (pose !== undefined) {
+          angles.setFromQuaternion(turn.fromArray([...pose.quaternion]));
+          found.push({
+            id,
+            label: mesh.semanticLabel ?? '',
+            position: pose.position,
+            rotation: [angles.x, angles.y, angles.z],
+          });
+        }
+      }
+      const now = found.map(meshSignatureOf).join(' ');
+      if (now !== reportedMeshes) {
+        reportedMeshes = now;
+        input({ _tag: 'Meshes', meshes: found });
+      }
+    }
+    for (const [id, lent] of lentMeshes) {
+      if (meshes.has(id)) continue;
+      withdrawLent(lent);
+      lentMeshes.delete(id);
+    }
+  };
+
+  const sourceOf = (hand: string, tracked: boolean): XRInputSource | undefined => {
+    for (const source of session.inputSources) {
+      if (source.handedness === hand && (source.hand !== undefined) === tracked) return source;
+    }
+    return undefined;
+  };
+
+  const locateIn =
+    (frame: XRFrame, space: XRReferenceSpace) =>
+    (target: XrSpace): BodyPose | undefined => {
+      switch (target._tag) {
+        case 'Head':
+          return poseOf(frame.getViewerPose(space));
+        case 'Joint': {
+          const joint = sourceOf(target.hand, true)?.hand?.get(target.joint);
+          return joint === undefined ? undefined : poseOf(frame.getJointPose?.(joint, space));
+        }
+        case 'Controller': {
+          const source = sourceOf(target.hand, false);
+          const located = target.space === 'grip' ? source?.gripSpace : source?.targetRaySpace;
+          return located === undefined ? undefined : poseOf(frame.getPose(located, space));
+        }
+        case 'Anchor': {
+          const anchor = anchors.get(target.id)?.anchor;
+          return anchor === undefined
+            ? undefined
+            : poseOf(frame.getPose(anchor.anchorSpace, space));
+        }
+        case 'Plane': {
+          const plane = planes.get(target.id);
+          return plane === undefined ? undefined : poseOf(frame.getPose(plane.planeSpace, space));
+        }
+        case 'Mesh': {
+          const mesh = meshes.get(target.id);
+          return mesh === undefined ? undefined : poseOf(frame.getPose(mesh.meshSpace, space));
+        }
+      }
+    };
+
+  return {
+    frame: (frame, space) => {
+      syncAnchors(frame, space);
+      syncPlanes(frame, space);
+      syncMeshes(frame, space);
+      follow(locateIn(frame, space));
+    },
+    stop: () => {
+      for (const made of anchors.values()) made.anchor?.delete();
+      anchors.clear();
+      planes.clear();
+      meshes.clear();
+      for (const lent of lentMeshes.values()) withdrawLent(lent);
+      lentMeshes.clear();
+      follow(() => undefined);
+    },
+  };
+};

package/src/dom/xrTarget.ts

@@ -0,0 +1,71 @@
+/**
+ * A mounted scene as an immersive session target: its frames handed to the session while
+ * it presents, and the session's start and end dispatched as `scene-xr` events.
+ *
+ * @module
+ */
+import type { GatedFrames, SceneEvent, Xr, XrInput } from '@opsydyn/effect-three';
+import type { Object3D } from 'three';
+
+import type { Latch } from './latch.ts';
+import type { XrMode, XrTarget } from './xrHub.ts';
+import type { Follow, LendGeometry } from './xrSpaces.ts';
+
+/**
+ * The page's frames for a scene: open while it is visible and no session presents it
+ * (a session brings its own frames, as React Three Fiber's loop stands aside).
+ */
+export const createFrameGate = (frames: GatedFrames) => {
+  let visible = true;
+  let presenting = false;
+  const apply = (): void => frames.setOpen(visible && !presenting);
+  return {
+    setVisible: (next: boolean): void => {
+      visible = next;
+      apply();
+    },
+    setPresenting: (next: boolean): void => {
+      presenting = next;
+      apply();
+    },
+  };
+};
+
+export type FrameGate = ReturnType<typeof createFrameGate>;
+
+/** The `scene-xr` event: the mode presenting, or `null` when the session ended. */
+export const dispatchXrSession = (element: Element, live: Latch, mode: XrMode | null): void => {
+  if (live.isOpen()) element.dispatchEvent(new CustomEvent('scene-xr', { detail: { mode } }));
+};
+
+/** A scene as a target for the page's immersive sessions. */
+export const xrTarget = (scene: {
+  readonly element: Element;
+  readonly canvas: HTMLCanvasElement;
+  readonly live: Latch;
+  readonly gate: FrameGate;
+  readonly settings: () => Xr | null;
+  readonly draw: () => void;
+  readonly scene: Object3D;
+  readonly follow: Follow;
+  readonly lend: LendGeometry;
+  readonly input: (input: XrInput) => ReadonlyArray<SceneEvent>;
+}): XrTarget => ({
+  canvas: scene.canvas,
+  element: scene.element,
+  follow: scene.follow,
+  lend: scene.lend,
+  settings: scene.settings,
+  draw: scene.draw,
+  scene: scene.scene,
+  // Dropped while time travel pauses the scene, as pointer input is.
+  input: (input) => {
+    if (scene.live.isOpen()) scene.input(input);
+  },
+  presenting: (mode) => {
+    scene.gate.setPresenting(mode !== null);
+    // Back on the page's frames: draw once, as React Three Fiber invalidates on session end.
+    if (mode === null) scene.draw();
+    dispatchXrSession(scene.element, scene.live, mode);
+  },
+});