# 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'
  network.ts   the heart: rooms, presence, mesh, media, settings sync
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)
```

## 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.
- **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.