CLAUDE.md#

Tips for future agents working in this repo. It borrows the p2p techniques of the sibling project commonview — read that first; this file only covers what is different here.

Architecture#

src/p2p/
  identity.ts  schnorr keypair; pubkey hex = peer ID  — ported from commonview
  nostr.ts     minimal relay client + topic scheme    — ported (adds event-id dedup)
  peer.ts      WebRTC wrapper: media tracks + a control data channel
  network.ts   the heart: presence roster + the call state machine
  settings.ts  shared per-call settings: types, quality presets, validators
src/App.tsx    join form, roster, ring/accept UI, video views

Key design decisions#

• No auto-connect. Unlike commonview (which meshes every peer), WebRTC is only brought up after an explicit call-request → call-accept handshake; getUserMedia is also deferred until then. All pre-call messaging rides on nostr per-peer topics.
• One call at a time. A second incoming ring is auto-declined with busy: true. Glare (both users call each other) is treated as mutual acceptance.
• Ephemeral events need retries. The caller re-publishes its ring every 4 s (the Nostr class dedupes by event id on the receiving side); a callee in connecting answers a re-ring by re-sending call-accept. Ring and connect phases both time out at 45 s.
• Deterministic initiator. The smaller peer ID creates the offer, same as commonview — no perfect-negotiation glare handling. Both sides add their tracks before signaling starts so one offer/answer round covers all media.
• Screen share = track swap. getDisplayMedia + RTCRtpSender.replaceTrack replaces the camera track in place (screen instead of camera, not alongside). Same-kind replacement avoids renegotiation, which the one-offer design cannot do — never addTrack mid-call.
• Shared call settings ride the control channel. One settings object per call (reset each call), editable by either side; sync is per-key last-writer-wins via {t:'set', key, value, rev} — a same-rev tie resolves to the smaller peer ID's value on both sides. The video-quality presets map to RTCRtpSender.setParameters caps (maxBitrate / scaleResolutionDownBy / maxFramerate), which each side applies to its OWN sender — live, no renegotiation. While screen sharing, resolution downscaling is skipped (downscaled text is unreadable) and degradationPreference is maintain-resolution; caps are re-derived on every share start/stop.
• Mute is per-party, NOT a shared setting. Each side owns its own flags — no revision counters, the ordered control channel makes last-sent win. Toggling track.enabled sends silence/black without renegotiation; the other side is told via {t:'mute', audio, video} and shows badges. The notice carries the EFFECTIVE outgoing video state: while screen sharing the screen is always live, so a muted camera is latent until the share ends (share start/stop re-sends the notice).

Testing#

npm run dev, then open two browsers (identity is per-browser-profile via localStorage, so two tabs in one profile are the SAME peer — use a private window or second browser). npm run build type-checks (tsc -b) and bundles.