Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
feat(web): finish participant presence states [skip ci]
AAAb1d676e317ab
diff --git a/docs/adr/0002-persistent-protected-rooms.md b/docs/adr/0002-persistent-protected-rooms.mdindex 00cecfe7..ccca3e25 100644--- a/docs/adr/0002-persistent-protected-rooms.md+++ b/docs/adr/0002-persistent-protected-rooms.md@@ -175,9 +175,11 @@ rollback to the old binary stops the service and restores that backup ratherthan retaining dual-schema runtime code.Display names and roster presentation remain a separate change: browser-`localStorage` plus current-room memory only, displayed with at least six-characters of room-scoped `peerId` and extended on collision. Neither enters-SQLite or participates in authorization, routing, or quality decisions.+`localStorage` plus current-room memory only. A unique display name is shown+without an identifier; duplicate names append the shortest room-scoped+`peerId` suffix (at least six characters, extended only when needed). Neither+the name nor suffix enters SQLite or participates in authorization, routing, or+quality decisions.## Consequencesdiff --git a/docs/project-memory.md b/docs/project-memory.mdindex d6168fed..9cc71c70 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -32,7 +32,7 @@ Last updated: 2026-08-21- Flagship media is UDP; HTTPS/WSS stays TLS/TCP; the old release remains rollback-only.- Treat settings as ceilings and degradation as unclassified. Use correlated Host A+B/Viewer C and one-variable evidence; never force AV1, infer by UA, or create a composite score.- Screen audio: peer answers use `stereo=1;maxaveragebitrate=128000`; SFU uses 128 kbps stereo/`forceStereo`, DTX off, RED retained. Other SDP/FEC stays browser-owned; one stream; production proof open; no audio UI; voice separate; Native source-only.-- Presence reports exact active upstream and feeds Host topology; it does not prove media. Status and details stay neutral until local/current media evidence, then label P2P/SFU and actual TURN; append its protocol only from local relay stats. Web Host names stay socket/localStorage-only; Native remains outside the boundary.+- Presence reports active upstream for topology; assignment alone never proves media. A Web SFU Viewer becomes connected only after session-bound first media; track/route/session loss clears it. Status/details stay neutral until current P2P/SFU/TURN evidence. Names stay socket/localStorage-only; Native remains outside.- Do not add scene detection, dynamic-FPS control, or forced AV1 without negotiation, encode, game, CPU/GPU, and sender evidence.- ADR-0002 grant/public access, the v3 room-password migration, and Web Host display names are deployed. Names/presence remain session-only without account or roster tables.@@ -43,14 +43,14 @@ Last updated: 2026-08-21## Current Implementation- The repository is one npm package using Node.js 24, React, TypeScript, Vite, native WebRTC, `ws`, Zod, Vitest, and separate coturn.-- Production is exact `7dd38fc39ce8e91b913b1f45e053c00e0520f3b9`, release `7dd38fc39ce8`, wire `screener-v3`; rollback is `f7d667c4d32d`.+- Production is exact `20cb1bdb2be3c7c254508623fa2bcfbd9a6d61c2`, release `/opt/screener/releases/20cb1bdb2be3`, with deployed Web wire `screener-v3`; rollback is `/opt/screener/releases/7dd38fc39ce8`.- Web keeps one SFU stream, clears unavailable video, exposes evidence-backed routes/transports and paused preview, and drops signals to a grace-retained offline current-edge target. Routing is automatic; entry/nickname UI is live; Native remains source-only.- Web relay is cap2 with one upstream; child3 rejects and no UA/visibility split exists.- Four services are active/running at `NRestarts=0`; local/public health are 200. SQLite v3 has five rooms, SHA-256 `aef724ae52c4107be8ec8791e72f8dcaa11b0ec849fb432d022e2cfb9cfe0974`, owner/mode `screener:screener`/0600.- Production keeps ordinary ICE STUN-only, SFU roots <=2, selected-edge UDP TTL 120, and one pending/answered `peer-selected` attempt per room excluding Host ingress. This rollout ran no browser/media/SFU/TURN/performance canary; earlier exact-`16f6eab` evidence proves active Host ingress only.- Production requires independent `SITE_ACCESS_PASSWORD`: its stateless cookie authorizes creation/Host and code-only Viewer attempts; private grants stay direct, while public/private code entry needs site access alone/plus room password. Env/endpoint/cookie/nginx naming migrated atomically; failures remain neutral; there are no accounts/JWT/session rows. Local `gate:access-privacy` proves fragment isolation, site/grant transport-log absence, and raw room-password SQLite absence; room-password WebSocket/log ingress and live/headful evidence remain open.- Production uses nginx, Node.js 24.19.0, coturn 4.17.2, and LiveKit 1.13.5 on UDP 7882 (TCP fallback off). Ordinary peer ICE receives no TURN; the selected-edge tuple is configured only for the current controller edge, with no credential pre-advertised to ordinary peers. Coturn retains the old authenticated-relay ports. Services are healthy with zero restarts.-- ADR-0005 rejects `PEER_ASSISTED_ROOM_IDS`; `PEER_ASSISTED_MEDIA=true` enables every room and ordinary peers stay STUN-only. Initial or active Host ingress may consume one bound relay-only grant; ready/abort clears it and failure restores peer baseline. Stale room-ID config fails startup; `screener-v3` is the deployed wire.+- ADR-0005 rejects `PEER_ASSISTED_ROOM_IDS`; `PEER_ASSISTED_MEDIA=true` enables every room and ordinary peers stay STUN-only. Initial or active Host ingress may consume one bound relay-only grant; ready/abort clears it and failure restores peer baseline. Stale room-ID config fails startup. This atomic source candidate moves Web and source-only Native from deployed v3 to the single `screener-v4` authentication wire; Native does not subscribe to Web presence.- Defaults are balanced with automatic codec; clarity/fluid and H.264/VP8 remain explicit. Codec is locked during a share. Web SFU uses LiveKit 2.22.0 `q,h`; SFU/UDP and selected-TURN work; BWE, Host A+B and production remain open.- Chrome 151 five-Viewer 720p30 cap2 evidence: Host/relay fanout two; both relay children +80 decoded frames/~1.1 MB; every Viewer decoded; clean stop. Functional only; resource and heterogeneous-network behavior remain open.diff --git a/docs/research/display-name-presence.md b/docs/research/display-name-presence.mdindex c60aecc5..3a2d7659 100644--- a/docs/research/display-name-presence.md+++ b/docs/research/display-name-presence.md@@ -10,4 +10,10 @@ Accessed 2026-08-20. This note records only the browser and Unicode facts that c## Retained design-The browser is the only durable owner of a display-name preference. The signaling server retains the canonical value only on the authenticated socket state and derives an authoritative online snapshot from current connected sessions. Presence is display-only: it neither authorizes nor changes media routing. Web Hosts and Viewers explicitly opt in to the shared participant snapshot; a Native sender does not, so its exact parser receives no new server message or field. Host defaults may be derived from the room-scoped stable client ID, but the value is still local/socket-only.+The browser is the only durable owner of a display-name preference. The signaling server retains the canonical value only on the authenticated socket state and derives an authoritative online snapshot from current connected sessions. Presence is display-only: it neither authorizes nor changes media routing. For Web display, an SFU Viewer entry carries `sfuMediaReady: true` only after first media is bound to its current session, active route revision, and publication generation; absence stays neutral, while track, route, or session loss removes the proof. Web Hosts and Viewers explicitly opt in to the shared participant snapshot; a Native sender does not, so its exact parser receives no new server message or field. Host defaults may be derived from the room-scoped stable client ID, but the value is still local/socket-only.++## Current roster presentation++The live roster uses the display name alone when it is unique in the current room snapshot. When two or more participants use the same name, only those colliding entries append the shortest room-scoped `peerId` suffix that distinguishes them, starting at six characters and extending only for a suffix collision. A suffix collision between different names does not change either label. This is presentation-only; the suffix remains opaque and never participates in authorization, routing, or quality decisions.++Host and Viewer pages consume the same authoritative participant snapshot. The Viewer roster renders only Viewer entries, including the local Viewer, and replaces the whole list on each snapshot so joins, leaves, renames, and reconnections do not require a second client-side membership model.diff --git a/docs/status.md b/docs/status.mdindex 09751914..f7683c3b 100644--- a/docs/status.md+++ b/docs/status.md@@ -4,20 +4,20 @@ Last updated: 2026-08-21## Phase-Production is exact `7dd38fc39ce8e91b913b1f45e053c00e0520f3b9` at `https://share.bonfire.icu`, release `7dd38fc39ce8`, wire `screener-v3`; rollback is `f7d667c4d32d`. SQLite v3/five rooms retains SHA-256 `aef724ae52c4107be8ec8791e72f8dcaa11b0ec849fb432d022e2cfb9cfe0974`, owner/mode `screener:screener`/0600. Four services and local/public health are green.-Ordinary ICE is STUN-only; limits are SFU roots <=2, one `peer-selected` attempt excluding Host ingress, and selected UDP TTL 120. This rollout ran no browser/media/SFU/TURN/performance canary; earlier exact-`16f6eab` Host-ingress proof remains separate.+Production is exact `20cb1bdb2be3c7c254508623fa2bcfbd9a6d61c2` at `https://share.bonfire.icu`, release `20cb1bdb2be3`, wire `screener-v3`; rollback is release `7dd38fc39ce8`. SQLite v3/five rooms keeps SHA-256 `aef724ae52c4107be8ec8791e72f8dcaa11b0ec849fb432d022e2cfb9cfe0974`, owner/mode `screener:screener`/0600. Four services and local/public health are green.+Ordinary ICE is STUN-only; limits are SFU roots <=2, one `peer-selected` attempt excluding Host ingress, and selected UDP TTL 120. No browser/media/SFU/TURN/performance canary ran; exact-`16f6eab` Host-ingress proof is separate.Stable SFU, route/transport truth, preview notice, entry/nickname UI and Web relay cap2 are live. Native is source-only. The controlled production A/B uses browser/LiveKit codec defaults; explicit codec controls are source-complete.## Execution Principle-Parallel flagship work; minimum relevant checks and rollback proof. Research plus target-device/production evidence drives performance decisions; ordinary-PC synthetic runs prove only correctness/interoperability. Active text is current; Git owns history; delete no-consumer layers.+Parallel flagship work; use minimum relevant checks and rollback proof. Target-device/production evidence drives performance decisions; ordinary-PC synthetic runs prove only correctness/interoperability. Git owns history; delete no-consumer layers.## Current Snapshot-- Capture precedes rooms; source/quality changes and AV pause preserve peers. Defaults are balanced and automatic codec; clarity/fluid plus H.264/VP8 stay explicit, with codec locked during a share. Browser degradation and Host SFU A+B remain open.-- Production `screener-v3` admits private fragment grants directly. Code-only Viewers need site access, then public rooms accept the code while private rooms also require their password. `SITE_ACCESS_PASSWORD`, `/api/site-access`, and its cookie are deployed atomically; raw credentials are never stored.-- Source UI uses adjacent nickname editing, distinct site/room prompts, and a shared room-code form. Status and details stay neutral before media proof; current evidence labels green P2P/yellow `SFU fallback`, while relay evidence adds `TURN` plus only a locally observed protocol.-- Native v2 is source-only (memory rooms, 300s reclaim); it follows authenticated direct-child assignments up to two and fails unsupported SFU/selected ingress boundedly.+- Capture precedes rooms; source/quality changes and AV pause preserve peers. Defaults are balanced and automatic codec; clarity/fluid plus H.264/VP8 stay explicit, with codec locked during a share. Browser degradation and Host SFU A+B remain open; pause notice is source-only.+- Deployed `screener-v3` admits private fragment grants directly; code-only Viewers need site access, and private rooms additionally need their password. Credentials remain unstored. This atomic source candidate moves Web and source-only Native authentication together to `screener-v4` for Web-only presence fields.+- Source UI has nickname editing and room entry. Status/details stay neutral before proof. An undeployed SFU-roster candidate carries session-bound first-media truth in presence and clears it on track/route/session loss; P2P/SFU/TURN labels require evidence. Browser proof is open.+- Native v4 is source-only (memory rooms, 300s reclaim); it does not subscribe to Web presence, follows authenticated direct-child assignments up to two, and fails unsupported SFU/selected ingress boundedly.- Production is roots/Web relay <=2; every Viewer has one upstream and rejects child3. One-root healthy-SFU MBB is deployed but media-unverified; capacity `0 -> 1`, multi-root and browser gates remain open. Room `1` is historical; HTTPS/WSS is TLS/TCP.- After an answer, a generation-bound 15s initial-connect deadline enters ICE restart; success/replacement/disposal cancels it. It is deployed but not mobile-verified.- Room `1` C+B reparenting remains uncalibrated. Deployed admission rescue promotes an unassigned relay over the oldest childless zero-capacity Host leaf, with no scores or periodic optimization.diff --git "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md" "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"index e7ea4401..db689d75 100644--- "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"+++ "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"@@ -100,11 +100,11 @@ rotate、revoke 或从 public-watch 切回 private-link 都是当前 Viewer 的Web Host 在 `authenticate` 中显式发送 `viewerPresence: true` capability,Viewer 也可显式订阅同一 participant snapshot;Native sender 不发送,因此继续只收到原有 exact server wire。两端可在 `authenticate.displayName` 发送名称,并以 `set-display-name` 更新当前会话。服务端只向已订阅的 Web participant 发送完整 `viewer-presence` snapshot,列表严格来自当前带 sessionId 的在线参与者,不含五秒媒体恢复 grace 成员;条目用 `role` discriminator 区分 Host/Viewer。加入、离线、会话替换、改名和 active route 改变都会重发快照;该只读广播不调用 connect/reconcile,也不建立任何媒体边。Host 的“在线”Viewer 总数只取 Viewer 条目数;最多两条本机媒体快照只补充当前以 Host 为 active upstream 的连接指标。-每个 presence 条目包含 `role`、`peerId`、`displayName` 和服务端 active assignment 的精确 `upstream`:Host 为 `none`,Viewer 为 `none | peer(peerId) | sfu`。UI 始终展示名称加 peerId 尾部至少六字符短后缀;碰撞时逐字符有界延长至完整 peerId。卡片状态只依据本机连接或当前 Viewer 接收证据显示“已连接”,否则保持中性的“线路分配中”或具体连接状态;active assignment 本身不是连接成功证据。连接详情同样等待当前媒体证据,再显示绿色 `P2P` 或黄色 `SFU fallback`;实际 relay 另附 `TURN`,本地 relay protocol 可见时才显示 `TURN/UDP` 等实际值。独立拓扑按钮可从 authoritative assignment snapshot 展示 Host、实际存在的 SFU 节点及精确上下游,但不把计划线路当作连接成功。peerId 不因此成为授权身份或路由输入;名称、presence 与拓扑视图不改变授权、媒体或路由状态机。+每个 presence 条目包含 `role`、`peerId`、`displayName` 和服务端 active assignment 的精确 `upstream`:Host 为 `none`,Viewer 为 `none | peer(peerId) | sfu`。UI 默认只展示名称;房内出现同名时,仅为同名项追加 peerId 尾部至少六字符短后缀,并只在同名项后缀碰撞时逐字符有界延长至完整 peerId。卡片状态只依据本机连接或当前 Viewer 接收证据显示“已连接”,否则保持中性的“线路分配中”或具体连接状态;active assignment 本身不是连接成功证据。连接详情同样等待当前媒体证据,再显示绿色 `P2P` 或黄色 `SFU fallback`;实际 relay 另附 `TURN`,本地 relay protocol 可见时才显示 `TURN/UDP` 等实际值。独立拓扑按钮可从 authoritative assignment snapshot 展示 Host、实际存在的 SFU 节点及精确上下游,但不把计划线路当作连接成功。peerId 不因此成为授权身份或路由输入;名称、presence 与拓扑视图不改变授权、媒体或路由状态机。## 信令协议-WebSocket 使用无 query/fragment 的同源 `/signal`。upgrade 只记录 site-access cookie 是否有效;连接后五秒内第一条消息必须是 `screener-v3` 的房间级 `authenticate`。Host 消息携带 room、role、内部 Host token 与 clientId,并由 socket state 复核 site access;Web Host 可选发 `viewerPasswordSettings: true` capability,Native v2 不发送且不接收任何密码设置新消息。Viewer 消息携带 room、role、clientId,以及 private room 的 Viewer grant 或当前尝试的房间密码。服务端设置 64 KiB `maxPayload`、关闭 `perMessageDeflate`,并以 ping/pong 清理失效连接。单进程固定限制 2048 条总连接和 256 条未鉴权连接,容量在 upgrade 前预留,超限直接返回 HTTP 503 并销毁 socket。+WebSocket 使用无 query/fragment 的同源 `/signal`。upgrade 只记录 site-access cookie 是否有效;连接后五秒内第一条消息必须是 `screener-v4` 的房间级 `authenticate`。Host 消息携带 room、role、内部 Host token 与 clientId,并由 socket state 复核 site access;Web Host 可选发 `viewerPasswordSettings: true` capability,source-only Native 使用同一 wire 版本但不发送该 capability,也不接收密码设置或 presence 新消息。Viewer 消息携带 room、role、clientId,以及 private room 的 Viewer grant 或当前尝试的房间密码。服务端设置 64 KiB `maxPayload`、关闭 `perMessageDeflate`,并以 ping/pong 清理失效连接。单进程固定限制 2048 条总连接和 256 条未鉴权连接,容量在 upgrade 前预留,超限直接返回 HTTP 503 并销毁 socket。主要消息:@@ -166,7 +166,7 @@ Web 视频端不做视频 SDP munging。`automatic` 不调用 P2P `setCodecPrefe直播中切换来源仍由明确的按钮手势重新调用 `getDisplayMedia()`,不改变房间、host generation 或媒体拓扑。选源取消或失败时继续发送旧流;成功后为每个现有 sender 调用 `replaceTrack()`,健康连接不重新协商。初始 offer 预留 send-only audio transceiver,使音频可以在 `null -> track -> null` 间切换。若某个 peer 的替换或回滚失败,只重建该 peer;新流提交后才停止旧流,并以当前 stream 身份保护旧 track 的迟到 `ended` 事件。统计码率累加器在换源后重置,避免把不同 track 的计数器混算。-直播中切换质量不重新打开选源器:对当前视频 track 调用 `applyConstraints()`,再更新所有现有 sender 的参数;新加入、重建的 relay sender 和启用的 SFU publisher 使用同一权威设置。失败时保留当前分享并给出状态,不以重建整个房间补偿。临时暂停禁用当前 capture stream 的全部音视频 tracks,使远端收到黑画面和静音;房间与连接保持不变,恢复时重新启用同一批 tracks。+直播中切换质量不重新打开选源器:对当前视频 track 调用 `applyConstraints()`,再更新所有现有 sender 的参数;新加入、重建的 relay sender 和启用的 SFU publisher 使用同一权威设置。失败时保留当前分享并给出状态,不以重建整个房间补偿。临时暂停禁用当前 capture stream 的全部音视频 tracks;Host 通过当前 share generation 更新现有 `host-status`,`authenticated` 快照携带当前暂停位,Viewer 在舞台显示“分享者已暂停”。晚加入和信令重连从快照恢复,恢复、停止、新分享或会话替换清除旧状态;不得把 track mute、黑帧或网络停顿推断成主动暂停。房间与连接保持不变,恢复时重新启用同一批 tracks。Host 本地预览直接绑定现有 capture stream,不创建 viewer、`RTCPeerConnection` 或额外媒体边,也不产生 TURN/SFU/应用服务器出口。预览仍可能有本地合成、缩放和 GPU 显示成本;在同一动态场景对预览开/关采集 Host CPU、GPU、encode time 和实际 FPS。只有稳定收益且捕获、编码和远端画面不变时,才把直播后的默认动态预览改为静止缩略图或隐藏并允许按需展开;隐藏预览绝不停止 capture track 或 sender encode。@@ -244,7 +244,7 @@ selected-edge TURN attempt。该 attempt 必须同时绑定 room/share generatioconnection identity;parent 与 child 只为该新 PC 协同重建,Viewer 使用 relay-only配置。pending 超时、失败或代次变化清理 attempt;answer 后 attempt 变为已使用并仅为该 edge 保留信令 owner,直到失败或 generation/session/topology/room cleanup。普通 PC、其他 edge、-Native v2 与 authenticated snapshot 继续 STUN-only。凭据不进入 URL、日志、browser+Source-only Native 与 authenticated snapshot 继续 STUN-only。凭据不进入 URL、日志、browserstorage、room row 或 SQLite。该临时 edge 不改写 active SFU assignment 或另建 route owner;attempt 存续期间@@ -314,10 +314,10 @@ hop 按[低服务器成本媒体路由](./research/low-server-media-routes.md)- 访问入口:未鉴权根路径、`/join` 和 code-only `/r/{code}` 显示“站点访问”与“站点口令”,未知路径只显示“无法访问”。有效 `/r/{code}#v={grant}` 直接进入;其余 Viewer 通过 site access 后,public-watch 进入房间,private room 显示“加入房间”与“房间密码”。已有有效 site-access cookie 不重复显示整站验证;站点口令和房间密码不共享输入值或授权状态。无效、过期、错误密码或满员只显示通用拒绝,不泄露房间存在性或 policy。- 分享者根页面:顶部显示“{分享者显示名} 的屏幕”和房间状态,并在标题旁显示可单独复制的紧凑房间号;Viewer 同一位置显示权威 Host 名称,不再在标题下重复。主区域保持稳定的 16:9 舞台。未发布、已停止或可恢复错误状态时,舞台内以同等尺寸和权重显示“开始分享”和“加入房间”,中间只用“或”与分隔线表达发送/接收;前者直接开始现有分享流程,后者作为 disclosure 在当前舞台内、紧邻触发按钮就地展开共享的房间码表单,提交后才导航到 `/r/{code}`。按钮同步 `aria-expanded`/`aria-controls`,展开后输入获得焦点,DOM 与焦点顺序保持触发器后接表单;窄屏允许表单换到动作行下方,不产生横向滚动。不增加首页、向导或拓扑选择。直播时舞台显示本地预览及独立全屏图标,底部保留停止、同步暂停音视频、质量档位和复制完整邀请链接;页面失焦仅暂停本地 video element,并在舞台提示“本地预览已暂停,分享仍在继续”;媒体暂停则禁用 capture stream 轨道,两者都保留现有连接。- `/join`:保留为可直接访问的回退入口,并复用同一个房间码表单;通过 site access 后只输入正整数房间码并进入 `/r/{code}`。public-watch 直接通过,private room 缺失 grant 时显示当前房间的密码表单。-- `/r/{code}` 观看者:private room 首次解析合法 fragment grant 后立即清理地址栏并直达;仅有 code 时先通过 site access,再按 public/private policy 进入。鉴权后主区域最大化远端视频,标题旁显示可复制的紧凑房间号,顶部保留连接状态,并提供本地音量、静音、全屏和重试控制。+- `/r/{code}` 观看者:private room 首次解析合法 fragment grant 后立即清理地址栏并直达;仅有 code 时先通过 site access,再按 public/private policy 进入。鉴权后主区域最大化远端视频,标题旁显示可复制的紧凑房间号,顶部保留连接状态,并提供本地音量、静音、全屏和重试控制;Host 主动暂停时复用视频舞台遮罩显示“分享者已暂停”,恢复后立即移除。- 移动端:视频保持稳定宽高比,控制与状态移到视频下方,任何文字和按钮不得溢出或遮挡。-两端后续默认显示紧凑在线 roster;Host 与 Viewer 的本机显示名在界面中统一标为“昵称”,默认只读,铅笔按钮紧贴昵称并只切换当前控件的输入、保存和取消,展示仍为名称加 room-scoped `peerId` 短后缀。一个不持久化的“显示连接详情”复选框按页展开媒体方式、传输协议、候选路径、浏览器实际暴露的本地/远端候选地址、codec、RTT、RTP 丢包率、编解码耗时及逐边统计;真实连接失败、音频缺失、持续画质受限和需要用户动作的告警始终可见。显示名/roster 不进入 access credential 或 SQLite。+两端默认显示紧凑在线 roster;Viewer 端复用同一权威 participant snapshot,只列出当前 Viewer(含本机)并在新 snapshot 到达时整体替换,停止分享仅移除已离线 Host,鉴权失效、房间关闭或页面卸载则清空。Host 与 Viewer 的本机显示名在界面中统一标为“昵称”,默认只读,铅笔按钮紧贴昵称并只切换当前控件的输入、保存和取消,唯一名称仅显示名称,重名时才追加 room-scoped `peerId` 短后缀。一个不持久化的“显示连接详情”复选框按页展开媒体方式、传输协议、候选路径、浏览器实际暴露的本地/远端候选地址、codec、RTT、RTP 丢包率、编解码耗时及逐边统计;真实连接失败、音频缺失、持续画质受限和需要用户动作的告警始终可见。显示名/roster 不进入 access credential 或 SQLite。用户可见的非直播状态只使用“已停止分享”(分享端已结束当前发布)、“等待开始分享”(观看端等待发布)、“正在连接”与“正在恢复连接”。`room-closed` 显示“房间已关闭”或“房间已过期”,不得误写成“分享已结束”。房间寿命、媒体代次、换父和恢复等内部状态不得作为额外产品文案暴露。@@ -343,9 +343,9 @@ hop 按[低服务器成本媒体路由](./research/low-server-media-routes.md)- RoomStore 的随机临时房间、TTL、Host token/Viewer grant 摘要验证、private/public policy、grant 到期/跨房拒绝、rotate/revoke 强撤销、停止分享等待、Viewer 上限和超额拒绝;- SQLite 房间库从 `1` 自增、重启恢复、v1/v2 -> v3 单事务迁移、nullable 32-byte grant 与 48-byte password material CHECK、畸形值 fail-closed、rotate/revoke/password 写失败原子性和数据最小化;数据库路径无 site access 时启动失败;- STUN/TURN UDP URL 严格校验、生产 STUN 必需、selected-edge tuple 完整性/TTL/secret 独立性、issuer HMAC/expiry/opaque tag、当前 route/session/revision/old-new connection generation 与 one-use rebuild guard,以及 ordinary peer、未命中房间和 Native 的 STUN-only isolation;LiveKit `sfu-config` 保持独立边界;-- 单一 `screener-v3` 信令 literal、v2 旧页面 mismatch 的一次性刷新终态,以及协议非法 JSON、未知消息、错误方向、跨房间目标和 payload 限制;+- 单一 `screener-v4` 信令 literal、v3 旧页面 mismatch 的一次性刷新终态,以及协议非法 JSON、未知消息、错误方向、跨房间目标和 payload 限制;- 质量协议的 host 授权、严格字段与数值范围、last-wins、当前/未来 relay、已配置 SFU 和普通 P2P wire 兼容;sender 的四字段 requested/applied 读回、拒绝与持续受限提示;screen audio SDP helper 覆盖 CRLF、existing/missing fmtp、unknown key preservation、幂等、payload number、rejected/non-audio,以及 empty/no-Opus/ambiguous/parser 异常原对象 fallback,`ViewerPeer` 覆盖 initial/restart/rebuild 时同一结果的 local/signaling 一致性,SFU publisher 精确断言 high-quality stereo/forceStereo/DTX 且不覆盖 RED;-- HTTP/WS 集成:nginx per-source site-access `limit_req` 与统一错误不泄露 secret,应用不建立 IP limiter 状态;Viewer 可在 Origin/容量门下 upgrade;Host 首条鉴权同时要求 upgrade-captured site access 与 Host token,Viewer 要么持 exact-room grant,要么先有 site access 再按 room policy;site-access cookie 不绕过 private grant/password,grant/password 不能建房、取得 Host 或跨房。覆盖 fragment/sessionStorage/replaceState、无 site access 的 public/password code-only 统一拒绝、通过 site access 后的 public/password 进入、不含明文于 URL/浏览器持久存储/SQLite/log、v2 Native wire,以及 rotate/revoke 后 grace/route 清理、旧 Viewer/上游媒体边关闭和 reconnect 拒绝;+- HTTP/WS 集成:nginx per-source site-access `limit_req` 与统一错误不泄露 secret,应用不建立 IP limiter 状态;Viewer 可在 Origin/容量门下 upgrade;Host 首条鉴权同时要求 upgrade-captured site access 与 Host token,Viewer 要么持 exact-room grant,要么先有 site access 再按 room policy;site-access cookie 不绕过 private grant/password,grant/password 不能建房、取得 Host 或跨房。覆盖 fragment/sessionStorage/replaceState、无 site access 的 public/password code-only 统一拒绝、通过 site access 后的 public/password 进入、不含明文于 URL/浏览器持久存储/SQLite/log、Native capability isolation,以及 rotate/revoke 后 grace/route 清理、旧 Viewer/上游媒体边关闭和 reconnect 拒绝;- 客户端策略与 stats 解析:会话替换不重连,ordinary ICE、LiveKit 与 selected-edge TURN protocol 分离,远端 TURN transport 保持未知;- TypeScript 类型检查、Vite production build 和仓库 hygiene。@@ -384,7 +384,7 @@ bounded controller,且 room `1` 曾作为 exact smoke;下列内容保留为当前部署设置 `PEER_ASSISTED_MEDIA=true` 后,所有正常房间进入`HybridMediaRouter`、房间质量同步和 LiveKit 兜底;每个房间的 route 字段、定向信令、停止、重连和删除状态仍独立。`PEER_ASSISTED_ROOM_IDS` 已退役并在启动时拒绝,-不能以旧变量隐式限制到 room `1`。所有 ordinary peer PC 与 Native v2 仍保持+不能以旧变量隐式限制到 room `1`。所有 ordinary peer PC 与 source-only Native 仍保持STUN-only;只有 controller-selected edge 可接收一次短期 grant。该边界不增加 UI、用户选择或百分比框架。@@ -400,7 +400,7 @@ STUN-only;只有 controller-selected edge 可接收一次短期 grant。该边固定 `2` 是当前上线档而非永久产品上限;后续统一 evidence-driven controller 可在独立验收后使用离散 `0/1/2/3`,不按 device/UA 分支,并由持续 sender bitrate、`availableOutgoingBitrate`、区间 encode time、`qualityLimitationReason`、loss/RTT 健康窗、server deployment hard ceiling 与 cooldown 共同限界。本次 slice 不实现该动态控制。H.264、hardware encode 或 shared encode 可降低编码成本或同观感码率,但每个 child 的网络副本仍独立存在。-Peer-assisted 信令只接受一个严格对象:`resolution` 为 `720p | 1080p | 1440p`,`maxFramerate` 为 15 至 60 的整数,`maxBitrate` 为 2,000,000 至 12,000,000 的整数,`degradationPreference` 为 `maintain-resolution | balanced | maintain-framerate`,可选 `videoCodec` 为 `automatic | h264 | vp8`,其余字段和越界值拒绝。服务端用房间内存 Map 保存完整设置,默认 1080p60、8 Mbps、`balanced`、`automatic`,不写 SQLite;停止分享时保留,房间被放弃或过期时删除。只有 peer-assisted host 可更新,鉴权快照和在线广播携带同一设置;本 wire 由 `screener-v3` 隔离旧页面,普通 P2P 严格鉴权结构不变。SFU publisher 复用同一设置。+Peer-assisted 信令只接受一个严格对象:`resolution` 为 `720p | 1080p | 1440p`,`maxFramerate` 为 15 至 60 的整数,`maxBitrate` 为 2,000,000 至 12,000,000 的整数,`degradationPreference` 为 `maintain-resolution | balanced | maintain-framerate`,可选 `videoCodec` 为 `automatic | h264 | vp8`,其余字段和越界值拒绝。服务端用房间内存 Map 保存完整设置,默认 1080p60、8 Mbps、`balanced`、`automatic`,不写 SQLite;停止分享时保留,房间被放弃或过期时删除。只有 peer-assisted host 可更新,鉴权快照和在线广播携带同一设置;本 wire 由 `screener-v4` 隔离旧页面,普通 P2P 严格鉴权结构不变。SFU publisher 复用同一设置。Viewer 在处理 peer-assisted 鉴权快照时先更新 `ViewerRelay` 的 desired settings,再应用拓扑分配;同一个串行队列协调 remote stream、当前 child 更新和以后重建的 child,因此它们读取同一最新目标。每个 `HostPeer` 也把初始 sender 配置、`replaceStream()` 和 `updateProfile()` 放进同一 sender-mutation queue;desired settings 在入队前同步更新,已排队操作执行时读取最新值,使快速连续修改保持 last-wins,而不增加版本号或确认协议。这里同步的是浏览器 sender 的目标上限,不是实际分辨率、帧率、码率或 shared encoding 的性能保证。diff --git "a/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md" "b/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"index 9b6264b9..a76e9925 100644--- "a/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"+++ "b/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"@@ -19,14 +19,14 @@- [ ] 首屏双入口:分享入口通过站点访问后,主工作区必须同等突出“开始分享”和“加入房间”两个主要动作,并用清楚的视觉分隔表达发送与接收;持合法房间 grant 的观看者不需要知道站点访问密码。“加入房间”在当前舞台内就地展开房间码输入并提交,不先跳转到独立页面;直接访问 `/join` 仍提供同一输入能力。不增加营销首页、模式向导或拓扑选择。浏览器标签页使用与现有 `MonitorUp` 品牌语言一致的 favicon。- [ ] 简单房间:分享者获得纯数字房间码,但房间码只负责定位。现有 `/r/{code}#v={grant}` 合法未过期邀请继续直接进入;仅有 `/r/{code}` 或 `/join` 房间码的 Viewer 必须先通过站点访问验证,再按房间 policy 进入:public-watch 接受房间码,private room 还需正确观看密码。所有入口只授予该房间 Viewer,不能建房、发布、冒充 Host 或跨房。Host 与 Viewer 标题附近都紧凑、显眼地显示房间号并提供只复制房间号的动作,Host 保留复制完整邀请链接;持久房间码从 `1` 开始自增,其他模式继续使用随机临时房间码。- [ ] 免安装观看:桌面和手机观看者可直接通过浏览器链接进入、授权并播放,不依赖与分享端相同的桌面客户端。-- [ ] 屏幕采集:分享者可主动选择显示器或应用窗口,开始、停止、临时同步暂停音视频和切换分享来源;暂停保留现有连接并禁用当前 capture stream 的全部媒体轨道。Host 本地预览必须直接使用 capture stream,支持独立全屏;页面失焦或隐藏时只暂停本地 video element,并明确提示“本地预览已暂停,分享仍在继续”,恢复焦点后继续预览,不得停止 capture、编码或上行。预览不得建立 viewer/媒体边或消耗 TURN、SFU、应用服务器 media egress;预览仍可能产生本地合成、缩放和 GPU 显示成本,不能把隐藏预览称为停止采集或编码。+- [ ] 屏幕采集:分享者可主动选择显示器或应用窗口,开始、停止、临时同步暂停音视频和切换分享来源;暂停保留现有连接并禁用当前 capture stream 的全部媒体轨道。服务端按当前分享代次同步这一主动暂停状态,观看端在视频舞台显示“分享者已暂停”,不得从黑帧、track mute 或网络状态推断暂停;晚加入和信令重连使用权威快照,恢复、停止、新分享或会话替换清除旧提示。Host 本地预览必须直接使用 capture stream,支持独立全屏;页面失焦或隐藏时只暂停本地 video element,并明确提示“本地预览已暂停,分享仍在继续”,恢复焦点后继续预览,不得停止 capture、编码或上行。预览不得建立 viewer/媒体边或消耗 TURN、SFU、应用服务器 media egress;预览仍可能产生本地合成、缩放和 GPU 显示成本,不能把隐藏预览称为停止采集或编码。- [ ] 游戏声音:Windows Chrome/Edge 目标环境可请求系统音频;没有返回音轨时必须明确提示,而不是静默无声。- [ ] 观看端本地音量:播放控制栏提供 `0%` 至 `100%` 音量条和静音按钮,只改变当前浏览器的媒体元素,不修改 Host 音轨、编码、房间状态或其他观看者。切流、换父和 ICE 恢复保留当前页面内的值;刷新后不持久化。静音保留上次非零音量,拖动到非零值自动取消静音。-- [ ] 本地昵称与房间成员:用户可设置一个只保存在当前浏览器同源 `localStorage` 的显示名,界面统一称为“昵称”;默认以只读文本显示,铅笔编辑按钮紧贴昵称,点击后才进入编辑。Viewer 顶部标题直接显示“{Host 名称} 的屏幕”,不得在下方重复一行 Host 名称。信令只在当前在线 socket 会话内保存和广播 NFC 规范化、最多 24 个 Unicode code points、拒绝控制/换行/双向覆盖符与孤立 surrogate 的纯文本标签,不写 SQLite 或日志。空值使用通用角色 fallback。Host 必须看到全部当前在线 Viewer 的权威总数与 roster,不能拿最多两条 Host 媒体直连数冒充在线人数;presence 更新也不得创建媒体连接。展示身份使用“名称 + 当前房间 `peerId` 的至少六字符短后缀”,房内碰撞时有界延长。显示名、后缀和 `clientId` 都不是账号、授权身份或全局 UUID,重复名称允许且不得参与授权、路由或质量决策。Web Host 与 Viewer 通过同一 opt-in participant roster 看到 Host 名称;Native 不发送 capability,wire 保持不变。+- [ ] 本地昵称与房间成员:用户可设置一个只保存在当前浏览器同源 `localStorage` 的显示名,界面统一称为“昵称”;默认以只读文本显示,铅笔编辑按钮紧贴昵称,点击后才进入编辑。Viewer 顶部标题直接显示“{Host 名称} 的屏幕”,不得在下方重复一行 Host 名称。信令只在当前在线 socket 会话内保存和广播 NFC 规范化、最多 24 个 Unicode code points、拒绝控制/换行/双向覆盖符与孤立 surrogate 的纯文本标签,不写 SQLite 或日志。空值使用通用角色 fallback。Web Host 与 Viewer 都必须看到全部当前在线 Viewer 的权威总数与 roster,不能拿最多两条 Host 媒体直连数冒充在线人数;presence 更新也不得创建媒体连接。展示身份默认只显示名称;仅当房内出现同名时追加当前房间 `peerId` 的至少六字符短后缀,并只在同名项后缀碰撞时有界延长。显示名、后缀和 `clientId` 都不是账号、授权身份或全局 UUID,重复名称允许且不得参与授权、路由或质量决策。Web Host 与 Viewer 通过同一 opt-in participant roster 看到 Host 名称;Native 使用同一版本化鉴权 wire,但不发送 presence capability,也不接收 Web roster。- [ ] 一对多观看:当前安全默认上限为 8、可配置范围为 1 至 16;自动分布式拓扑验收后,同一 release 将默认值和上限改为 20。当前 PoC 的逐观看者连接是测量基线,不再是超过两名观看者时的目标拓扑;未通过 20 人门禁时继续明确拒绝超额加入。- [ ] 端点 fanout 硬上限:任一非服务器端点任何时刻最多维护两条 active downstream media edges,包括加入、断线、换父和恢复过程;上游接收不计入这项上传预算。普通 Web relay 统一声明最多两个 child,不按 UA、设备类型或页面可见性另建容量策略;实际 edge 失败进入同一有界换父路径。第三名及后续观看者由系统自动分配给通过验收的 peer-assisted 拓扑,不能隐藏地回退为 Host 第三条连接。没有可行 peer path 时,SFU 作为主要中央兜底 virtual parent 正常向一至两个必要 roots 送流;媒体到达 root 后其余可行观看者仍优先沿受限 peer descendants 扩散。多个无法挂到健康 root 的极端 viewer 可成为额外 server-fed 例外,但必须受显式中央 egress/admission 上限约束,不能无界整房 fanout。TURN 只作为可选的极端网络 transport 兼容层,不定义房间拓扑。- [ ] P2P 优先:每条逻辑媒体边的 ICE 必须先尝试直接 UDP 路径,服务器不得默认中转可直连的媒体。一个或两个观看者优先直接连接分享端;更多观看者的 peer-assisted 行为须先通过 ADR-0004 的实验门槛。-- [ ] NAT 与传输兜底:STUN 必须可用,所有 ordinary peer `RTCPeerConnection` 只接收 STUN ICE servers。PC 失败后按一次 ICE restart、一次同 parent rebuild、一个 alternate peer、再 SFU/UDP virtual parent 的顺序恢复,任一步成功即停止;只有该 edge 的 SFU/UDP 也失败后,controller 才可授权一次短期 authenticated selected-edge TURN/UDP rebuild。授权必须绑定当前 room/share generation、viewer/parent session、route revision 与 old/new connection identity,成功、失败、超时或代次变化即消费;同一房间同时 pending 或 active 的 `peer-selected` attempt 总数最多为一,`host-sfu-ingress` 使用独立状态且不占该 last-mile 名额。不得按 participant、房间或普通 peer PC 下发,Native v2 保持 STUN-only。凭据不进入 URL、日志、浏览器持久化或 SQLite。Coturn 只验证 HMAC 与 expiry,应用必须重验 edge 代次并用短 TTL、one-use state 与 quota 限界。媒体路径保持 UDP-only;全部 UDP 路径耗尽后明确失败。HTTPS/WSS 仍独立使用 TLS/TCP。+- [ ] NAT 与传输兜底:STUN 必须可用,所有 ordinary peer `RTCPeerConnection` 只接收 STUN ICE servers。PC 失败后按一次 ICE restart、一次同 parent rebuild、一个 alternate peer、再 SFU/UDP virtual parent 的顺序恢复,任一步成功即停止;只有该 edge 的 SFU/UDP 也失败后,controller 才可授权一次短期 authenticated selected-edge TURN/UDP rebuild。授权必须绑定当前 room/share generation、viewer/parent session、route revision 与 old/new connection identity,成功、失败、超时或代次变化即消费;同一房间同时 pending 或 active 的 `peer-selected` attempt 总数最多为一,`host-sfu-ingress` 使用独立状态且不占该 last-mile 名额。不得按 participant、房间或普通 peer PC 下发,source-only Native 保持 STUN-only。凭据不进入 URL、日志、浏览器持久化或 SQLite。Coturn 只验证 HMAC 与 expiry,应用必须重验 edge 代次并用短 TTL、one-use state 与 quota 限界。媒体路径保持 UDP-only;全部 UDP 路径耗尽后明确失败。HTTPS/WSS 仍独立使用 TLS/TCP。- [ ] 质量控制:保留 1080p60(8 Mbps)、1080p30(5 Mbps)、720p30(3 Mbps)三档推荐上限,三档与高级设置初始值统一采用 `balanced`(平衡)与 `automatic`(自动编码),`maintain-resolution`(清晰优先)、`maintain-framerate`(流畅优先)和 H.264/VP8 保留为显式选择;分享期间可直接换档或应用有界高级设置,不重新选择来源或重建健康连接,codec 在直播中锁定并于下一次分享生效。Peer-assisted relay 与已配置的 SFU 必须接收同一个严格校验的房间级权威设置,覆盖当前和以后建立的 sender;普通 P2P 信令结构保持不变。任何设置都只是浏览器上限和偏好,具体降级由浏览器决定;必须读回实际 sender 参数并通过 stats 观测结果、显示参数拒绝、改写和持续受限原因。不做自定义动态 FPS、综合评分或周期性全房间调档。- [ ] 路径隔离双表示:direct/peer 继续使用每条 PeerConnection 独立的 stock WebRTC GCC,不把任何 viewer 反馈合成全房目标。每条 SFU path 从 `HIGH` ceiling 开始;优先用 pinned LiveKit 2.22.0/1.13.5 的标准两层 screen-share simulcast,在 Dynacast off 下常驻 exactly `HIGH+LOW`,让内建 per-subscriber BWE 独立降层和恢复。若该 gate 通过,Screener 不实现媒体层 selector。首 gate 使用 zero-descendant SFU leaf;root-with-children 的自动 downshift 与有界迁移是 default-on 前独立硬门。只有内建选择不满足门槛时才用标准 subscriber quality 显式限制,常驻成本不合格时再测标准 sender 手动启停。`LOW` 停编只是资源优化;active representation/layer 硬上限为二,禁止按 viewer 增长。必须实测实际接收层、硬件编码证据、游戏 FPS/p1 low、CPU/GPU、区间 encode cost、上传和分层 bytes。当前 Web P2P simulcast 缺少 receiver 选 RID 和跨 PeerConnection shared-encode 契约;当前 Web/LiveKit SVC 也缺少 direct/peer 独立选层与可移植硬件保证,且 pinned screen share 强制三层 temporal-only `L1T3`,二者按现契约静态 no-go。全部标准路径失败后才考虑 custom/native dual encode。没有合格 hardware/power-efficient 路径或额外表示破坏游戏/上传预算时 fail closed:保护健康路径并明确显示弱路径降级或不可用。- [ ] 路径级质量状态:应用的 `HIGH`/`FALLBACK` 非对称窗口只决定拓扑资格和诊断,不命令正常的媒体层切换,也不计算综合分数。SFU BWE downshift 先进入 `suspect`;多个连续窗口的 sender/viewer 关联证据确认 `FALLBACK` 后,应用不得稳定保留该 parent,并把 downstream capacity 降为 0。计划或显式质量 fallback 仅是内建路径失败后的候选:已有 children 时先在 connection/assignment generation guard 下全部迁走,失败或代次过期则保持原 assignment/quality。Autonomous downshift 无法 packet-level 预先迁移,default-on 前必须验收 descendants 的短暂影响。只有更长的稳定恢复窗口和 cooldown 后才能重新声明 relay capacity。Viewer 请求必须鉴权、限频、去重,并由 sender 的 GCC/Transport-CC、实际码率、RTT、丢包、重传、编码限制、协商 codec/profile/parameters 与 viewer 解码、丢帧、冻结证据交叉验证;不能仅凭自报生效,也不得上传 raw SDP、candidate 地址或原始设备/网络标识。@@ -112,7 +112,7 @@- Given 两端网络允许 UDP 打洞,When 观看者加入,Then `getStats()` 显示选中的候选对不是 `relay`,且服务器没有承载媒体流量。- Given direct/peer UDP 无法建立但 LiveKit SFU/UDP 可达,When 观看者加入或现有 edge 恢复耗尽,Then 系统只把必要 root 切到 SFU,保留可行 peer descendants 和未受影响路径,无需用户选择模式。- Given 未配置 TURN 且所有媒体 UDP 路径均不可用,When 有界连接窗口耗尽,Then 界面快速显示通用连接失败,不静默黑屏、不长时间假连接,也不尝试未配置的媒体路径。-- Given 未配置完整 selected-edge TURN tuple、当前 route/connection generation 不匹配或该 edge 未经过 controller 选择,When 会话鉴权、peer PC 创建或旧消息重放,Then authenticated snapshot 与 ordinary peer PC 必须保持 STUN-only,服务端不得签发或接受该 TURN grant;不得把 credential 发给 Native v2、普通房间或未鉴权会话。+- Given 未配置完整 selected-edge TURN tuple、当前 route/connection generation 不匹配或该 edge 未经过 controller 选择,When 会话鉴权、peer PC 创建或旧消息重放,Then authenticated snapshot 与 ordinary peer PC 必须保持 STUN-only,服务端不得签发或接受该 TURN grant;不得把 credential 发给 source-only Native、普通房间或未鉴权会话。- Given 当前异常 edge 已耗尽 direct/peer UDP 与 SFU/UDP 且 controller 授权一次 selected-edge TURN attempt,When parent 与 child 以同一 session/revision/old-and-new connection generation 重建,Then 只有该新 PC 使用 relay-only 短期 credential;成功即停止,失败或过期即消费并明确失败,不得把 bearer 复用于其他 edge、后续 PC 或整个 participant。- Given 部署者为 LiveKit 启用了 embedded/external TURN,When publisher 或 subscriber 的 SFU/UDP 路径耗尽,Then 只把它作为 LiveKit participant-to-SFU 兼容 transport 单独验收;它不是 Screener selected peer-edge grant,也不得改变 controller 的默认梯级。- Given 同一房间中一名观看者可以 direct/peer UDP、另一名只能通过 SFU root 接收,When 两者同时观看,Then 前者保持分布式 P2P,后者使用 SFU,双方互不迁移且 host/SFU root 上限不变。@@ -123,7 +123,7 @@- Given 用户在普通手机浏览器尝试成为 Host,When `navigator.mediaDevices.getDisplayMedia` 缺失,Then 页面在创建发布路径前明确显示该浏览器不支持移动端屏幕分享,并保留加入房间入口。Given API 存在但真实调用失败,When 失败原因是拒绝/取消或其他 capture error,Then 分别显示对应状态而不是一律重标为不支持;判断使用运行时能力/结果而不是 UA、平台或设备型号,也不能把移动 Viewer 支持宣传成移动 Web Host 支持。- Given 观看者调节音量或静音,When 媒体切流、换父或恢复连接,Then 当前页面的本地播放音量保持不变,其他观看者和发送端不受影响;刷新页面后恢复默认音量,不产生信令、持久化或媒体重协商。- Given Viewer 已通过浏览器要求的用户手势开始可听播放,When 页面切到后台且浏览器仍保留该页面,Then 同一个媒体元素、信令和 WebRTC 连接继续承载音频,返回前台后沿当前直播恢复画面而无需重新加入;后台视频合成或逐帧回调增长不作为连续播放承诺。Given iOS 锁屏、系统回收页面或后台期间产生新的媒体连接,Then 以当前真机行为为准,恢复时继续使用已有重连和显式播放入口。-- Given 用户查看本机身份,When 尚未进入编辑状态,Then 界面显示“昵称”、当前昵称和紧贴其后的铅笔按钮,不显示默认可编辑输入框。Given 用户修改昵称后以 Host 或 Viewer 加入房间,Then 所有在线参与者看到同一份服务端权威 roster、对应房间标题和“名称 + room-scoped peer 后缀”;刷新后本机名称仍在,清除站点数据后恢复未命名默认值,数据库中不存在显示名或成员记录,展示身份不参与授权或路由。+- Given 用户查看本机身份,When 尚未进入编辑状态,Then 界面显示“昵称”、当前昵称和紧贴其后的铅笔按钮,不显示默认可编辑输入框。Given 用户修改昵称后以 Host 或 Viewer 加入房间,Then 所有在线参与者看到同一份服务端权威 roster、对应房间标题;唯一名称只显示名称,重名项追加当前房间 `peerId` 短后缀。刷新后本机名称仍在,清除站点数据后恢复未命名默认值,数据库中不存在显示名或成员记录,展示身份不参与授权或路由。- Given 手机从 Wi-Fi 切换到蜂窝网络或页面从后台恢复,When 原候选对失效,Then 客户端执行 ICE restart 或重建连接,并显示恢复进度而不是永久黑屏。- Given Viewer 尝试把直播输出到电视,When 浏览器/系统提供已验证的 Remote Playback、AirPlay 或屏幕镜像能力,Then 该动作只改变本机输出设备,现有 upstream PeerConnection、TURN/SFU/peer route 和其他参与者保持不变。Given live `srcObject` 未经目标设备证明或 API 缺失,Then 产品不显示伪可用 Cast/AirPlay 按钮,也不创建自有 receiver 或转码服务器。diff --git a/native/sender/internal/app/server_test.go b/native/sender/internal/app/server_test.goindex c464769f..669bcba4 100644--- a/native/sender/internal/app/server_test.go+++ b/native/sender/internal/app/server_test.go@@ -632,7 +632,7 @@ func newAppRemoteServer(t *testing.T, terminal chan<- []byte) *httptest.Server {if _, _, err = connection.Read(request.Context()); err != nil {return}- authenticated := []byte(`{"type":"authenticated","protocol":"screener-v2","role":"host","peerId":"host-peer","roomExpiresAt":null,"maxViewers":3,"hostOnline":true,"connectionId":null,"viewerPeerIds":[],"iceConfig":{"iceServers":[]},"viewerPolicy":"private-link","viewerAuthorizationGeneration":"viewer_generation_12345678"}`)+ authenticated := []byte(`{"type":"authenticated","protocol":"screener-v4","role":"host","peerId":"host-peer","roomExpiresAt":null,"maxViewers":3,"hostOnline":true,"connectionId":null,"viewerPeerIds":[],"iceConfig":{"iceServers":[]},"viewerPolicy":"private-link","viewerAuthorizationGeneration":"viewer_generation_12345678"}`)if err = connection.Write(request.Context(), websocket.MessageText, authenticated); err != nil {return}@@ -688,7 +688,7 @@ func newDelayedAppRemoteServer(<-releaseAuthenticationwriteContext, cancelWrite := context.WithTimeout(context.Background(), time.Second)defer cancelWrite()- _ = connection.Write(writeContext, websocket.MessageText, []byte(`{"type":"authenticated","protocol":"screener-v2","role":"host","peerId":"host-peer","roomExpiresAt":null,"maxViewers":3,"hostOnline":true,"connectionId":null,"viewerPeerIds":[],"iceConfig":{"iceServers":[]},"viewerPolicy":"private-link","viewerAuthorizationGeneration":"viewer_generation_12345678"}`))+ _ = connection.Write(writeContext, websocket.MessageText, []byte(`{"type":"authenticated","protocol":"screener-v4","role":"host","peerId":"host-peer","roomExpiresAt":null,"maxViewers":3,"hostOnline":true,"connectionId":null,"viewerPeerIds":[],"iceConfig":{"iceServers":[]},"viewerPolicy":"private-link","viewerAuthorizationGeneration":"viewer_generation_12345678"}`))})return server}diff --git a/native/sender/internal/remote/wire.go b/native/sender/internal/remote/wire.goindex 610b3d9b..6cb91dc4 100644--- a/native/sender/internal/remote/wire.go+++ b/native/sender/internal/remote/wire.go@@ -16,7 +16,7 @@ import ()const (- signalingProtocol = "screener-v2"+ signalingProtocol = "screener-v4"maxProtocolViewers = 16maxRouteRevision = int64(1<<53 - 1)maxSignalSDPBytes = 48 << 10diff --git a/native/sender/internal/remote/wire_test.go b/native/sender/internal/remote/wire_test.goindex ff7f5700..cda9dc78 100644--- a/native/sender/internal/remote/wire_test.go+++ b/native/sender/internal/remote/wire_test.go@@ -6,9 +6,9 @@ import ("testing")-const validHostAuthenticated = `{"type":"authenticated","protocol":"screener-v2","role":"host","peerId":"host-peer","roomExpiresAt":null,"maxViewers":3,"hostOnline":true,"connectionId":null,"viewerPeerIds":[],"iceConfig":{"iceServers":[{"urls":["stun:example.test"]}]},"viewerPolicy":"private-link","viewerAuthorizationGeneration":"viewer_generation_12345678"}`+const validHostAuthenticated = `{"type":"authenticated","protocol":"screener-v4","role":"host","peerId":"host-peer","roomExpiresAt":null,"maxViewers":3,"hostOnline":true,"connectionId":null,"viewerPeerIds":[],"iceConfig":{"iceServers":[{"urls":["stun:example.test"]}]},"viewerPolicy":"private-link","viewerAuthorizationGeneration":"viewer_generation_12345678"}`-const validPeerAssistedHostAuthenticated = `{"type":"authenticated","protocol":"screener-v2","role":"host","peerId":"host-peer","roomExpiresAt":null,"maxViewers":3,"hostOnline":true,"connectionId":null,"viewerPeerIds":["viewer-1","viewer-2"],"iceConfig":{"iceServers":[{"urls":["stun:example.test"]}]},"viewerPolicy":"private-link","viewerAuthorizationGeneration":"viewer_generation_12345678","mediaMode":"peer-assisted","mediaAssignment":{"parentPeerId":null,"childPeerIds":["viewer-1","viewer-2"]},"routeRevision":7,"routeAssignment":{"upstream":{"kind":"none"},"childPeerIds":["viewer-1","viewer-2"],"sfuPublicationGeneration":null},"qualitySettings":{"resolution":"1080p","maxFramerate":60,"maxBitrate":8000000,"degradationPreference":"maintain-resolution"}}`+const validPeerAssistedHostAuthenticated = `{"type":"authenticated","protocol":"screener-v4","role":"host","peerId":"host-peer","roomExpiresAt":null,"maxViewers":3,"hostOnline":true,"connectionId":null,"viewerPeerIds":["viewer-1","viewer-2"],"iceConfig":{"iceServers":[{"urls":["stun:example.test"]}]},"viewerPolicy":"private-link","viewerAuthorizationGeneration":"viewer_generation_12345678","mediaMode":"peer-assisted","mediaAssignment":{"parentPeerId":null,"childPeerIds":["viewer-1","viewer-2"]},"routeRevision":7,"routeAssignment":{"upstream":{"kind":"none"},"childPeerIds":["viewer-1","viewer-2"],"sfuPublicationGeneration":null},"qualitySettings":{"resolution":"1080p","maxFramerate":60,"maxBitrate":8000000,"degradationPreference":"maintain-resolution","videoCodec":"automatic"}}`func TestMarshalHostSignalShapes(t *testing.T) {mid := "0"diff --git a/src/client/lib/signaling.ts b/src/client/lib/signaling.tsindex 42fe6dc9..d64d7e27 100644--- a/src/client/lib/signaling.ts+++ b/src/client/lib/signaling.ts@@ -114,6 +114,21 @@ export class SignalingClient {return this.setDisplayName(displayName);}+ setSharingPaused(paused: boolean): boolean {+ if (this.identity.role !== "host") {+ return false;+ }+ this.identity.sharingPaused = paused;+ if (!this.identity.shareGeneration) {+ return false;+ }+ return this.send({+ type: "set-sharing-paused",+ shareGeneration: this.identity.shareGeneration,+ paused,+ });+ }+sendThenStop(message: ClientMessage): void {if (this.stopped) {return;diff --git a/src/client/lib/viewer-presence.ts b/src/client/lib/viewer-presence.tsindex 2400bcdd..5f634d62 100644--- a/src/client/lib/viewer-presence.ts+++ b/src/client/lib/viewer-presence.ts@@ -1,4 +1,7 @@-import type { ViewerPresenceEntry } from "../../shared/protocol";+import type {+ ParticipantPresenceEntry,+ ViewerPresenceEntry,+} from "../../shared/protocol";export interface LabeledViewerPresence extends ViewerPresenceEntry {peerIdSuffix: string;@@ -10,6 +13,18 @@ const MIN_PEER_ID_SUFFIX_LENGTH = 6;export function labelViewerPresence(viewers: readonly ViewerPresenceEntry[],): LabeledViewerPresence[] {+ const nameCounts = new Map<string, number>();+ viewers.forEach((viewer) => {+ nameCounts.set(+ viewer.displayName,+ (nameCounts.get(viewer.displayName) ?? 0) + 1,+ );+ });+ const duplicateNames = new Set(+ [...nameCounts.entries()]+ .filter(([, count]) => count > 1)+ .map(([displayName]) => displayName),+ );const suffixLengths = viewers.map((viewer) =>Math.min(MIN_PEER_ID_SUFFIX_LENGTH, viewer.peerId.length),);@@ -17,10 +32,14 @@ export function labelViewerPresence(while (true) {const collisions = new Map<string, number[]>();viewers.forEach((viewer, index) => {+ if (!duplicateNames.has(viewer.displayName)) {+ return;+ }const suffix = viewer.peerId.slice(-suffixLengths[index]);- const indexes = collisions.get(suffix) ?? [];+ const key = `${viewer.displayName}\u0000${suffix}`;+ const indexes = collisions.get(key) ?? [];indexes.push(index);- collisions.set(suffix, indexes);+ collisions.set(key, indexes);});let extended = false;for (const indexes of collisions.values()) {@@ -44,7 +63,20 @@ export function labelViewerPresence(return {...viewer,peerIdSuffix,- label: `${viewer.displayName} (${peerIdSuffix})`,+ label: duplicateNames.has(viewer.displayName)+ ? `${viewer.displayName} (${peerIdSuffix})`+ : viewer.displayName,};});}++export function labelViewerParticipants(+ participants: readonly ParticipantPresenceEntry[],+): LabeledViewerPresence[] {+ return labelViewerPresence(+ participants.filter(+ (participant): participant is ViewerPresenceEntry =>+ participant.role === "viewer",+ ),+ );+}diff --git a/src/client/media/viewer-sfu-route.ts b/src/client/media/viewer-sfu-route.tsindex de530723..c6d12d8d 100644--- a/src/client/media/viewer-sfu-route.ts+++ b/src/client/media/viewer-sfu-route.ts@@ -27,6 +27,7 @@ interface ViewerSubscriberSlot {subscriber: ViewerSubscriberTransport;connected: boolean;activated: boolean;+ mediaAvailable: boolean;failed: boolean;activationToken: RouteOperationToken | null;}@@ -125,9 +126,14 @@ export class ViewerSfuRoute {async resyncAuthoritative(update: RouteUpdateInput,): Promise<RouteUpdateResult> {- const result = this.accept(update, false);- if (result !== "stale" || this.closed) {- return result;+ if (this.closed) {+ return "stale";+ }+ if (!this.active && !this.pending) {+ const result = this.accept(update, false);+ if (result !== "stale") {+ return result;+ }}const resyncGeneration = ++this.resyncGeneration;@@ -250,6 +256,7 @@ export class ViewerSfuRoute {subscriber,connected: false,activated: false,+ mediaAvailable: false,failed: false,activationToken: null,};@@ -436,7 +443,12 @@ export class ViewerSfuRoute {if (this.active === slot) {const assignment = this.route.getMediaAssignment();if (assignment?.upstream.kind === "sfu") {+ const recovered = !slot.mediaAvailable;+ slot.mediaAvailable = true;this.events.onSfuStream(stream, assignment, false);+ if (recovered) {+ this.ready(slot.revision, "active");+ }}return;}@@ -460,6 +472,7 @@ export class ViewerSfuRoute {return;}this.recovery = null;+ slot.mediaAvailable = true;this.events.onSfuStream(stream, assignment, true);if (previous && previous !== slot) {try {@@ -485,7 +498,20 @@ export class ViewerSfuRoute {) {return;}+ const changed = slot.mediaAvailable !== available;+ slot.mediaAvailable = available;this.events.onSfuVideoAvailability?.(available);+ if (!changed) {+ return;+ }+ if (available) {+ this.ready(slot.revision, "active");+ } else {+ this.events.send({+ type: "route-media-unavailable",+ revision: slot.revision,+ });+ }}private commitMedia(token: RouteOperationToken, acknowledge: boolean): void {@@ -493,7 +519,11 @@ export class ViewerSfuRoute {return;}this.recovery = null;- if (acknowledge) {+ const assignment = this.route.getMediaAssignment();+ if (+ acknowledge &&+ (assignment?.upstream.kind !== "sfu" || this.active?.mediaAvailable === true)+ ) {this.ready(token.revision, "active");}}diff --git a/src/client/pages/HostPage.tsx b/src/client/pages/HostPage.tsxindex 25a25e80..1d606cc2 100644--- a/src/client/pages/HostPage.tsx+++ b/src/client/pages/HostPage.tsx@@ -66,7 +66,7 @@ import {writeHostRoom,} from "../lib/session";import { SignalingClient } from "../lib/signaling";-import { labelViewerPresence } from "../lib/viewer-presence";+import { labelViewerParticipants } from "../lib/viewer-presence";import {applyCaptureProfile,captureDisplay,@@ -275,15 +275,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {[peerSnapshots],);const viewers = useMemo(- () =>- labelViewerPresence(- participantPresence.filter(- (participant): participant is Extract<- ParticipantPresenceEntry,- { role: "viewer" }- > => participant.role === "viewer",- ),- ),+ () => labelViewerParticipants(participantPresence),[participantPresence],);const hostPresence = useMemo(@@ -728,6 +720,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {}sharingPausedRef.current = nextPaused;setSharingPaused(nextPaused);+ signalRef.current?.setSharingPaused(nextPaused);setNotice(nextPaused ? "音视频分享已暂停" : "音视频分享已恢复");}@@ -1218,6 +1211,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {token: activeRoom.hostToken,clientId: hostClientId,shareGeneration,+ sharingPaused: false,viewerPresence: true,viewerPasswordSettings: true,displayName: initialDisplayName,@@ -2169,11 +2163,17 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {const hasCurrentQualityEvidence =viewer.upstream.kind === "peer" &&qualityEvidence?.parentPeerId === viewer.upstream.peerId;+ const hasCurrentSfuEvidence =+ viewer.upstream.kind === "sfu" &&+ viewer.sfuMediaReady === true;const hasCurrentRouteEvidence =- hasPeerRouteEvidence(snapshot) || hasCurrentQualityEvidence;+ hasPeerRouteEvidence(snapshot) ||+ hasCurrentQualityEvidence ||+ hasCurrentSfuEvidence;const hasCurrentConnectionEvidence =snapshot?.connectionState === "connected" ||- hasCurrentQualityEvidence;+ hasCurrentQualityEvidence ||+ hasCurrentSfuEvidence;const viewerState =hasCurrentConnectionEvidence? "connected"diff --git a/src/client/pages/ViewerPage.tsx b/src/client/pages/ViewerPage.tsxindex b6b19386..ca232a44 100644--- a/src/client/pages/ViewerPage.tsx+++ b/src/client/pages/ViewerPage.tsx@@ -39,6 +39,7 @@ import { viewerRouteEvidence } from "../components/status-badge-model";import { readDisplayName, saveDisplayName } from "../lib/display-name";import { clearViewerGrant, getStableClientId } from "../lib/session";import { SignalingClient } from "../lib/signaling";+import { labelViewerParticipants } from "../lib/viewer-presence";import type { QualitySettings } from "../media/quality";import {ParentEdgeQualityEvidenceReporter,@@ -105,6 +106,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {useState<SignalConnectionState>("offline");const [statusText, setStatusText] = useState("正在连接");const [hostOnline, setHostOnline] = useState(false);+ const [hostPaused, setHostPaused] = useState(false);const [remoteStream, setRemoteStream] = useState<MediaStream | null>(null);const [peerSnapshot, setPeerSnapshot] = useState<PeerSnapshot | null>(null);const [sfuUpstream, setSfuUpstream] = useState<SfuUpstreamState | null>(null);@@ -124,10 +126,9 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {const [displayNameDraft, setDisplayNameDraft] = useState(displayName);const [displayNameError, setDisplayNameError] = useState<string | null>(null);const [editingDisplayName, setEditingDisplayName] = useState(false);- const [hostPresence, setHostPresence] = useState<Extract<- ParticipantPresenceEntry,- { role: "host" }- > | null>(null);+ const [participantPresence, setParticipantPresence] = useState<+ ParticipantPresenceEntry[] | null+ >(null);const [viewerPasswordDraft, setViewerPasswordDraft] = useState("");const [viewerPasswordError, setViewerPasswordError] = useState<string | null>(null,@@ -146,6 +147,32 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {),[peerSnapshot, relaySnapshot],);+ const hostPresence = useMemo(+ () =>+ participantPresence?.find(+ (participant): participant is Extract<+ ParticipantPresenceEntry,+ { role: "host" }+ > => participant.role === "host",+ ) ?? null,+ [participantPresence],+ );+ const viewers = useMemo(+ () => labelViewerParticipants(participantPresence ?? []),+ [participantPresence],+ );++ function clearParticipantPresence(): void {+ setParticipantPresence(null);+ setHostPaused(false);+ }++ function clearHostPresence(): void {+ setParticipantPresence((current) =>+ current?.filter((participant) => participant.role !== "host") ?? null,+ );+ setHostPaused(false);+ }const videoRef = useRef<HTMLVideoElement | null>(null);const peerRef = useRef<ViewerPeer | null>(null);@@ -240,7 +267,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {setAssignedRoute(null);clearViewerSfuRoute();clearPeerState();- setHostPresence(null);+ clearParticipantPresence();if (!viewerAuthenticated) {setAccessState("denied");}@@ -253,7 +280,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {setAssignedRoute(null);clearViewerSfuRoute();clearPeerState();- setHostPresence(null);+ clearParticipantPresence();viewerAuthenticated = false;setAccessState("denied");setStatusText("邀请无效或已失效");@@ -806,6 +833,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {currentIceConfig = message.iceConfig;currentHostOnline = message.hostOnline;setHostOnline(message.hostOnline);+ setHostPaused(message.hostPaused ?? false);if (nextPeerAssisted && "qualitySettings" in message) {currentQualitySettings = message.qualitySettings;void viewerRelay?.updateProfile(currentQualitySettings);@@ -995,6 +1023,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {if (message.type === "host-status") {currentHostOnline = message.online;setHostOnline(message.online);+ setHostPaused(message.paused);if (!message.online && !peerRef.current?.isConnected()) {setStatusText("等待开始分享");} else if (message.online && !peerRef.current?.isConnected()) {@@ -1003,14 +1032,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {return;}if (message.type === "viewer-presence") {- setHostPresence(- message.viewers.find(- (participant): participant is Extract<- ParticipantPresenceEntry,- { role: "host" }- > => participant.role === "host",- ) ?? null,- );+ setParticipantPresence(message.viewers);return;}if (message.type === "sharing-stopped") {@@ -1019,7 +1041,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {currentHostOnline = false;clearViewerSfuRoute();clearPeerState();- setHostPresence(null);+ clearHostPresence();setHostOnline(false);setStatusText("等待开始分享");return;@@ -1039,7 +1061,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {setAssignedRoute(null);clearViewerSfuRoute();clearPeerState();- setHostPresence(null);+ clearParticipantPresence();setStatusText("邀请已失效,请向分享者获取新链接");signal.stop();return;@@ -1051,7 +1073,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {setAssignedRoute(null);clearViewerSfuRoute();clearPeerState();- setHostPresence(null);+ clearParticipantPresence();setStatusText(message.reason === "expired" ? "房间已过期" : "房间已关闭");signal.stop();return;@@ -1059,7 +1081,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {if (message.type === "error") {if (message.code === "PEER_NOT_FOUND" && !currentHostOnline) {clearPeerState();- setHostPresence(null);+ clearHostPresence();setStatusText("等待开始分享");return;}@@ -1075,7 +1097,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {setAssignedRoute(null);clearViewerSfuRoute();clearPeerState();- setHostPresence(null);+ clearParticipantPresence();viewerAuthenticated = false;setAccessState("denied");}@@ -1104,7 +1126,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {}sfuStandbyPrewarmer?.dispose();signal.stop();- setHostPresence(null);+ clearParticipantPresence();if (signalRef.current === signal) {signalRef.current = null;}@@ -1408,7 +1430,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {<span>{statusText}</span></div>)}- {playbackBlocked && remoteStream && (+ {playbackBlocked && remoteStream && !hostPaused && (<buttontype="button"className="play-overlay"@@ -1418,6 +1440,11 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {播放</button>)}+ {hostOnline && hostPaused && (+ <div className="stage-overlay" role="status">+ 分享者已暂停+ </div>+ )}</section><div className="viewer-toolbar">@@ -1472,6 +1499,25 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {</div></div>+ {participantPresence && (+ <section+ className="viewer-roster"+ aria-labelledby="viewer-roster-heading"+ >+ <div className="viewer-roster-heading">+ <h2 id="viewer-roster-heading">观看者</h2>+ <span>在线 {viewers.length}</span>+ </div>+ <ul className="viewer-roster-list">+ {viewers.map((viewer) => (+ <li key={viewer.peerId} title={viewer.label}>+ {viewer.label}+ </li>+ ))}+ </ul>+ </section>+ )}+<ConnectionDetailsTogglechecked={showConnectionDetails}onChange={setShowConnectionDetails}diff --git a/src/client/styles.css b/src/client/styles.cssindex 9c3d2252..c31e4476 100644--- a/src/client/styles.css+++ b/src/client/styles.css@@ -1122,6 +1122,47 @@ h3 {border-bottom: 1px solid var(--border);}+.viewer-roster {+ margin-top: 16px;+ padding: 14px 0;+ border-block: 1px solid var(--border);+}++.viewer-roster-heading {+ display: flex;+ align-items: baseline;+ justify-content: space-between;+ gap: 12px;+ margin-bottom: 10px;+}++.viewer-roster-heading h2 {+ color: var(--muted);+ font-size: 14px;+}++.viewer-roster-heading span {+ color: var(--faint);+ font-size: 12px;+}++.viewer-roster-list {+ display: flex;+ flex-wrap: wrap;+ gap: 7px 20px;+ margin: 0;+ padding: 0;+ list-style: none;+}++.viewer-roster-list li {+ min-width: 0;+ color: var(--text);+ font-size: 13px;+ font-weight: 600;+ overflow-wrap: anywhere;+}+.toolbar-status {min-width: 0;overflow: hidden;diff --git a/src/server/hybrid-media-router.ts b/src/server/hybrid-media-router.tsindex 19a1497c..23195668 100644--- a/src/server/hybrid-media-router.ts+++ b/src/server/hybrid-media-router.ts@@ -161,6 +161,14 @@ export interface HybridMediaRouterOptions {deleteConnectionId: (roomId: string, viewerPeerId: string) => void;getShareGeneration: (roomId: string) => string | undefined;onActiveRouteChanged?: (roomId: string) => void;+ onViewerMediaState?: (+ roomId: string,+ viewerPeerId: string,+ viewerSessionId: string,+ revision: number,+ sfuPublicationGeneration: string,+ ready: boolean,+ ) => void;now?: () => number;}@@ -473,6 +481,20 @@ export class HybridMediaRouter {return { kind: "sfu" };}+ viewerSfuMediaStateIsCurrent(+ roomId: string,+ viewerPeerId: string,+ revision: number,+ sfuPublicationGeneration: string,+ ): boolean {+ const active = this.mediaRouteControllers.get(roomId)?.getActiveRoute();+ return Boolean(+ active?.revision === revision &&+ active.assignments.get(viewerPeerId)?.upstream.kind === "sfu" &&+ active.sfu.publicationGeneration === sfuPublicationGeneration,+ );+ }+handleViewerQualityEvidence(input: ForwardedViewerQualityEvidence): void {const { evidence, roomId, viewerSessionId, parentSessionId } = input;const { viewerPeerId, parentPeerId } = evidence;@@ -850,6 +872,10 @@ export class HybridMediaRouter {return;}if (message.phase === "active") {+ if (participant.role === "viewer") {+ this.notifyViewerMediaState(participant, message.revision, true);+ return;+ }const active = controller.getActiveRoute();if (active.revision === message.revision &&@@ -919,6 +945,47 @@ export class HybridMediaRouter {this.commitPendingRoute(participant.roomId, message.revision);}+ handleRouteMediaUnavailable(+ participant: AuthenticatedRouteParticipant,+ message: Extract<ClientMessage, { type: "route-media-unavailable" }>,+ ): void {+ this.notifyViewerMediaState(participant, message.revision, false);+ }++ private notifyViewerMediaState(+ participant: AuthenticatedRouteParticipant,+ revision: number,+ ready: boolean,+ ): void {+ if (+ participant.role !== "viewer" ||+ this.connectedPeer(participant.roomId, participant.peerId)?.sessionId !==+ participant.sessionId+ ) {+ return;+ }+ const active = this.mediaRouteControllers+ .get(participant.roomId)+ ?.getActiveRoute();+ const assignment = active?.assignments.get(participant.peerId);+ if (+ !active ||+ active.revision !== revision ||+ assignment?.upstream.kind !== "sfu" ||+ active.sfu.publicationGeneration === null+ ) {+ return;+ }+ this.options.onViewerMediaState?.(+ participant.roomId,+ participant.peerId,+ participant.sessionId,+ revision,+ active.sfu.publicationGeneration,+ ready,+ );+ }+handleRouteFailed(participant: AuthenticatedRouteParticipant,message: Extract<ClientMessage, { type: "route-failed" }>,diff --git a/src/server/signaling.ts b/src/server/signaling.tsindex 7ae839d8..539ae5cb 100644--- a/src/server/signaling.ts+++ b/src/server/signaling.ts@@ -72,6 +72,12 @@ interface ViewerQualityEvidenceGate {parentEvidenceAccepted: boolean;}+interface ViewerMediaReadyState {+ sessionId: string;+ revision: number;+ sfuPublicationGeneration: string;+}+export interface SignalingOptions {server: HttpServer;roomStore: RoomStore;@@ -106,8 +112,13 @@ export class SignalingServer {string,ViewerQualityEvidenceGate>();+ private readonly viewerMediaReadyByRoom = new Map<+ string,+ Map<string, ViewerMediaReadyState>+ >();private readonly qualitySettingsByRoom = new Map<string, QualitySettings>();private readonly shareGenerationsByRoom = new Map<string, string>();+ private readonly pausedShareGenerationsByRoom = new Map<string, string>();private readonly deferredViewerPresenceRooms = new Set<string>();private readonly hybridMediaRouter?: HybridMediaRouter;private readonly now: () => number;@@ -155,7 +166,26 @@ export class SignalingServer {deleteConnectionId: (roomId, viewerPeerId) =>this.deleteViewerConnectionId(roomId, viewerPeerId),getShareGeneration: (roomId) => this.shareGenerationsByRoom.get(roomId),- onActiveRouteChanged: (roomId) => this.sendViewerPresence(roomId),+ onActiveRouteChanged: (roomId) => {+ this.viewerMediaReadyByRoom.delete(roomId);+ this.sendViewerPresence(roomId);+ },+ onViewerMediaState: (+ roomId,+ viewerPeerId,+ viewerSessionId,+ revision,+ sfuPublicationGeneration,+ ready,+ ) =>+ this.updateViewerMediaState(+ roomId,+ viewerPeerId,+ viewerSessionId,+ revision,+ sfuPublicationGeneration,+ ready,+ ),now: this.now,});}@@ -216,7 +246,9 @@ export class SignalingServer {this.viewerGraceTimers.clear();this.hybridMediaRouter?.close();this.viewerQualityEvidenceGates.clear();+ this.viewerMediaReadyByRoom.clear();this.shareGenerationsByRoom.clear();+ this.pausedShareGenerationsByRoom.clear();this.options.server.off("upgrade", this.upgradeHandler);for (const socket of this.webSocketServer.clients) {@@ -433,6 +465,14 @@ export class SignalingServer {this.stopSharing(participant.roomId);}this.shareGenerationsByRoom.set(participant.roomId, shareGeneration);+ if (message.sharingPaused === true) {+ this.pausedShareGenerationsByRoom.set(+ participant.roomId,+ shareGeneration,+ );+ } else {+ this.pausedShareGenerationsByRoom.delete(participant.roomId);+ }}state.authenticated = {roomId: participant.roomId,@@ -494,6 +534,14 @@ export class SignalingServer {roomExpiresAt: participant.expiresAt,maxViewers: this.options.roomStore.maxViewersPerRoom,hostOnline: participant.hostOnline,+ ...(participant.role === "viewer"+ ? {+ hostPaused:+ participant.hostOnline &&+ this.pausedShareGenerationsByRoom.get(participant.roomId) ===+ this.shareGenerationsByRoom.get(participant.roomId),+ }+ : {}),connectionId,viewerPeerIds: [...participant.viewerPeerIds],iceConfig: this.iceConfig(),@@ -545,7 +593,13 @@ export class SignalingServer {if (participant.role === "host") {for (const viewer of connectedViewers) {- this.sendToSession(viewer.sessionId, { type: "host-status", online: true });+ this.sendToSession(viewer.sessionId, {+ type: "host-status",+ online: true,+ paused:+ this.pausedShareGenerationsByRoom.get(participant.roomId) ===+ shareGeneration,+ });if (!this.isHybridMediaEnabled()) {this.send(socket, { type: "peer-joined", peerId: viewer.peerId });}@@ -667,6 +721,19 @@ export class SignalingServer {message,);return;+ case "route-media-unavailable":+ if (!this.isHybridMediaEnabled()) {+ this.sendError(socket, "FORBIDDEN", "Media routes are not enabled");+ return;+ }+ this.hybridMediaRouter!.handleRouteMediaUnavailable(+ {+ ...authenticated,+ sessionId: this.socketStates.get(socket)!.sessionId,+ },+ message,+ );+ return;case "route-failed":if (!this.isHybridMediaEnabled()) {this.sendError(socket, "FORBIDDEN", "Media routes are not enabled");@@ -758,6 +825,44 @@ export class SignalingServer {});return;}+ case "set-sharing-paused":+ if (authenticated.role !== "host") {+ this.sendError(socket, "FORBIDDEN", "Only the host may pause sharing");+ return;+ }+ const pauseSocketState = this.socketStates.get(socket);+ const connectedHost = this.options.roomStore.getConnectedHost(+ authenticated.roomId,+ );+ if (+ !pauseSocketState ||+ connectedHost?.sessionId !== pauseSocketState.sessionId ||+ authenticated.shareGeneration === null ||+ this.shareGenerationsByRoom.get(authenticated.roomId) !==+ authenticated.shareGeneration ||+ message.shareGeneration !== authenticated.shareGeneration+ ) {+ socket.close(4001, "Sharing generation replaced");+ return;+ }+ if (message.paused) {+ this.pausedShareGenerationsByRoom.set(+ authenticated.roomId,+ authenticated.shareGeneration,+ );+ } else {+ this.pausedShareGenerationsByRoom.delete(authenticated.roomId);+ }+ for (const viewer of this.options.roomStore.getConnectedViewers(+ authenticated.roomId,+ )) {+ this.sendToSession(viewer.sessionId, {+ type: "host-status",+ online: true,+ paused: message.paused,+ });+ }+ return;case "stop-sharing":if (authenticated.role !== "host") {this.sendError(socket, "FORBIDDEN", "Only the host may stop sharing");@@ -1295,7 +1400,11 @@ export class SignalingServer {for (const viewer of this.options.roomStore.getConnectedViewers(disconnected.roomId,)) {- this.sendToSession(viewer.sessionId, { type: "host-status", online: false });+ this.sendToSession(viewer.sessionId, {+ type: "host-status",+ online: false,+ paused: false,+ });}this.sendViewerPresence(disconnected.roomId);return;@@ -1337,13 +1446,18 @@ export class SignalingServer {}private stopSharing(roomId: string): void {+ this.pausedShareGenerationsByRoom.delete(roomId);this.clearRoomConnectionIds(roomId);if (this.isHybridMediaEnabled()) {this.hybridMediaRouter!.stopRoom(roomId);}for (const viewer of this.options.roomStore.getConnectedViewers(roomId)) {this.sendToSession(viewer.sessionId, { type: "sharing-stopped" });- this.sendToSession(viewer.sessionId, { type: "host-status", online: false });+ this.sendToSession(viewer.sessionId, {+ type: "host-status",+ online: false,+ paused: false,+ });}}@@ -1359,6 +1473,7 @@ export class SignalingServer {}this.qualitySettingsByRoom.delete(roomId);this.shareGenerationsByRoom.delete(roomId);+ this.pausedShareGenerationsByRoom.delete(roomId);for (const sessionId of abandoned.sessionIds) {const socket = this.socketsBySessionId.get(sessionId);if (!socket) {@@ -1378,6 +1493,7 @@ export class SignalingServer {}this.qualitySettingsByRoom.delete(expired.roomId);this.shareGenerationsByRoom.delete(expired.roomId);+ this.pausedShareGenerationsByRoom.delete(expired.roomId);for (const sessionId of expired.sessionIds) {const socket = this.socketsBySessionId.get(sessionId);if (!socket) {@@ -1464,6 +1580,21 @@ export class SignalingServer {return;}+ const connectedViewers = this.options.roomStore.getConnectedViewers(roomId);+ const currentSessions = new Map(+ connectedViewers.map((viewer) => [viewer.peerId, viewer.sessionId]),+ );+ const readyByViewer = this.viewerMediaReadyByRoom.get(roomId);+ if (readyByViewer) {+ for (const [viewerPeerId, ready] of readyByViewer) {+ if (currentSessions.get(viewerPeerId) !== ready.sessionId) {+ readyByViewer.delete(viewerPeerId);+ }+ }+ if (readyByViewer.size === 0) {+ this.viewerMediaReadyByRoom.delete(roomId);+ }+ }const viewers: ParticipantPresenceEntry[] = [];const host = this.options.roomStore.getConnectedHost(roomId);const hostSocket = host@@ -1488,7 +1619,7 @@ export class SignalingServer {});}- for (const viewer of this.options.roomStore.getConnectedViewers(roomId)) {+ for (const viewer of connectedViewers) {const viewerSocket = this.socketsBySessionId.get(viewer.sessionId);const viewerState = viewerSocket? this.socketStates.get(viewerSocket)?.authenticated@@ -1501,27 +1632,42 @@ export class SignalingServer {) {continue;}+ const upstream = this.isHybridMediaEnabled()+ ? this.hybridMediaRouter!.getViewerRouteUpstream(roomId, viewer.peerId)+ : host+ ? { kind: "peer" as const, peerId: host.peerId }+ : { kind: "none" as const };+ const ready = readyByViewer?.get(viewer.peerId);+ const sfuMediaReady =+ upstream.kind === "sfu" &&+ ready?.sessionId === viewer.sessionId &&+ this.hybridMediaRouter!.viewerSfuMediaStateIsCurrent(+ roomId,+ viewer.peerId,+ ready.revision,+ ready.sfuPublicationGeneration,+ );+ if (ready && !sfuMediaReady) {+ readyByViewer?.delete(viewer.peerId);+ }viewers.push({role: "viewer",peerId: viewer.peerId,displayName: viewerState.displayName,- upstream: this.isHybridMediaEnabled()- ? this.hybridMediaRouter!.getViewerRouteUpstream(- roomId,- viewer.peerId,- )- : host- ? { kind: "peer", peerId: host.peerId }- : { kind: "none" },+ upstream,+ ...(sfuMediaReady ? { sfuMediaReady: true as const } : {}),});}+ if (readyByViewer?.size === 0) {+ this.viewerMediaReadyByRoom.delete(roomId);+ }const message = { type: "viewer-presence" as const, viewers };const recipients = new Set<WebSocket>();if (hostSocket && hostState?.viewerPresence) {recipients.add(hostSocket);}- for (const viewer of this.options.roomStore.getConnectedViewers(roomId)) {+ for (const viewer of connectedViewers) {const viewerSocket = this.socketsBySessionId.get(viewer.sessionId);const viewerState = viewerSocket? this.socketStates.get(viewerSocket)?.authenticated@@ -1539,6 +1685,44 @@ export class SignalingServer {recipients.forEach((socket) => this.send(socket, message));}+ private updateViewerMediaState(+ roomId: string,+ viewerPeerId: string,+ viewerSessionId: string,+ revision: number,+ sfuPublicationGeneration: string,+ ready: boolean,+ ): void {+ let readyByViewer = this.viewerMediaReadyByRoom.get(roomId);+ if (ready) {+ readyByViewer ??= new Map<string, ViewerMediaReadyState>();+ readyByViewer.set(viewerPeerId, {+ sessionId: viewerSessionId,+ revision,+ sfuPublicationGeneration,+ });+ this.viewerMediaReadyByRoom.set(roomId, readyByViewer);+ } else {+ if (!readyByViewer) {+ return;+ }+ const current = readyByViewer.get(viewerPeerId);+ if (+ !current ||+ current.sessionId !== viewerSessionId ||+ current.revision !== revision ||+ current.sfuPublicationGeneration !== sfuPublicationGeneration+ ) {+ return;+ }+ readyByViewer.delete(viewerPeerId);+ if (readyByViewer.size === 0) {+ this.viewerMediaReadyByRoom.delete(roomId);+ }+ }+ this.sendViewerPresence(roomId);+ }+private sendToSession(sessionId: string, message: ServerMessage): void {const socket = this.socketsBySessionId.get(sessionId);if (socket) {@@ -1617,6 +1801,7 @@ export class SignalingServer {}private clearRoomConnectionIds(roomId: string): void {+ this.viewerMediaReadyByRoom.delete(roomId);const prefix = `${roomId}:`;for (const key of this.connectionIdsByViewer.keys()) {if (key.startsWith(prefix)) {diff --git a/src/shared/protocol.ts b/src/shared/protocol.tsindex 76bbb713..c1df3314 100644--- a/src/shared/protocol.ts+++ b/src/shared/protocol.ts@@ -5,7 +5,7 @@ import { isCanonicalVideoCodecEvidence } from "./video-codec-evidence.js";export const MAX_VIEWERS_PER_ROOM_LIMIT = 16;export const MAX_PARTICIPANTS_PER_ROOM_LIMIT = MAX_VIEWERS_PER_ROOM_LIMIT + 1;export const MAX_SIGNAL_BYTES = 64 * 1024;-export const SIGNALING_PROTOCOL = "screener-v3";+export const SIGNALING_PROTOCOL = "screener-v4";export const ROOM_CODE_LENGTH = 12;export const MAX_MEDIA_ROUTE_REVISION = Number.MAX_SAFE_INTEGER;export const MAX_SFU_TOKEN_LENGTH = 8 * 1024;@@ -84,6 +84,7 @@ export const participantPresenceEntrySchema = z.discriminatedUnion("role", [peerId: opaqueIdSchema,displayName: displayNameSchema,upstream: mediaRouteUpstreamSchema,+ sfuMediaReady: z.literal(true).optional(),}).strict(),]);@@ -97,6 +98,7 @@ export const viewerPresenceEntrySchema = zpeerId: opaqueIdSchema,displayName: displayNameSchema,upstream: mediaRouteUpstreamSchema,+ sfuMediaReady: z.literal(true).optional(),}).strict();export type ViewerPresenceEntry = z.infer<typeof viewerPresenceEntrySchema>;@@ -495,6 +497,7 @@ const authenticateMessageSchema = z.discriminatedUnion("role", [token: tokenSchema,clientId: opaqueIdSchema,shareGeneration: opaqueIdSchema.optional(),+ sharingPaused: z.boolean().optional(),viewerPresence: z.literal(true).optional(),viewerPasswordSettings: z.literal(true).optional(),displayName: displayNameSchema.optional(),@@ -557,6 +560,12 @@ export const clientMessageSchema = z.union([phase: mediaRoutePhaseSchema,}).strict(),+ z+ .object({+ type: z.literal("route-media-unavailable"),+ revision: mediaRouteRevisionSchema,+ })+ .strict(),z.object({type: z.literal("route-failed"),@@ -591,6 +600,13 @@ export const clientMessageSchema = z.union([password: viewerPasswordSchema.nullable(),}).strict(),+ z+ .object({+ type: z.literal("set-sharing-paused"),+ shareGeneration: opaqueIdSchema,+ paused: z.boolean(),+ })+ .strict(),z.object({type: z.literal("stop-sharing"),@@ -621,6 +637,7 @@ const authenticatedMessageShape = {roomExpiresAt: z.string().datetime().nullable(),maxViewers: z.number().int().min(1).max(MAX_VIEWERS_PER_ROOM_LIMIT),hostOnline: z.boolean(),+ hostPaused: z.boolean().optional(),connectionId: opaqueIdSchema.nullable(),viewerPeerIds: z.array(opaqueIdSchema).max(MAX_VIEWERS_PER_ROOM_LIMIT),iceConfig: iceConfigSchema,@@ -744,6 +761,7 @@ export const serverMessageSchema = z.union([.object({type: z.literal("host-status"),online: z.boolean(),+ paused: z.boolean(),}).strict(),zdiff --git a/tests/client-state.test.ts b/tests/client-state.test.tsindex 0396cd37..c9b6c62e 100644--- a/tests/client-state.test.ts+++ b/tests/client-state.test.ts@@ -27,7 +27,10 @@ import {SignalingClient,} from "../src/client/lib/signaling.ts";import { deriveParticipantTopology } from "../src/client/lib/participant-topology.ts";-import { labelViewerPresence } from "../src/client/lib/viewer-presence.ts";+import {+ labelViewerParticipants,+ labelViewerPresence,+} from "../src/client/lib/viewer-presence.ts";import { qualityEvidenceWindowFromMetrics } from "../src/client/media/viewer-quality-evidence.ts";import { createStatsAccumulator, collectConnectionMetrics } from "../src/client/webrtc/stats.ts";@@ -81,9 +84,84 @@ describe("browser-local display name", () => {expect(labeled[1].peerIdSuffix.length).toBeGreaterThan(6);expect(labeled[0].peerIdSuffix).not.toBe(labeled[1].peerIdSuffix);expect(labeled[2].peerIdSuffix).toHaveLength(6);+ expect(labeled[2].label).toBe("朋友");expect(labeled[0].label).toContain("同名 (");});+ it("keeps the shortest hidden suffix for distinct display names", () => {+ const labeled = labelViewerPresence([+ {+ role: "viewer",+ peerId: "viewer_AAAAAAsuffix",+ displayName: "甲",+ upstream: { kind: "sfu" },+ },+ {+ role: "viewer",+ peerId: "viewer_BBBBBBsuffix",+ displayName: "乙",+ upstream: { kind: "sfu" },+ },+ ]);++ expect(labeled.map((viewer) => viewer.label)).toEqual(["甲", "乙"]);+ expect(labeled.map((viewer) => viewer.peerIdSuffix.length)).toEqual([6, 6]);+ });++ it("uses the minimum suffix when duplicate names are already distinct", () => {+ const labeled = labelViewerPresence([+ {+ role: "viewer",+ peerId: "viewer_AAAAAA111111",+ displayName: "同名",+ upstream: { kind: "none" },+ },+ {+ role: "viewer",+ peerId: "viewer_BBBBBB222222",+ displayName: "同名",+ upstream: { kind: "none" },+ },+ ]);++ expect(labeled.map((viewer) => viewer.peerIdSuffix)).toEqual([+ "111111",+ "222222",+ ]);+ expect(labeled.map((viewer) => viewer.label)).toEqual([+ "同名 (111111)",+ "同名 (222222)",+ ]);+ });++ it("labels every Viewer in a participant snapshot without including the Host", () => {+ const labeled = labelViewerParticipants([+ {+ role: "host",+ peerId: "host_12345678",+ displayName: "分享者",+ upstream: { kind: "none" },+ },+ {+ role: "viewer",+ peerId: "viewer_111111",+ displayName: "朋友甲",+ upstream: { kind: "peer", peerId: "host_12345678" },+ },+ {+ role: "viewer",+ peerId: "viewer_222222",+ displayName: "朋友乙",+ upstream: { kind: "sfu" },+ },+ ]);++ expect(labeled.map((viewer) => viewer.label)).toEqual([+ "朋友甲",+ "朋友乙",+ ]);+ });+it("derives exact peer and SFU branches without guessing orphaned routes", () => {const viewer = (peerId: string,@@ -541,7 +619,7 @@ describe("client signaling recovery policy", () => {JSON.parse(String(sockets[0]!.send.mock.calls[0]![0])),).toMatchObject({type: "authenticate",- protocol: "screener-v3",+ protocol: "screener-v4",});const message = new Event("message");Object.defineProperty(message, "data", { value: payload });diff --git a/tests/protocol.test.ts b/tests/protocol.test.tsindex 7a2448aa..a2aede69 100644--- a/tests/protocol.test.ts+++ b/tests/protocol.test.ts@@ -1,3 +1,6 @@+import { readFileSync } from "node:fs";+import { join } from "node:path";+import { describe, expect, it } from "vitest";import {@@ -72,6 +75,20 @@ const parentEdgeQualityEvidence = {} as const;describe("client signaling protocol", () => {+ it("keeps the Native sender on the same signaling version", () => {+ const nativeWire = readFileSync(+ join(+ import.meta.dirname,+ "../native/sender/internal/remote/wire.go",+ ),+ "utf8",+ );++ expect(nativeWire).toContain(+ `signalingProtocol = "${SIGNALING_PROTOCOL}"`,+ );+ });+it("accepts only the fixed provisional Host lease", () => {expect(createRoomRequestSchema.parse({ viewerPolicy: "private-link" }),@@ -146,7 +163,7 @@ describe("client signaling protocol", () => {expect(clientMessageSchema.safeParse({type: "authenticate",- protocol: "screener-v2",+ protocol: "screener-v3",roomId,role: "viewer",clientId: "client_12345678",@@ -407,6 +424,33 @@ describe("client signaling protocol", () => {);});+ it("keeps intentional pause updates strict and generation-bound", () => {+ const update = {+ type: "set-sharing-paused",+ shareGeneration: "share_generation_12345678",+ paused: true,+ };+ expect(clientMessageSchema.safeParse(update).success).toBe(true);+ expect(+ clientMessageSchema.safeParse({ ...update, shareGeneration: undefined })+ .success,+ ).toBe(false);+ expect(+ clientMessageSchema.safeParse({ ...update, paused: "true" }).success,+ ).toBe(false);+ expect(+ serverMessageSchema.safeParse({+ type: "host-status",+ online: true,+ paused: true,+ }).success,+ ).toBe(true);+ expect(+ serverMessageSchema.safeParse({ type: "host-status", online: true })+ .success,+ ).toBe(false);+ });+it("accepts only strict, bounded quality settings", () => {expect(clientMessageSchema.safeParse({@@ -634,6 +678,12 @@ describe("client signaling protocol", () => {phase: "prepare",}).success,).toBe(true);+ expect(+ clientMessageSchema.safeParse({+ type: "route-media-unavailable",+ revision: 7,+ }).success,+ ).toBe(true);expect(clientMessageSchema.safeParse({type: "route-failed",@@ -656,6 +706,12 @@ describe("client signaling protocol", () => {phase: "prepare",}).success,).toBe(false);+ expect(+ clientMessageSchema.safeParse({+ type: "route-media-unavailable",+ revision: -1,+ }).success,+ ).toBe(false);expect(clientMessageSchema.safeParse({type: "route-failed",@@ -761,9 +817,21 @@ describe("server signaling protocol", () => {expect(serverMessageSchema.safeParse({type: "viewer-presence",- viewers: [viewer],+ viewers: [+ {+ ...viewer,+ upstream: { kind: "sfu" },+ sfuMediaReady: true,+ },+ ],}).success,).toBe(true);+ expect(+ serverMessageSchema.safeParse({+ type: "viewer-presence",+ viewers: [{ ...viewer, sfuMediaReady: false }],+ }).success,+ ).toBe(false);expect(serverMessageSchema.safeParse({type: "viewer-presence",diff --git a/tests/route-transition.test.ts b/tests/route-transition.test.tsindex ce4b3abd..27f5b508 100644--- a/tests/route-transition.test.ts+++ b/tests/route-transition.test.ts@@ -1161,13 +1161,17 @@ describe("ViewerSfuRoute", () => {it("retries a sticky authoritative SFU route only after stable decoded RTP", async () => {const healthy: number[] = [];+ const messages: ClientMessage[] = [];let subscriber!: ReturnType<typeof createFakeSubscriber>;const route = new ViewerSfuRoute({activatePeer: () => undefined,reconcileSfuChildren: () => undefined,onSfuStream: () => undefined,onHealthySfu: (revision) => healthy.push(revision),- send: () => true,+ send: (message) => {+ messages.push(message);+ return true;+ },createSubscriber: (events) => {subscriber = createFakeSubscriber(events, [], "subscriber");return subscriber;@@ -1182,7 +1186,17 @@ describe("ViewerSfuRoute", () => {route.armHealthySfuReselection(7);await route.acceptConfig(sfuConfig(7));await vi.waitFor(() => expect(subscriber.activate).toHaveBeenCalledOnce());+ expect(messages).not.toContainEqual({+ type: "route-ready",+ revision: 7,+ phase: "active",+ });subscriber.events.onStream({} as MediaStream);+ expect(messages).toContainEqual({+ type: "route-ready",+ revision: 7,+ phase: "active",+ });subscriber.events.onStats?.({intervalPacketsReceived: 4,intervalFramesDecoded: 0,@@ -1205,7 +1219,7 @@ describe("ViewerSfuRoute", () => {expect(healthy).toEqual([7]);});- it("switches on first SFU video and forwards loss across SFU revision reuse", async () => {+ it("switches on first SFU video and forwards loss across same-publication revision reuse", async () => {const log: string[] = [];const messages: ClientMessage[] = [];const peerAssignments: ParticipantRouteAssignment[] = [];@@ -1302,16 +1316,40 @@ describe("ViewerSfuRoute", () => {subscribers[0]?.events.onVideoAvailability?.(false);subscribers[0]?.events.onVideoAvailability?.(true);expect(videoAvailability).toEqual([false, true]);+ expect(messages).toContainEqual({+ type: "route-media-unavailable",+ revision: 2,+ });+ expect(+ messages.filter(+ (message) =>+ message.type === "route-ready" &&+ message.revision === 2 &&+ message.phase === "active",+ ),+ ).toHaveLength(2);+ const revisionThreeAssignment = sfuAssignment(["other-child"]);route.accept({revision: 3,phase: "active",- assignment: sfuAssignment(["other-child"]),+ assignment: revisionThreeAssignment,});+ await vi.waitFor(() =>+ expect(messages).toContainEqual({+ type: "route-ready",+ revision: 3,+ phase: "active",+ }),+ );expect(subscribers).toHaveLength(1);expect(subscribers[0]?.deactivate).not.toHaveBeenCalled();subscribers[0]?.events.onVideoAvailability?.(false);expect(videoAvailability).toEqual([false, true, false]);+ expect(messages).toContainEqual({+ type: "route-media-unavailable",+ revision: 3,+ });route.accept({revision: 4,@@ -1327,6 +1365,11 @@ describe("ViewerSfuRoute", () => {await vi.waitFor(() => expect(subscribers[1]?.disconnect).toHaveBeenCalled());expect(subscribers[0]?.deactivate).not.toHaveBeenCalled();expect(streams).toHaveLength(1);+ expect(messages).not.toContainEqual({+ type: "route-ready",+ revision: 5,+ phase: "active",+ });await route.disconnect();expect(sfuUpdates).toEqual([metrics, null]);@@ -1338,6 +1381,92 @@ describe("ViewerSfuRoute", () => {expect(videoAvailability).toEqual([false, true, false]);});+ it("rebuilds an authoritative SFU route before proving a replaced publication", async () => {+ const log: string[] = [];+ const messages: ClientMessage[] = [];+ const resetMedia = vi.fn();+ const subscribers: ReturnType<typeof createFakeSubscriber>[] = [];+ const route = new ViewerSfuRoute({+ activatePeer: () => undefined,+ resetMedia,+ reconcileSfuChildren: () => undefined,+ onSfuStream: () => undefined,+ send: (message) => {+ messages.push(message);+ return true;+ },+ createSubscriber: (events) => {+ const subscriber = createFakeSubscriber(+ events,+ log,+ `subscriber-${subscribers.length + 1}`,+ );+ subscribers.push(subscriber);+ return subscriber;+ },+ });+ const assignment = sfuAssignment();++ route.accept({ revision: 1, phase: "prepare", assignment });+ await route.acceptConfig(sfuConfig(1));+ route.accept({ revision: 1, phase: "active", assignment });+ await vi.waitFor(() =>+ expect(subscribers[0]?.activate).toHaveBeenCalledOnce(),+ );+ subscribers[0]?.events.onStream({} as MediaStream);+ messages.length = 0;+ log.length = 0;++ await expect(+ route.resyncAuthoritative({+ revision: 2,+ phase: "active",+ assignment,+ }),+ ).resolves.toBe("accepted");++ expect(resetMedia).toHaveBeenCalledOnce();+ expect(log).toEqual([+ "subscriber-1:deactivate",+ "subscriber-1:disconnect",+ ]);+ expect(messages).not.toContainEqual({+ type: "route-ready",+ revision: 2,+ phase: "active",+ });++ await route.acceptConfig(sfuConfig(2));+ await vi.waitFor(() =>+ expect(subscribers[1]?.activate).toHaveBeenCalledOnce(),+ );+ expect(subscribers).toHaveLength(2);+ expect(messages).not.toContainEqual({+ type: "route-ready",+ revision: 2,+ phase: "active",+ });++ subscribers[1]?.events.onStream({} as MediaStream);+ expect(messages).toContainEqual({+ type: "route-ready",+ revision: 2,+ phase: "active",+ });++ messages.length = 0;+ route.accept({ revision: 3, phase: "active", assignment });+ await vi.waitFor(() =>+ expect(messages).toContainEqual({+ type: "route-ready",+ revision: 3,+ phase: "active",+ }),+ );+ expect(subscribers).toHaveLength(2);+ expect(subscribers[1]?.deactivate).not.toHaveBeenCalled();+ });+it("disconnects a subscriber whose connect completes after rollback", async () => {let finishConnect!: () => void;const connectGate = new Promise<void>((resolve) => {diff --git a/tests/server-signal.test.ts b/tests/server-signal.test.tsindex 3d47c118..342ea269 100644--- a/tests/server-signal.test.ts+++ b/tests/server-signal.test.ts@@ -445,6 +445,7 @@ async function authenticate(viewerPresence?: true;viewerPasswordSettings?: true;viewerPassword?: string;+ sharingPaused?: boolean;} = {},) {client.socket.send(@@ -458,6 +459,9 @@ async function authenticate(token: room.hostToken,clientId,...(shareGeneration ? { shareGeneration } : {}),+ ...(presence.sharingPaused !== undefined+ ? { sharingPaused: presence.sharingPaused }+ : {}),...(presence.viewerPresence ? { viewerPresence: true } : {}),...(presence.viewerPasswordSettings? { viewerPasswordSettings: true }@@ -696,10 +700,19 @@ async function failSingleViewerDirect(webSocketUrl: string,room: CreatedRoom,prefix: string,+ hostPresence = false,) {const host = await openClient(webSocketUrl);const hostAuth = peerAssisted(- await authenticate(host, room, "host", `${prefix}-host`, 1, `${prefix}-share`),+ await authenticate(+ host,+ room,+ "host",+ `${prefix}-host`,+ 1,+ `${prefix}-share`,+ hostPresence ? { viewerPresence: true } : {},+ ),);const viewer = await openClient(webSocketUrl);const viewerAuth = peerAssisted(@@ -729,8 +742,14 @@ async function activateSingleViewerSfu(webSocketUrl: string,room: CreatedRoom,prefix: string,+ hostPresence = false,) {- const direct = await failSingleViewerDirect(webSocketUrl, room, prefix);+ const direct = await failSingleViewerDirect(+ webSocketUrl,+ room,+ prefix,+ hostPresence,+ );const { host, viewer } = direct;const hostPrepare = await nextPreparedRoute(host);const viewerPrepare = await nextPreparedRoute(viewer);@@ -1263,6 +1282,55 @@ describe("WebSocket signaling", () => {expect(hostPresenceEntry(renamedHost)?.peerId).toBe(hostAuth.peerId);});+ it("replaces an opted-in Viewer roster after another Viewer leaves", async () => {+ const harness = await startHarness();+ const host = await openClient(harness.webSocketUrl);+ await authenticate(host, harness.room, "host", "viewer-roster-host");++ const subscriber = await openClient(harness.webSocketUrl);+ const subscriberAuth = await authenticate(+ subscriber,+ harness.room,+ "viewer",+ "viewer-roster-subscriber",+ 1,+ undefined,+ { viewerPresence: true, displayName: "订阅者" },+ );+ await nextViewerPresenceMatching(+ subscriber,+ (message) => viewerPresenceEntries(message).length === 1,+ );++ const other = await openClient(harness.webSocketUrl);+ const otherAuth = await authenticate(+ other,+ harness.room,+ "viewer",+ "viewer-roster-other",+ 1,+ undefined,+ { displayName: "另一位" },+ );+ const joined = await nextViewerPresenceMatching(+ subscriber,+ (message) => viewerPresenceEntries(message).length === 2,+ );+ expect(viewerPresenceEntries(joined).map((viewer) => viewer.peerId)).toEqual([+ subscriberAuth.peerId,+ otherAuth.peerId,+ ]);++ await closeClient(other);+ const left = await nextViewerPresenceMatching(+ subscriber,+ (message) => viewerPresenceEntries(message).length === 1,+ );+ expect(viewerPresenceEntries(left).map((viewer) => viewer.peerId)).toEqual([+ subscriberAuth.peerId,+ ]);+ });+it("clears a disconnected Host name and publishes the replacement name", async () => {const harness = await startHarness({ viewerDisconnectGraceMs: 40 });const firstHost = await openClient(harness.webSocketUrl);@@ -1847,6 +1915,124 @@ describe("WebSocket signaling", () => {expect(await viewer.inbox.next("host-status")).toEqual({type: "host-status",online: true,+ paused: false,+ });+ });++ it("snapshots intentional pause across Viewer replacement and clears it on resume and stop", async () => {+ const harness = await startHarness();+ const shareGeneration = "pause_share_generation_12345678";+ const host = await openClient(harness.webSocketUrl);+ let activeHost = host;+ const hostAuth = await authenticate(+ host,+ harness.room,+ "host",+ "pause-host-client",+ 1,+ shareGeneration,+ );+ expect(hostAuth).not.toHaveProperty("hostPaused");+ const viewer = await openClient(harness.webSocketUrl);+ const viewerAuth = await authenticate(+ viewer,+ harness.room,+ "viewer",+ "pause-viewer-client",+ );+ expect(viewerAuth.hostPaused).toBe(false);+ await host.inbox.next("peer-joined");++ host.socket.send(+ JSON.stringify({+ type: "set-sharing-paused",+ shareGeneration,+ paused: true,+ }),+ );+ expect(await viewer.inbox.next("host-status")).toEqual({+ type: "host-status",+ online: true,+ paused: true,+ });++ await closeClient(host);+ expect(await viewer.inbox.next("host-status")).toMatchObject({+ online: false,+ paused: false,+ });+ activeHost = await openClient(harness.webSocketUrl);+ await authenticate(+ activeHost,+ harness.room,+ "host",+ "pause-host-client",+ 1,+ shareGeneration,+ { sharingPaused: true },+ );+ expect(await viewer.inbox.next("host-status")).toMatchObject({+ online: true,+ paused: true,+ });++ const replacement = await openClient(harness.webSocketUrl);+ const replacementAuth = await authenticate(+ replacement,+ harness.room,+ "viewer",+ "pause-viewer-client",+ );+ expect(replacementAuth.hostPaused).toBe(true);++ activeHost.socket.send(+ JSON.stringify({+ type: "set-sharing-paused",+ shareGeneration,+ paused: false,+ }),+ );+ expect(await replacement.inbox.next("host-status")).toMatchObject({+ online: true,+ paused: false,+ });++ activeHost.socket.send(+ JSON.stringify({+ type: "set-sharing-paused",+ shareGeneration,+ paused: true,+ }),+ );+ expect(await replacement.inbox.next("host-status")).toMatchObject({+ paused: true,+ });+ activeHost.socket.send(+ JSON.stringify({ type: "stop-sharing", shareGeneration }),+ );+ await replacement.inbox.next("sharing-stopped");+ expect(await replacement.inbox.next("host-status")).toMatchObject({+ online: false,+ paused: false,+ });++ const nextHost = await openClient(harness.webSocketUrl);+ await authenticate(+ nextHost,+ harness.room,+ "host",+ "pause-host-client",+ 1,+ "next_pause_share_generation_12345678",+ );+ await replacement.inbox.next("sharing-stopped");+ expect(await replacement.inbox.next("host-status")).toMatchObject({+ online: false,+ paused: false,+ });+ expect(await replacement.inbox.next("host-status")).toMatchObject({+ online: true,+ paused: false,});});@@ -3778,6 +3964,235 @@ describe("WebSocket signaling", () => {await foreignViewer.inbox.expectNone(30);});+ it("ignores SFU media assertions on an active peer route", async () => {+ const harness = await startSfuHarness({+ tokenIssuer: {+ issueToken: async ({ peerId }) => `token-${peerId}`,+ },+ });+ const host = await openClient(harness.webSocketUrl);+ const hostAuth = peerAssisted(+ await authenticate(+ host,+ harness.room,+ "host",+ "peer-media-state-host",+ 1,+ "peer-media-state-share",+ { viewerPresence: true },+ ),+ );+ const viewer = await openClient(harness.webSocketUrl);+ const viewerAuth = peerAssisted(+ await authenticate(+ viewer,+ harness.room,+ "viewer",+ "peer-media-state-viewer",+ ),+ );+ expect(viewerAuth.routeAssignment.upstream.kind).toBe("peer");++ for (const message of [+ {+ type: "route-ready",+ revision: viewerAuth.routeRevision,+ phase: "active",+ },+ {+ type: "route-media-unavailable",+ revision: viewerAuth.routeRevision,+ },+ ]) {+ viewer.socket.send(JSON.stringify(message));+ }++ const replacementHost = await openClient(harness.webSocketUrl);+ const replacementAuth = peerAssisted(+ await authenticate(+ replacementHost,+ harness.room,+ "host",+ "peer-media-state-host",+ 1,+ "peer-media-state-share",+ { viewerPresence: true },+ ),+ );+ expect(replacementAuth.peerId).toBe(hostAuth.peerId);+ const presence = await nextViewerPresenceMatching(+ replacementHost,+ (message) =>+ viewerPresenceEntries(message).some(+ (entry) => entry.peerId === viewerAuth.peerId,+ ),+ );+ expect(+ viewerPresenceEntries(presence).find(+ (entry) => entry.peerId === viewerAuth.peerId,+ ),+ ).toMatchObject({ upstream: viewerAuth.routeAssignment.upstream });+ expect(+ viewerPresenceEntries(presence).find(+ (entry) => entry.peerId === viewerAuth.peerId,+ )?.sfuMediaReady,+ ).toBeUndefined();+ });++ it("reports and revokes current SFU Viewer media readiness", async () => {+ const harness = await startSfuHarness({+ tokenIssuer: {+ issueToken: async ({ peerId }) => `token-${peerId}`,+ },+ });+ const active = await activateSingleViewerSfu(+ harness.webSocketUrl,+ harness.room,+ "sfu-media-ready",+ true,+ );+ const findViewer = (+ message: Extract<ServerMessage, { type: "viewer-presence" }>,+ ) =>+ viewerPresenceEntries(message).find(+ (entry) => entry.peerId === active.viewerAuth.peerId,+ );+ const initiallyUnready = await nextViewerPresenceMatching(+ active.host,+ (message) => findViewer(message)?.upstream.kind === "sfu",+ );+ expect(findViewer(initiallyUnready)?.sfuMediaReady).toBeUndefined();++ active.viewer.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: active.revision - 1,+ phase: "active",+ }),+ );+ const replacementHost = await openClient(harness.webSocketUrl);+ await authenticate(+ replacementHost,+ harness.room,+ "host",+ "sfu-media-ready-host",+ 1,+ "sfu-media-ready-share",+ { viewerPresence: true },+ );+ const afterStaleReady = await nextViewerPresenceMatching(+ replacementHost,+ (message) => findViewer(message)?.upstream.kind === "sfu",+ );+ expect(findViewer(afterStaleReady)?.sfuMediaReady).toBeUndefined();++ active.viewer.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: active.revision,+ phase: "active",+ }),+ );+ const ready = await nextViewerPresenceMatching(+ replacementHost,+ (message) => findViewer(message)?.sfuMediaReady === true,+ );+ expect(findViewer(ready)).toMatchObject({+ upstream: { kind: "sfu" },+ sfuMediaReady: true,+ });++ active.viewer.socket.send(+ JSON.stringify({+ type: "route-media-unavailable",+ revision: active.revision - 1,+ }),+ );+ const replayHost = await openClient(harness.webSocketUrl);+ await authenticate(+ replayHost,+ harness.room,+ "host",+ "sfu-media-ready-host",+ 1,+ "sfu-media-ready-share",+ { viewerPresence: true },+ );+ const replayed = await nextViewerPresenceMatching(+ replayHost,+ (message) => findViewer(message)?.sfuMediaReady === true,+ );+ expect(findViewer(replayed)?.sfuMediaReady).toBe(true);++ active.viewer.socket.send(+ JSON.stringify({+ type: "route-media-unavailable",+ revision: active.revision,+ }),+ );+ const unavailable = await nextViewerPresenceMatching(+ replayHost,+ (message) => {+ const viewer = findViewer(message);+ return viewer?.upstream.kind === "sfu" && !viewer.sfuMediaReady;+ },+ );+ expect(findViewer(unavailable)?.sfuMediaReady).toBeUndefined();++ active.viewer.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: active.revision,+ phase: "active",+ }),+ );+ await nextViewerPresenceMatching(+ replayHost,+ (message) => findViewer(message)?.sfuMediaReady === true,+ );++ const replacementViewer = await openClient(harness.webSocketUrl);+ const replacementViewerAuth = peerAssisted(+ await authenticate(+ replacementViewer,+ harness.room,+ "viewer",+ "sfu-media-ready-viewer",+ ),+ );+ expect(replacementViewerAuth).toMatchObject({+ peerId: active.viewerAuth.peerId,+ routeRevision: active.revision,+ routeAssignment: { upstream: { kind: "sfu" } },+ });+ const afterViewerSessionChange = await nextViewerPresenceMatching(+ replayHost,+ (message) => {+ const viewer = findViewer(message);+ return viewer?.upstream.kind === "sfu" && !viewer.sfuMediaReady;+ },+ );+ expect(findViewer(afterViewerSessionChange)?.sfuMediaReady).toBeUndefined();++ replacementViewer.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: replacementViewerAuth.routeRevision,+ phase: "active",+ }),+ );+ await nextViewerPresenceMatching(+ replayHost,+ (message) => findViewer(message)?.sfuMediaReady === true,+ );++ await closeClient(replacementViewer);+ await nextViewerPresenceMatching(+ replayHost,+ (message) => findViewer(message) === undefined,+ );+ });+it("reparents failed peer edges before committing a bounded SFU fallback", async () => {const issued: Array<Parameters<SfuTokenIssuer["issueToken"]>[0]@@ -6878,7 +7293,7 @@ describe("WebSocket signaling", () => {oldClient.socket.send(JSON.stringify({type: "authenticate",- protocol: "screener-v2",+ protocol: "screener-v3",roomId: "999999999999",role: "viewer",clientId: "old-client",