docs: Phase 62 contacts mesh polish (v0.8.27)

Document mux-wire migration, friend topic subscriptions, meshLive stats,
live smoke test, and UI updates. Roadmap Phase 62 complete; next: role
emoji manage UI.

Co-authored-by: Cursor <[email protected]>

AUTOMATED_TESTING.md

@@ -35,6 +35,7 @@ Pearcord validates itself without manual QA.
 | `npm run test:slash` | Slash commands + gossip (`SLASH_SMOKE_OK`) |
 | `npm run test:bot-events` | Bot event fanout (`BOT_EVENTS_SMOKE_OK`) |
 | `npm run test:contacts` | Friend request gossip + accept (`CONTACTS_SMOKE_OK`) |
+| `npm run test:contacts-mesh-live` | Live contacts mesh request/accept/presence (`CONTACTS_MESH_LIVE_SMOKE_OK`) |
 | `npm run test:bot-limits` | Slash/bot rate limits (`BOT_LIMITS_SMOKE_OK`) |
 | `npm run test:bot-install` | Signed install tokens + gossip (`BOT_INSTALL_SMOKE_OK`) |
 | `npm run test:bot-runner` | Headless runner !ping (`BOT_RUNNER_SMOKE_OK`) |

CONTACTS.md

@@ -12,6 +12,8 @@ pearcord:contacts:{userId}
 
 Outgoing requests temporarily join the peer’s topic (`client: true`) and gossip `CONTACT_REQUEST`. Accept/decline/remove use the same protomux channel (`pearcord-contacts-v1`).
 
+**v0.8.27:** Protomux v3 wire via `pearcord-drive/mux-wire`. Accepted friends keep persistent topic subscriptions (`_syncFriendTopicLinks`) so presence and cosmetics sync live. See [CONTACTS_MESH_LIVE.md](./CONTACTS_MESH_LIVE.md).
+
 ## RPC gossip
 
 | RPC | Direction | Payload |
@@ -56,7 +58,8 @@ Contact row:
 DM home sidebar:
 
 - **Friends** section with pending accept/decline, accepted friends (opens DM), **status dot** (online/idle/dnd), **+** add friend modal
-- Members pane shows pending/outgoing counts and contacts mesh peer count
+- Members pane shows pending/outgoing counts, contacts mesh peer count, and **Live P2P** when `stats.meshLive`
+- DM sidebar lists outgoing pending with cancel (remove-contact)
 
 ## IPC
 
