# OpenSpec Change: enterprise-gaming-r3f-performance

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

---

## Summary

Deliver `@suaveplan/r3f-performance` on the genesis branch from scratch at enterprise quality. The package provides performance monitoring and optimization utilities for React Three Fiber. A `PerformanceMonitor` component tracks FPS, draw calls, triangle count, GPU memory, and frame budget; a `PerformanceHUD` overlay renders the stats panel; an `AdaptiveQuality` component automatically reduces quality settings (shadow map size, particle count, LOD distance) when FPS drops below threshold. A `usePerformance()` hook exposes current metrics. Genesis adds structured errors, OTel metrics export, and 100% coverage.

---

## Available workspace deps

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

---

## Public API surface

```ts
function PerformanceMonitor(props: PerformanceMonitorProps): JSX.Element
// onDrop, onRecover, flipflops, bounds

function PerformanceHUD(props: PerformanceHUDProps): JSX.Element
// visible, position

function AdaptiveQuality(props: AdaptiveQualityProps): JSX.Element
// minFps, targetFps, qualityLevels

function usePerformance(): PerformanceMetrics
// fps, drawCalls, triangles, frameTime, gpuMemoryMb
```

---

## File layout

```text
gaming/effects/r3f-performance/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    core/metrics-collector/ (ts + md + types + test + index)
    components/
      PerformanceMonitor/ (tsx + md + test + stories + index)
      PerformanceHUD/ (tsx + md + test + stories + index)
      AdaptiveQuality/ (tsx + md + test + stories + index)
    hooks/use-performance.ts + md + test
  tests/integration.test.ts
```