suaveplan/openspec/changes/enterprise-gaming-r3f-xr/proposal.md

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

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

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