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

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

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

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