# Qurmmius XR Bridge

## Purpose

The bridge is the reliable PSVR2 path for EraWeaver and future Qurmmius products. It is a **native Windows companion**, not a WebXR clone or a browser polyfill:

1. The companion connects to the PSVR2 PC adapter through the SteamVR/OpenXR runtime.
2. A loopback-only health and session channel reports approved capabilities to the Qurmmius site.
3. EraWeaver starts its normal, user-gesture-gated WebXR session when the browser reports support.
4. If WebXR is unavailable, the scene keeps its desktop walkable preview; no fake headset state is shown.

The browser cannot create an immersive headset session when its runtime does not expose WebXR. A JavaScript “clone” would only make the UI look connected, so this project intentionally uses a native companion boundary instead.

## Works today

1. Install the official PlayStation VR2 PC app and PC adapter updates, then start SteamVR.
2. Set SteamVR as the active OpenXR runtime if another runtime is selected.
3. Open the EraWeaver scene in a normal desktop browser on the same Windows PC. Do not use the Codex embedded browser for the headset check.
4. Open **Universal Connectivity Bridge** → **Check local companion**. The page checks `http://127.0.0.1:8788/health` and reports browser capability, OpenXR runtime state, companion state, and consent state.
5. Run the scene's **Enter VR** button only after the browser reports WebXR support. If it remains unavailable, use the desktop preview and record the named browser/device result in Product hardware acceptance.

For repeatable startup on Windows, right-click `scripts/start-psvr2-session.ps1` and choose **Run with PowerShell**. It performs a SteamVR/OpenXR runtime check and opens the bridge check plus the EraWeaver scene in an isolated Chrome XR profile with Chromium's `--force-webxr-runtime=openxr` switch. The temporary profile contains no saved Qurmmius credentials.

## Native companion contract

The future companion should expose these loopback endpoints only after the user starts it:

`GET /health`

```json
{
  "service": "qurmmius-xr-bridge",
  "version": "0.2.0-runtime-probe",
  "openxr": "ready",
  "steamvr": "ready",
  "psvr2": "runtime_detected",
  "capabilities": ["openxr-runtime"],
  "consentRequired": true
}
```

The Windows helper now performs a real OpenXR instance + HMD-system probe. A
`runtime_detected` value confirms that the runtime exposed an HMD system, but
does not claim that a PSVR2 session or pose/controller stream has started.

`POST /session` creates a short-lived, single-use session nonce after the user explicitly approves the fields to share. A future WebSocket/WebRTC channel may carry pose and controller samples using that nonce. The web app must treat all samples as read-only coaching input.

## Boundaries

- Loopback or user-approved local network only; no public listener by default.
- Explicit consent before a session and before each new capability.
- No MAC-address discovery, console memory access, anti-cheat bypass, account automation, force-feedback writes, or game-file writes.
- No claims of device compatibility until a real PSVR2 + adapter + named browser run is recorded.
- The companion must fail closed when SteamVR, the OpenXR runtime, or the adapter is missing.

## Acceptance run

Record one result on `/hardware-testing/` for each combination:

- PSVR2 + official PC adapter + SteamVR + desktop browser
- a supported wheel/controller
- the EraWeaver scene's WebXR entry and desktop fallback
- reconnect after SteamVR restart
- disconnect/reconnect of the headset and controller

The native OpenXR session/rendering implementation and physical acceptance run remain external work. Until those are complete, the bridge page is a transparent runtime probe and setup guide rather than a claim that a headset session is active.