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

bunx turbo lint typecheck test --filter=@suaveplan/r3f-networking green.
bunx turbo test:coverage --filter=@suaveplan/r3f-networking 100/100/100/100.
bun run docs:check green.
Every component has Storybook stories (default + playground + variants).
Playwright E2E: 2-client multiplayer scene round-trips state through network-transport-webrtc.
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.

4.6 KiB Raw Permalink Blame History