Sessions and lifecycle

Everything else on this site depends on this section. A WebXR page does not simply switch to 3D — it negotiates. It asks for a session of a particular mode, lists the features it needs, and waits for a user gesture and a permission decision. Only then does it get an XRSession, and only then do the other APIs mean anything.

The four pages here follow a session from the request through to the frame. The first is the negotiation itself: what `immersive-vr` and `immersive-ar` mean to the runtime, and how to find out which of the features you asked for you actually got. Reference spaces answers the question the session deliberately leaves open, which is where (0, 0, 0) sits in the real room; the same line of code puts a table on the floor on one device and at chest height on another, and the difference is not in the scene. Session visibility covers the state where your content is still on screen but the input is going somewhere else. Blend modes is what the session hands back on the far side: whether your content replaces the room or sits on top of it, and how much the page is allowed to know about which it got.

The recurring mistake in this area is treating a session as a boolean: XR on, XR off. A session has a mode, a set of granted features that may be fewer than the ones you asked for, a reference space whose origin the runtime can move underneath you, and a blend mode that changes what your rendering should even look like. Code written against the boolean version works on the developer's headset and breaks on everyone else's.

In this section

1. 01WebXR sessionsA WebXR session is the handshake that hands your page a headset: one call takes over both displays, and the reference space you pick decides where the floor is.
2. 02Reference spacesEvery position you write in a WebXR app is relative to something. That something is the reference space, and it is the one piece of the coordinate system your code never states out loud.
3. 03Session visibilityThe user can still see your frames while a system menu sits on top of them. visibilityState tells you that, and your code has to treat it as its own case.
4. 04Environment blend modesOne property — session.environmentBlendMode — tells you whether the user can see the real room behind your content, and on one of its three values black is not a colour but a hole in your scene.

Read these in order

Start with sessions. It establishes the vocabulary — session mode, feature descriptors, reference space, viewer pose — that every other page on this site uses without redefining.

Reference spaces comes second because every coordinate on this site is expressed in one, and the pages that follow stop saying so out loud. It is also the page that explains the single most common first bug: content that is the right size and shape and is simply in the wrong place.

Session visibility third. It is short, and it is the one lifecycle detail that is easy to get wrong for months without noticing, because the failure only appears while the user is looking at a system menu rather than at your application.

Blend modes last. It answers the question that shows up immediately after your first AR session starts: why does the background render black on one device and show the room on another?