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

OpenSpec Change: enterprise-gaming-r3f-environment

• Change ID: enterprise-gaming-r3f-environment
• Package: @suaveplan/r3f-environment
• Category: gaming/scene
• Target path: gaming/scene/r3f-environment
• Status: PROPOSED
• Date: 2026-04-24
• Reference spec: /mnt/s/web/suaveplan/enterprise/r3f-environment.md

---

Summary

Deliver @suaveplan/r3f-environment on the genesis branch from scratch at enterprise quality. The package provides skybox, HDR environment maps, and lighting presets for React Three Fiber. An Environment component accepts a preset name or HDR URL and sets up @react-three/drei's Environment with PMREM generation; a procedural Sky component renders sun disc and atmosphere scattering; a LightingPreset component configures ambient + directional lights from @suaveplan/day-night's LightKeyframe. Genesis adds structured errors, and 100% coverage.

---

Available workspace deps

@suaveplan/error, @suaveplan/day-night, react, @react-three/fiber, @react-three/drei, three.

---

Public API surface

function Environment(props: EnvironmentProps): JSX.Element
// preset | hdriUrl, background, blur

function Sky(props: SkyProps): JSX.Element
// sunPosition, turbidity, rayleigh, mieCoefficient, elevation, azimuth

function LightingPreset(props: LightingPresetProps): JSX.Element
// keyframe or auto from DayNightClock

function useEnvironment(): EnvironmentCon```text

---

## File layout

```text
gaming/scene/r3f-environment/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    presets/index.ts    # named preset configs
    components/
      Environment/ (tsx + md + test + stories + index)
      Sky/ (tsx + md + test + stories + index)
      LightingPreset/ (tsx + md + test + stories + index)
    hooks/use-environment.ts + md + test
  tests/integration.test.ts