docs: v0.7.6 stage channels — Phase 30, STAGE_CHANNELS.md, parity update

Document P2P stage speaker roles, gossip RPC 43, platform API, and UI. Mark Phase 30 and P3-5 complete in PLATFORM_ROADMAP. Add pearcord-stage to Gitea org table and module map. Update PEARCORD_PARITY voice row. Co-authored-by: Cursor <[email protected]>
2026-05-21 21:50:07 -04:00
parent 8668761be1
commit 65f47d73e4
4 changed files with 64 additions and 3 deletions
@@ -114,6 +114,7 @@ git remote -v
 | `pearcord-settings` | User appearance prefs + `USER_PREFS_UPDATE` gossip |
 | `pearcord-step-up` | Local step-up PIN for sensitive actions |
 | `pearcord-forum` | Forum post tags + palette helpers |
+| `pearcord-stage` | Stage channel speaker roles + `STAGE_SPEAKER_UPDATE` gossip |
 | `pearcord-device-sync` | `pcdv_` multi-device pairing |
 | `pearcord-emoji` | Guild emoji registry + `EMOJI_UPSERT` gossip |
 | `pearcord-sync` | Planned Autobase bridge |
@@ -4,7 +4,7 @@ Gap analysis between **Pearcord** (P2P Pear app) and a typical **centralized cha

 > This is the only doc that compares against an external reference product. All other docs use Pearcord naming only.

-## Summary (v0.7.5)
+## Summary (v0.7.6)

 | Area | Reference product | Pearcord | Gap |
 |------|-------------------|----------|-----|
@@ -12,7 +12,7 @@ Gap analysis between **Pearcord** (P2P Pear app) and a typical **centralized cha
 | Servers | Hosted guilds | P2P guild topic + local DB + **public discovery mesh** | No curated global index (fully P2P topic) |
 | Text chat | Full | … **announcement** + **forum** channels, tags, forum slowmode, threads, typing, **guild emoji** | automod, animated stickers |
 | DMs | E2E optional | … **sidebar previews**, **group DM (3–10)**, read-on-open | Full E2E group vault |
-| Voice/video | WebRTC SFU | Voice join/leave + **P2P protomux media plane** (ping/RTT, mute) | Opus/udx live audio (P3-3 follow-up) |
+| Voice/video | WebRTC SFU | Voice + **stage** (audience/speaker, request to speak) + **P2P protomux media** | Opus/udx live audio (P3-3 follow-up) |
 | Moderation | Roles, bans, automod | Kick, ban, timeout, roles UI, slowmode, audit+gossip; local step-up PIN for kick/ban/bot tokens | automod |
 | Account security | 2FA, session revoke | Local step-up PIN (`pearcord-step-up`, 5 min session) | Cloud 2FA, OAuth |
 | Friends | Friend list + requests | **P2P contacts** + presence + **custom status** on contacts mesh | Activity feed, rich presence games |
@@ -61,7 +61,7 @@ Track implementation status here. Update checkboxes as phases land.
 | P3-2 | Voice channels join/leave | [x] |
 | P3-3 | WebRTC / udx-native media path | [~] protomux data plane + ping RTT; udx optional |
 | P3-4 | Screen share | [ ] |
-| P3-5 | Stage channels | [ ] |
+| P3-5 | Stage channels | [x] audience/speaker roles + request to speak (v0.7.6) |

 ---

@@ -141,6 +141,7 @@ See [PEARCORD_PARITY.md](./PEARCORD_PARITY.md) for full gap analysis and Phases
 | `pearcord-settings` | User appearance prefs + P2P sync |
 | `pearcord-step-up` | Local step-up PIN (kick/ban/bot token gate) |
 | `pearcord-forum` | Forum post tags + palette on channel topic |
+| `pearcord-stage` | Stage speaker roles (audience/speaker/pending) |

 ---

@@ -233,6 +234,16 @@ When completing work, change `[ ]` → `[x]` and add a one-line note under **Cha

 ---

+### Phase 30 — Stage channels (v0.7.6)
+
+| ID | Item | Status |
+|----|------|--------|
+| P30-1 | `CHANNEL_TYPES.STAGE` + `pearcord-stage` module | [x] |
+| P30-2 | `STAGE_SPEAKER_UPDATE` gossip + join/request/approve APIs | [x] |
+| P30-3 | Stage bar UI + smoke-stage + STAGE_CHANNELS.md | [x] |
+
+---
+
 ### Phase 29 — Announcement channels (v0.7.5)

 | ID | Item | Status |
@@ -376,6 +387,7 @@ When completing work, change `[ ]` → `[x]` and add a one-line note under **Cha

 ### Changelog

+- **2026-05-21** — v0.7.6: stage channels (`pearcord-stage`, STAGE_SPEAKER_UPDATE gossip, request/approve speakers, stage bar UI, smoke-stage, STAGE_CHANNELS.md).
 - **2026-05-21** — v0.7.5: announcement channels (mod-only post), UI bar, smoke-announcement, ANNOUNCEMENT_CHANNELS.md.
 - **2026-05-21** — v0.7.4: forum channel slowmode on new posts, smoke-forum-slowmode.
 - **2026-05-21** — v0.7.3: forum post tags (`pearcord-forum`, palette, filter, FORUM_POST_TAGS gossip, smoke-forum-tags).
@@ -0,0 +1,48 @@
+# Stage channels (v0.7.6+)
+
+**Stage** channels combine voice occupancy (`pearcord-voice`) with speaker roles (`pearcord-stage`). Members join as **audience** (muted). They may **request to speak**; moderators with `MANAGE_CHANNELS` approve them as **speakers** (unmuted).
+
+## Channel type
+
+| Field | Value |
+|-------|--------|
+| `type` | `stage` |
+
+Create via **Create channel → Stage** or `createChannel({ type: 'stage' })`.
+
+## Roles (P2P gossip)
+
+| Role | Meaning |
+|------|---------|
+| `audience` | Joined stage, muted by default |
+| `pending` | Requested to speak, awaiting mod |
+| `speaker` | Approved to speak (may unmute) |
+
+Gossip: `STAGE_SPEAKER_UPDATE` (RPC 43) — `{ guildId, channelId, userId, role, updatedAt?, requestedAt?, cleared? }`.
+
+## Platform API
+
+| Method | Description |
+|--------|-------------|
+| `joinStageChannel(channelId)` | Voice join + initial role (mods → speaker) |
+| `requestStageSpeak()` | Audience → pending |
+| `approveStageSpeaker(userId)` | Mod promotes to speaker |
+| `demoteStageSpeaker(userId)` | Mod returns user to audience |
+
+View fields: `stageRolesByChannel`, `myStageRole`, `stagePendingRequests` (mods only).
+
+## UI
+
+- Sidebar **Stage Channels** section (🎙)
+- **Stage bar**: role pill, request/invite buttons, mute (speakers only), leave
+- Voice bar hidden while in a stage channel
+
+## Tests
+
+```bash
+cd apps/pearcord
+npm run test:stage   # STAGE_SMOKE_OK
+npm run test:boot
+```
+
+See [VOICE.md](./VOICE.md) for occupancy and media plane.