# OpenSpec Change: r3f-networking

- **Change ID**: r3f-networking
- **Package**: `@suaveplan/r3f-networking`
- **Category**: r3f (three / React-Three-Fiber tier)
- **Target path**: `packages/r3f/r3f-networking`
- **Status**: PROPOSED
- **Date**: 2026-05-11
- **Parent**: `network-transport-family` (2026-05-11) — Wave 7
- **Migration source**: `../suaveplan/packages/three/r3f-networking` + `../suaveplan/enterprise/r3f-networking.md`

---

## Summary

Migrate `@suaveplan/r3f-networking` into genesis as the top-of-stack multiplayer state-synchronisation library for React-Three-Fiber scenes. Provides interpolation (smoothing remote-peer transforms across the local frame loop), client-side prediction (locally apply input → reconcile against server state), entity-snapshot diffing, and snapshot interpolation between authoritative state ticks. Last package of the network migration plan because every concrete transport + discovery option from Waves 1-6 must exist for this layer to be useful.

---

## Why this is last

- Sits at the top of the network stack — depends on `@suaveplan/network` ✅ + at least one shipped transport.
- R3F-tier — pulls `three`, `@react-three/fiber`, optional `@react-three/drei`.
- Game-engine-shaped surface (interp / prediction / snapshot diff) — the toughest test cases.

---

## Current-state audit

Upstream coverage: 99.60%.

Upstream layout (`../suaveplan/packages/three/r3f-networking/src/`): TBD at execution time — read `../suaveplan/enterprise/r3f-networking.md` for the full inventory.

Expected subsystems:

- **Interpolation** — frame-loop smoothing of remote peer transforms
- **Prediction** — local input applied immediately, reconciled against authoritative snapshots
- **Snapshot diffing** — minimal-payload deltas between authoritative ticks
- **Snapshot interpolation** — render between two confirmed snapshots
- **React hooks** — `useNetworkedTransform`, `useNetworkedEntity`, `useNetworkPredict`
- **R3F components** — `<NetworkedMesh>`, `<NetworkProvider>`, etc.

---

## Parity Checklist (preliminary)

| Capability | Upstream | Migrated | Notes |
|---|---|---|---|
| Interpolation | ✅ | ✅ | Backed by injectable `Clock` from `@suaveplan/types`. |
| Client-side prediction | ✅ | ✅ | |
| Server-reconciliation FSM | ✅ | ✅ | Composes `@suaveplan/fsm` ✅. |
| Snapshot diffing | ✅ | ✅ | Re-use `@suaveplan/diff` ✅ for RFC-6902 patches. |
| Snapshot interpolation | ✅ | ✅ | |
| React hooks | ✅ | ✅ | |
| R3F components | ✅ | ✅ | |
| Transport abstraction | ✅ | ⬆️ | Accepts any `Transport` from `@suaveplan/network` — no hard-coded WebRTC. |
| Structured errors | 🚫 | ⬆️ | `defineCodes("R3F_NET", [...])`: `SNAPSHOT_OUT_OF_ORDER`, `PEER_DROPPED`, `PREDICTION_DIVERGED`, `INVALID_OPTIONS`. |
| Zod boundary validation | 🚫 | ⬆️ | Every public option + every wire snapshot frame. |
| OTel instrumentation | 🚫 | ⬆️ | Histograms `r3f_net.snapshot_dispatch_ms`, `prediction_divergence`, counters `snapshots_total{outcome}`. |
| `export *` barrels | check | ⬆️ | §6a. |
| Test-runner imports | direct vitest | ⬆️ | §7. |
| 100% test coverage | 🚫 (99.60%) | ⬆️ | 100/100/100/100. |
| Storybook stories | ✅ | ✅ | Required — every R3F component needs default + playground + variants per CLAUDE.md. |
| Property tests | 🚫 | ⬆️ | fast-check: interpolation monotonicity, prediction-reconcile convergence, snapshot diff round-trip. |

---

## Available workspace deps on genesis

- `@suaveplan/network` ✅
- `@suaveplan/network-transport-webrtc` ✅ (canonical real-time transport)
- `@suaveplan/diff` ✅
- `@suaveplan/fsm` ✅
- `@suaveplan/timing` ✅
- `@suaveplan/serialize` ✅
- `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events` ✅
- `@suaveplan/testing-dom` ✅ + `@suaveplan/testing-e2e` ✅
- External: `three`, `@react-three/fiber`, `react`, `react-dom` — already cataloged.

---

## Acceptance gate

1. `bunx turbo lint typecheck test --filter=@suaveplan/r3f-networking` green.
2. `bunx turbo test:coverage --filter=@suaveplan/r3f-networking` 100/100/100/100.
3. `bun run docs:check` green.
4. Every component has Storybook stories (default + playground + variants).
5. Playwright E2E: 2-client multiplayer scene round-trips state through `network-transport-webrtc`.
6. `STATUS.md` row flipped.

---

## Out of scope

- Voice / video transport over R3F (separate `@suaveplan/r3f-voice` if needed).
- Server-authoritative simulation engine (consumers supply their own; this package handles the wire format).
- Specific game-genre logic (FPS netcode, MMO area-of-interest) — left to consumers.