Initial Commit
This commit is contained in:
97
openspec/archive/2026-05-12-r3f-networking/proposal.md
Normal file
97
openspec/archive/2026-05-12-r3f-networking/proposal.md
Normal file
@@ -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.
|
||||
76
openspec/archive/2026-05-12-r3f-networking/tasks.md
Normal file
76
openspec/archive/2026-05-12-r3f-networking/tasks.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# Tasks — r3f-networking
|
||||
|
||||
## Phase 1: Scaffold
|
||||
|
||||
- [ ] 1.1 Create `packages/r3f/r3f-networking/` with feature-module layout.
|
||||
- [ ] 1.2 `package.json` at `0.1.0`, R3F-tier (peer-deps on `react`, `three`, `@react-three/fiber`).
|
||||
- [ ] 1.3 Test config + browser environment via `createTestConfig()`.
|
||||
- [ ] 1.4 `tests/dep-graph.test.ts`.
|
||||
|
||||
## Phase 2: Audit upstream layout
|
||||
|
||||
- [ ] 2.1 Read `../suaveplan/packages/three/r3f-networking/src/` end-to-end.
|
||||
- [ ] 2.2 Populate parity table with concrete file → capability mapping.
|
||||
|
||||
## Phase 3: Types + errors
|
||||
|
||||
- [ ] 3.1 Port public types + sibling `.md`.
|
||||
- [ ] 3.2 `defineCodes("R3F_NET", [...])`: `SNAPSHOT_OUT_OF_ORDER`, `PEER_DROPPED`, `PREDICTION_DIVERGED`, `INVALID_OPTIONS`.
|
||||
- [ ] 3.3 Zod schemas for snapshot frames + public options.
|
||||
|
||||
## Phase 4: Interpolation subsystem
|
||||
|
||||
- [ ] 4.1 Port frame-loop smoothing for remote-peer transforms.
|
||||
- [ ] 4.2 Backed by injectable `Clock` from `@suaveplan/types`.
|
||||
- [ ] 4.3 Property test: interpolation monotonicity.
|
||||
|
||||
## Phase 5: Prediction + reconciliation
|
||||
|
||||
- [ ] 5.1 Port local input application.
|
||||
- [ ] 5.2 Reconciliation FSM via `@suaveplan/fsm`.
|
||||
- [ ] 5.3 Property test: divergence detection + convergence on reconcile.
|
||||
|
||||
## Phase 6: Snapshot diffing
|
||||
|
||||
- [ ] 6.1 Wire `@suaveplan/diff` for RFC-6902 patches between snapshots.
|
||||
- [ ] 6.2 Wire-format encoding via `@suaveplan/serialize`.
|
||||
- [ ] 6.3 Property test: round-trip equivalence.
|
||||
|
||||
## Phase 7: React + R3F components
|
||||
|
||||
- [ ] 7.1 `useNetworkedTransform` hook.
|
||||
- [ ] 7.2 `useNetworkedEntity` hook.
|
||||
- [ ] 7.3 `useNetworkPredict` hook.
|
||||
- [ ] 7.4 `<NetworkProvider>` context.
|
||||
- [ ] 7.5 `<NetworkedMesh>` and friends.
|
||||
- [ ] 7.6 Storybook stories per component (default + playground + variants).
|
||||
|
||||
## Phase 8: Observability
|
||||
|
||||
- [ ] 8.1 Histograms `r3f_net.snapshot_dispatch_ms`, `prediction_divergence`.
|
||||
- [ ] 8.2 Counters `snapshots_total{outcome}`.
|
||||
- [ ] 8.3 Bus emissions for join/leave/snapshot.
|
||||
|
||||
## Phase 9: Tests + docs
|
||||
|
||||
- [ ] 9.1 Unit tests via `@suaveplan/testing/runner` + `@suaveplan/testing-dom`.
|
||||
- [ ] 9.2 Playwright E2E: 2-client scene over `network-transport-webrtc` via `@suaveplan/testing-e2e`.
|
||||
- [ ] 9.3 100/100/100/100 coverage gate.
|
||||
- [ ] 9.4 Sibling `.md` per `.ts` impl file.
|
||||
- [ ] 9.5 Root `README.md`.
|
||||
|
||||
## Phase 10: Verification
|
||||
|
||||
- [ ] 10.1 `bunx turbo lint typecheck test --filter=@suaveplan/r3f-networking` green.
|
||||
- [ ] 10.2 `bunx turbo test:coverage --filter=@suaveplan/r3f-networking` 100/100/100/100.
|
||||
- [ ] 10.3 `bun run docs:check` green.
|
||||
- [ ] 10.4 Stories cover every component.
|
||||
- [ ] 10.5 `MANIFEST.md` regen.
|
||||
- [ ] 10.6 `STATUS.md` row flipped.
|
||||
|
||||
## Pre-archive checklist
|
||||
|
||||
- [ ] Row 1 — Phase 10 green.
|
||||
- [ ] Row 2 — Playwright E2E passes.
|
||||
- [ ] Row 3 — `openspec/specs/r3f-networking/spec.md` written.
|
||||
- [ ] Row 4 — Folder archived.
|
||||
Reference in New Issue
Block a user