# OpenSpec Change: enterprise-gaming-r3f-world

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

---

## Summary

Deliver `@suaveplan/r3f-world` on the genesis branch from scratch at enterprise quality. The package provides world management and scene composition for React Three Fiber. A `WorldManager` orchestrates scene layers (terrain, vegetation, water, buildings, NPCs, effects) in dependency order; a `SceneGraph` maintains a flat registry of mounted scene nodes with bounding volumes; a `WorldProvider` React context exposes the manager to all child R3F components. `useWorld()` accesses the context for scene queries and entity registration. Genesis adds structured errors, OTel scene-node gauge, and 100% coverage.

---

## Available workspace deps

`@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/spatial-hash`, `@suaveplan/ecs`, react, `@react-three/fiber`, `@react-three/drei`, three.

---

## Public API surface

```ts
function WorldProvider(props: WorldProviderProps): JSX.Element
function useWorld(): WorldContext

interface WorldContext {
  register(node: SceneNode): () => void
  query(bounds: AABB3): SceneNode[]
  readonly nodeCount: number
}

// Components
function World(props: WorldProps): JSX.Element   // root scene orchestrator
```

---

## File layout

```text
gaming/scene/r3f-world/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts / constants/index.ts
    types/common.ts + md
    core/
      world-manager/ (ts + md + types + test + index)
      scene-graph/ (ts + md + types + test + index)
    context/
      world-provider.tsx + md + test
      use-world.ts + md + test
    components/
      World/ (tsx + md + test + stories + index)
  tests/integration.test.ts
```