Initial Commit

openspec/archive/2026-05-12-r3f-networking/proposal.md

@@ -0,0 +1,97 @@
+# 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.