# OpenSpec Change: enterprise-gaming-r3f-water

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

---

## Summary

Deliver `@suaveplan/r3f-water` on the genesis branch from scratch at enterprise quality. The package provides water rendering and ocean simulation for React Three Fiber. A tiled plane mesh samples a Gerstner wave sum for animated surface displacement; a custom shader handles Fresnel reflections, refractive depth coloring, foam near shorelines (depth texture comparison), and specular highlights. An `Ocean` component wraps a configurable wave parameter set; a `WaterPlane` component handles simpler inland water. Genesis adds Zod wave config schemas, structured errors, and 100% coverage.

---

## Available workspace deps

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

---

## Public API surface

```ts
function Ocean(props: OceanProps): JSX.Element
// waves: GerstnerWave[], tileSize, color, foamColor, windDirection

function WaterPlane(props: WaterPlaneProps): JSX.Element
// width, height, color, opacity, reflectionMap

interface GerstnerWave {
  direction: [number, number]
  amplitude: number
  steepness: number
  wavelength: number
}

function useWaterHeight(x: number, z: number, time: number): number
```

---

## File layout

```text
gaming/scene/r3f-water/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts / constants/index.ts
    types/common.ts + md
    shaders/
      ocean.vert.ts + ocean.frag.ts
    utils/
      gerstner.ts + md + test
    components/
      Ocean/ (tsx + md + test + stories + index)
      WaterPlane/ (tsx + md + test + stories + index)
    hooks/use-water-height.ts + md + test
  tests/integration.test.ts
```