98 lines
4.6 KiB
Markdown
98 lines
4.6 KiB
Markdown
# 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.
|