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

OpenSpec Change: enterprise-gaming-r3f-camera

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

---

Summary

Deliver @suaveplan/r3f-camera on the genesis branch from scratch at enterprise quality. The package provides advanced camera controls for React Three Fiber: first-person, third-person follow, cinematic dolly/orbit, top-down, and isometric modes. Each mode is a composable CameraRig that drives the Three.js camera; smooth transitions between modes use spring interpolation; a CameraShake component applies procedural trauma-based shake. useCamera() exposes the active rig and allows programmatic transitions. Genesis adds structured errors, and 100% coverage.

---

Available workspace deps

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

---

Public API surface

type CameraMode = 'first-person' | 'third-person' | 'cinematic' | 'top-down' | 'isometric'

function CameraRig(props: CameraRigProps): JSX.Element
// mode, target, offset, smoothing, fov

function CameraShake(props: CameraShakeProps): JSX.Element
// trauma, decay, frequency, maxAngle, maxOffset

function useCamera(): CameraContext
// mode, setMode(mode), addTrauma(amount), lookAt(target)

---

File layout

gaming/devices/r3f-camera/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    rigs/
      first-person/ (ts + md + test + index)
      third-person/ (ts + md + test + index)
      top-down/ (ts + md + test + index)
    context/camera-provider.tsx + md + test
    hooks/use-camera.ts + md + test
    components/
      CameraRig/ (tsx + md + test + stories + index)
      CameraShake/ (tsx + md + test + stories + index)
  tests/integration.test.ts