# CLAUDE.md

Tips for future agents working in this repo. It combines the p2p techniques of
the sibling projects `commonview` (auto-connecting mesh) and `commoncall`
(WebRTC media, settings, screen share) — read those first; this file only
covers what is different here.

## Architecture

```
src/p2p/
  identity.ts  schnorr keypair; pubkey hex = peer ID     — ported from commoncall
  nostr.ts     minimal relay client + topic scheme        — ported (roomTopic takes a room ID)
  peer.ts      WebRTC wrapper: media + control channel    — ported (replaceTrack generalized to audio|video)
  settings.ts  shared ROOM settings, quality presets      — default quality is 'medium', not 'auto'
  turn.ts      optional TURN: build-time endpoint, credential fetch, sanitizers
  network.ts   the heart: rooms, presence, mesh, media, settings sync, relay sharing
src/App.tsx    landing form (light) + in-room view (dark), video grid with
               click-to-spotlight (gallery ↔ one big tile + filmstrip; Esc or
               click again to return), control bar, chat panel (side panel on
               wide screens, overlay ≤700px, unread badge)
worker/        Cloudflare Worker that mints TURN credentials — deployed
               separately (wrangler), NOT part of `npm run build`
```

## Key design decisions

- **Rooms, no registry.** The room ID is any string (whitespace stripped,
  exact otherwise, case-sensitive); `roomTopic` hashes it into the nostr
  presence topic. The URL hash holds the room (`#<encoded-room>`) so the
  address bar is the invite link.
- **Auto-mesh, no consent handshake.** Unlike commoncall, entering the room IS
  the consent: on every presence announcement, `maybeConnect` brings up a
  `Peer` (initiator = smaller peer ID, commonview's stalled-connection retry
  at 15 s). All of commoncall's call-request/accept machinery is gone.
- **Muted by default; placeholder tracks.** getUserMedia runs at entry but
  tracks start `enabled = false`. Every participant ALWAYS carries exactly one
  audio + one video track (denied/missing devices get a silent
  AudioContext-destination track / black canvas-capture track), so
  offer/answer stays symmetric and the one-offer, no-renegotiation design
  holds. Unmuting without a real device retries getUserMedia and upgrades the
  placeholder via `replaceTrack` on every connection. getUserMedia failures
  surface a cause-specific notice (`mediaErrorMessage`: permission vs
  not-found vs device-busy, error name included) both at join and on retry —
  on Linux, a camera held by another browser fails with NotReadableError,
  which is NOT a permissions problem. The combined audio+video request fails
  as a whole in that case, so `acquireMedia` retries each kind separately.
- **Soft cap of 8** (`MAX_PARTICIPANTS`). A peer already holding 7 connections
  answers an unknown peer's announcement/offer with `{t:'room-full'}` on the
  newcomer's topic instead of connecting; a newcomer with zero connections
  that receives room-full tears down and shows a notice. Two simultaneous
  joiners racing for the last slot can briefly exceed the cap — accepted.
- **Settings are room-wide, multi-party LWW.** One entry per key in
  `settingsMeta` (`{rev, by}`); changes broadcast `{t:'set', key, value, rev,
  by}` to all peers (complete graph — no relaying), late joiners get every
  entry inside each peer's `hello`, and a same-rev tie is won by the SMALLER
  setter ID. Default quality is `medium` — so quality caps are applied to each
  sender on connect (`applyVideoParamsTo`, with one delayed retry because
  encodings may not exist right at 'connected'), not only on change.
- **Mute is per-participant, NOT a shared setting** — same as commoncall: own
  flags, `{t:'mute'}` notices, `track.enabled` toggling, and the notice
  carries the EFFECTIVE outgoing video state (screen share overrides camera
  mute). Remote participants are assumed muted until told otherwise.
- **Screen share = track swap on every connection.** `getDisplayMedia` +
  `replaceTrack` per peer; a peer that joins mid-share gets the screen track
  from `outgoingStream()`. Same-kind replacement avoids renegotiation — never
  addTrack mid-connection.
- **Chat is ephemeral and never relayed.** `{t:'chat', text}` broadcasts on
  the control channels; every message arrives directly from its author over a
  channel established via signed signaling, so authorship needs no extra
  crypto. There is deliberately NO history replay for late joiners — replay
  would mean peers relaying others' messages, which a malicious peer could
  fabricate; adding history requires signing each message. Log capped at 500,
  messages at 2000 chars. Join/left lines are derived locally: hello carries a
  self-reported `joinedAt`, and a peer whose join predates ours gets no
  "joined" line on first sight (they were already here) — but `chatSeen`
  ensures a blip-reconnect logs "joined" to match its "left". Links: only
  http(s) URLs matched by `withLinks` become anchors (target=_blank,
  rel=noopener noreferrer); never linkify other schemes.
- **TURN is optional, token-gated, and shared room-wide.** `VITE_TURN_ENDPOINT`
  (build time) points at `worker/`; unset ⇒ the whole feature is hidden and
  `BASE_ICE_SERVERS` (STUN + openrelay) is used, as before. One participant
  enters a token on the landing form, `mintIce` exchanges it for an
  `{iceServers, expiresAt}` and it is broadcast as `{t:'ice'}` — on `connect`
  to each peer, and again on refresh (`scheduleIceRefresh`, 5 min before
  expiry). Peers `adoptIce` it; our own credentials always beat a shared one
  (only we can refresh them), otherwise the later `expiresAt` wins. Share the
  CREDENTIAL, never the token — the token never leaves the browser it was
  typed into. **Peer-supplied ICE is untrusted:** `sanitizeIceConfig` bounds
  and scheme-checks it before it reaches `RTCPeerConnection`.
- **Credentials can't help the connection that carried them.** `Peer` takes
  `iceServers` at construction and never renegotiates them, so a peer learns
  credentials from the first peer it reaches and uses them for the NEXT
  connection. Stalled pairs recover via the existing `CONNECT_RETRY_MS` path,
  which calls `iceServers()` afresh — deliberately no proactive teardown on
  adoption, since rebuilding a half-open pair out of step with the other side
  is exactly what that retry already handles.
- **Cleanup is join-generation-guarded.** `joinSeq` is bumped on every
  join/leave; async work (getUserMedia, topic hashing, display capture)
  re-checks it after each await. `leave()` unsubscribes topics, stops all
  tracks, closes the AudioContext, and resets settings to defaults.

## Testing

`npm run dev`, then open the room in 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. Let the user test multi-party media in real browsers;
don't try to automate camera/mic flows.

The Worker CAN be tested without a browser: `cd worker && cp .dev.vars.example
.dev.vars && npm run dev`, then curl it. With the example values, token checks
work (`goodtoken` passes, anything else 401s) and the upstream call 404s, which
surfaces as a 502 — enough to cover auth, CORS and method handling. `cd worker
&& npx tsc --noEmit` type-checks it; the root `tsc -b` does not (it only
includes `src`). The sanitizers in `turn.ts` are pure and testable under node
via `npx esbuild src/p2p/turn.ts --format=esm --define:import.meta.env='{}'`.
Whether a relay is actually USED can only be seen in a real browser
(chrome://webrtc-internals, candidate pair type `relay`).