suaveplan/openspec/changes/enterprise-gaming-r3f-physics-rapier/proposal.md

OpenSpec Change: enterprise-gaming-r3f-physics-rapier

• Change ID: enterprise-gaming-r3f-physics-rapier
• Package: @suaveplan/r3f-physics-rapier
• Category: gaming/physics
• Target path: gaming/physics/r3f-physics-rapier
• Status: PROPOSED
• Date: 2026-04-24

---

Summary

Deliver @suaveplan/r3f-physics-rapier on the genesis branch from scratch at enterprise quality. The package provides a Rapier physics engine integration for React Three Fiber, implementing the PhysicsBackend interface from @suaveplan/r3f-physics-core. It wraps @dimforge/rapier3d-compat (WASM); a RapierPhysicsProvider initialises the WASM module asynchronously and provides a RAPIER.World; RigidBody, Collider, and Joint components wrap the corresponding Rapier APIs; useRapierContext() exposes the raw RAPIER.World for advanced usage. Genesis adds structured errors, and 100% coverage.

---

Available workspace deps

@suaveplan/error, @suaveplan/r3f-physics-core, react, @react-three/fiber, @dimforge/rapier3d-compat, three.

---

Public API surface

function RapierPhysicsProvider(props: RapierProviderProps): JSX.Element
function RigidBody(props: RigidBodyProps): JSX.Element
function Collider(props: ColliderProps): JSX.Element
function useRapierContext(): RapierCon```text

---

## File layout

```text
gaming/physics/r3f-physics-rapier/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    context/rapier-provider.tsx + md + test
    hooks/use-rapier-context.ts + md + test
    components/
      RigidBody/ (tsx + md + test + stories + index)
      Collider/ (tsx + md + test + stories + index)
  tests/integration.test.ts