suaveplan/openspec/archive/2026-05-12-r3f-networking/tasks.md

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.