# OpenSpec Change: enterprise-gaming-r3f-xr

- **Change ID**: enterprise-gaming-r3f-xr
- **Package**: `@suaveplan/r3f-xr`
- **Category**: gaming/devices
- **Target path**: `gaming/devices/r3f-xr`
- **Status**: PROPOSED
- **Date**: 2026-04-24

---

## Summary

Deliver `@suaveplan/r3f-xr` on the genesis branch from scratch at enterprise quality. The package provides WebXR/VR/AR integration for React Three Fiber: `XRProvider` initializing the WebXR session, `useXR` hook (session type, referenceSpace, frame), `XRController` components for left/right hand meshes with ray pointer and grip pose, `HandTracking` with 25-joint skeleton rendering, `XRButton` for session entry/exit, and `TeleportTarget` for locomotion. Builds on `@react-three/xr` primitives with structured errors from `@suaveplan/error`. Genesis adds 100% coverage and Storybook stories.

---

## Available workspace deps

`@suaveplan/error`, `@suaveplan/types`, react, `@react-three/fiber`, `@react-three/drei`, `@react-three/xr`, three.

---

## Public API surface

```ts
type XRSessionMode = 'immersive-vr' | 'immersive-ar' | 'inline'

function XRProvider(props: XRProviderProps): JSX.Element
// sessionMode, referenceSpace, children

function XRController(props: XRControllerProps): JSX.Element
// hand: 'left' | 'right', showRay, showGrip

function HandTracking(props: HandTrackingProps): JSX.Element
// hand: 'left' | 'right', showJoints, showMesh

function XRButton(props: XRButtonProps): JSX.Element
// sessionMode, onSessionStart, onSessionEnd

function TeleportTarget(props: TeleportTargetProps): JSX.Element
// onTeleport(position: THREE.Vector3)

function useXR(): XRContext
// session, sessionMode, referenceSpace, isPresenting, frame
```

---

## File layout

```text
gaming/devices/r3f-xr/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    context/xr-provider.tsx + md + test
    hooks/use-xr.ts + md + test
    components/
      XRController/ (tsx + md + test + stories + index)
      HandTracking/ (tsx + md + test + stories + index)
      XRButton/ (tsx + md + test + stories + index)
      TeleportTarget/ (tsx + md + test + stories + index)
  tests/integration.test.ts
```