# OpenSpec Change: enterprise-gaming-r3f-vehicle

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

---

## Summary

Deliver `@suaveplan/r3f-vehicle` on the genesis branch from scratch at enterprise quality. The package provides React Three Fiber vehicle rendering and controller integration: a `Vehicle` component that drives a Three.js mesh from physics state provided by `@suaveplan/vehicle-physics`, animated wheel joints, chassis lean, suspension travel visualization, headlight beams, exhaust particles, and skid-mark decals. `useVehicle()` exposes throttle/brake/steer inputs and vehicle telemetry. Genesis adds 100% coverage and Storybook stories.

---

## Available workspace deps

`@suaveplan/vehicle-physics`, `@suaveplan/controller`, `@suaveplan/error`, `@suaveplan/types`, react, `@react-three/fiber`, `@react-three/drei`, three.

---

## Public API surface

```ts
interface VehicleProps {
  physicsRef: VehiclePhysicsRef
  chassisModel: THREE.Object3D
  wheelModels: THREE.Object3D[]
  enableSkidMarks?: boolean
  enableExhaust?: boolean
  enableHeadlights?: boolean
}

function Vehicle(props: VehicleProps): JSX.Element
function VehicleCamera(props: VehicleCameraProps): JSX.Element
// follows vehicle with spring arm, configurable offset

function useVehicle(): VehicleContext
// throttle, brake, steer, telemetry (speed, rpm, gear)
```

---

## File layout

```text
gaming/devices/r3f-vehicle/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    hooks/use-vehicle.ts + md + test
    components/
      Vehicle/ (tsx + md + test + stories + index)
      VehicleCamera/ (tsx + md + test + stories + index)
  tests/integration.test.ts
```