my_site/docs/superpowers/plans/2026-04-03-transfer-simple-peer-integration.md

Transfer Simple Peer Integration Implementation Plan

For agentic workers: REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Replace the hand-rolled online transfer WebRTC peer wiring with simple-peer while preserving the current pickup-code flow, backend signaling APIs, and offline transfer mode.

Architecture: Keep the existing product boundaries: Spring Boot remains a dumb signaling relay and session store, while the React frontend owns online-transfer peer creation and file streaming. Instead of manually managing RTCPeerConnection, ICE candidates, and SDP state across sender/receiver pages, introduce a thin simple-peer adapter that serializes peer signals through the existing /api/transfer/sessions/{id}/signals endpoints and reuses the current transfer control/data protocol.

Tech Stack: Vite 6, React 19, TypeScript, node:test, simple-peer, existing Spring Boot transfer signaling API.

---

Task 1: Lock the new peer adapter contract with failing tests

Files:

• Create: front/src/lib/transfer-peer.test.ts

• Create: front/src/lib/transfer-peer.ts

• Step 1: Write the failing test

Add tests that assert:

• local simple-peer signal events serialize into a backend-friendly payload

• incoming backend signal payloads are routed back into the peer instance

• peer connection lifecycle maps to app-friendly callbacks without exposing raw browser SDP/ICE handling to pages

• Step 2: Run test to verify it fails

Run: cd front && npm run test -- src/lib/transfer-peer.test.ts

• Step 3: Write minimal implementation

Create a focused adapter around simple-peer with:

• sender/receiver construction

• signal event forwarding

• connect, data, close, and error callbacks

• send helpers used by the existing transfer pages

• Step 4: Run test to verify it passes

Run: cd front && npm run test -- src/lib/transfer-peer.test.ts

Task 2: Replace online sender wiring in the desktop and mobile transfer pages

Files:

• Modify: front/src/pages/Transfer.tsx

• Modify: front/src/mobile-pages/MobileTransfer.tsx

• Modify: front/src/lib/transfer.ts

• Step 1: Write the failing test

Add or extend focused tests for the new signaling payload shape if needed so the sender path no longer depends on manual offer/answer/ICE branches.

• Step 2: Run test to verify it fails

Run: cd front && npm run test

• Step 3: Write minimal implementation

Use the adapter in both sender pages:

• build an initiator peer instead of a raw RTCPeerConnection

• post serialized peer signals through the existing backend endpoint

• keep the current file manifest and binary chunk sending protocol

• Step 4: Run test to verify it passes

Run: cd front && npm run test

Task 3: Replace online receiver wiring while keeping the current receive UX

Files:

• Modify: front/src/pages/TransferReceive.tsx

• Step 1: Write the failing test

Add or update tests around receiver signal handling and data delivery if gaps remain after Task 2.

• Step 2: Run test to verify it fails

Run: cd front && npm run test

• Step 3: Write minimal implementation

Use the adapter in the receiver page:

• build a non-initiator peer

• feed backend-delivered signals into it

• keep the current control messages, archive flow, and netdisk save flow unchanged

• Step 4: Run test to verify it passes

Run: cd front && npm run test

Task 4: Verification and release

Files:

• Modify if required by validation failures: front/package.json, front/package-lock.json

• Step 1: Install the dependency

Run: cd front && npm install simple-peer @types/simple-peer

• Step 2: Run frontend tests

Run: cd front && npm run test

• Step 3: Run frontend typecheck

Run: cd front && npm run lint

• Step 4: Run frontend build

Run: cd front && npm run build

• Step 5: Publish the frontend

Run: node scripts/deploy-front-oss.mjs