@@ -75,6 +78,7 @@ Blocked users cannot send you friend requests (`ingestRequest` returns null). Th
 
 ```bash
 cd apps/pearcord && npm run test:contacts
+cd apps/pearcord && npm run test:contacts-mesh-live   # CONTACTS_MESH_LIVE_SMOKE_OK
 cd apps/pearcord && npm run test:friend-presence   # FRIEND_PRESENCE_SMOKE_OK
 cd apps/pearcord && npm run test:custom-status    # CUSTOM_STATUS_SMOKE_OK
 cd apps/pearcord && npm run test:block-contacts

CONTACTS_MESH_LIVE.md

@@ -0,0 +1,31 @@
+# Contacts mesh live (v0.8.27)
+
+Friend requests, accepts, and presence run over **protomux v3** (`pearcord-drive/mux-wire`) on the per-user contacts topic.
+
+## Topic wiring
+
+Each user hosts `pearcord:contacts:{userId}` (server + client). After friendship:
+
+- **`_syncFriendTopicLinks`** joins each accepted friend’s topic as a persistent client subscription so `PRESENCE_UPDATE` and profile cosmetics reach both sides without ephemeral joins.
+
+Outgoing one-shot gossip (`CONTACT_REQUEST`, etc.) still uses a temporary join to the peer topic when needed.
+
+## Stats
+
+`listContacts().stats`:
+
+| Field | Meaning |
+|-------|---------|
+| `peers` | Open Hyperswarm connections on contacts mesh |
+| `friendTopics` | Subscribed friend contact topics |
+| `meshLive` | `peers > 0` — UI shows **Live P2P** |
+
+## Tests
+
+| Script | Marker |
+|--------|--------|
+| `npm run test:contacts-mesh-live` | `CONTACTS_MESH_LIVE_SMOKE_OK` |
+
+Live smoke: mesh connect → request → accept → `setPresence` + custom status visible to friend without `simulateGossip`.
+
+See [CONTACTS.md](./CONTACTS.md).

PEARCORD_PARITY.md

@@ -141,8 +141,9 @@ Phases **0–2** and **4** are largely complete; **3** (live audio) and **5** (n
 | P59-1 | Server-wide emoji slots UI + boost tiers (v0.8.24) | [x] |
 | P60-1 | Pear attach preview mesh path + `fetchSource` (v0.8.25) | [x] |
 | P61-1 | GUILD_SYNC history on join (v0.8.26) | [x] |
+| P62-1 | Contacts mesh polish — live P2P friends (v0.8.27) | [x] |
 
-**Next tranches:** Contacts mesh polish · role emoji manage UI · discovery sync extensions.
+**Next tranches:** Role emoji manage UI · discovery sync extensions.
 
 When Phase 5 checklist is `[x]`, copy open items here into tracked rows in `PLATFORM_ROADMAP.md`.
 

PLATFORM_ROADMAP.md

@@ -249,6 +249,19 @@ When completing work, change `[ ]` → `[x]` and add a one-line note under **Cha
 
 ---
 
+### Phase 62 — Contacts mesh polish (v0.8.27)
+
+| ID | Item | Status |
+|----|------|--------|
+| P62-1 | Protomux v3 `mux-wire` on contacts mesh | [x] |
+| P62-2 | Persistent friend topic links (`_syncFriendTopicLinks`) | [x] |
+| P62-3 | `stats.meshLive` + UI Live P2P tag + pending-out cancel | [x] |
+| P62-4 | smoke-contacts-mesh-live + CONTACTS_MESH_LIVE.md | [x] |
+
+**Next:** Role emoji manage UI · discovery sync extensions.
+
+---
+
 ### Phase 61 — GUILD_SYNC history on join (v0.8.26)
 
 | ID | Item | Status |
@@ -258,7 +271,7 @@ When completing work, change `[ ]` → `[x]` and add a one-line note under **Cha
 | P61-3 | Push on peer join + remote `MEMBER_JOIN` | [x] |
 | P61-4 | smoke-guild-sync + GUILD_SYNC.md | [x] |
 
-**Next:** Contacts mesh polish · role emoji manage UI · discovery sync extensions.
+**Next:** ~~Contacts mesh polish~~ (Phase 62) · role emoji manage UI · discovery sync extensions.
 
 ---
 
@@ -755,6 +768,7 @@ When completing work, change `[ ]` → `[x]` and add a one-line note under **Cha
 
 ### Changelog
 
+- **2026-05-22** — v0.8.27: contacts mesh polish (mux-wire v3, friend topic subscriptions, live presence smoke, UI Live P2P tag, CONTACTS_MESH_LIVE.md).
 - **2026-05-22** — v0.8.26: GUILD_SYNC history on join (`gossipGuildSync`, peer/member triggers, `test:guild-sync`, GUILD_SYNC.md).
 - **2026-05-22** — v0.8.25: Pear attach preview mesh path (`readAttachmentBytesWithSource`, preview `fetchSource`, UI P2P mesh tag, `test:attachment-preview-mesh`, ATTACHMENT_PREVIEW_MESH.md).
 - **2026-05-22** — v0.8.24: server-wide emoji slots (`pearcord-emoji/slots.js`, boost-tier limits, server settings UI, `test:emoji-slots`, EMOJI_SLOTS.md).