# OpenSpec Change: enterprise-gaming-r3f-lod

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

---

## Summary

Deliver `@suaveplan/r3f-lod` on the genesis branch from scratch at enterprise quality. The package provides level-of-detail management for React Three Fiber. An `LodGroup` component accepts child meshes paired with distance thresholds; the `LodManager` evaluates camera distance each frame and swaps the active mesh; a `BillboardLod` fallback renders a sprite at maximum distance. Supports hysteresis bands to prevent LOD flickering. Genesis adds structured errors, OTel active-lod-level histogram, and 100% coverage.

---

## Available workspace deps

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

---

## Public API surface

```ts
function LodGroup(props: LodGroupProps): JSX.Element
// levels: { distance: number; children: ReactNode }[]
// hysteresis?: number

function BillboardLod(props: BillboardLodProps): JSX.Element
// atlasTexture, frameIndex, sizeAttenuation

function useLod(ref: RefObject<Object3D>): number   // current LOD level
```

---

## File layout

```text
gaming/effects/r3f-lod/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    core/lod-manager/ (ts + md + types + test + index)
    components/
      LodGroup/ (tsx + md + test + stories + index)
      BillboardLod/ (tsx + md + test + stories + index)
    hooks/use-lod.ts + md + test
  tests/integration.test.ts
```