Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
feat(presence): show named online viewer roster (#64)
AAA51a3022ae172
diff --git a/docs/README.md b/docs/README.mdindex a3f5b2fd..90987f29 100644--- a/docs/README.md+++ b/docs/README.md@@ -13,6 +13,7 @@- [Native shared-encode sender](./research/native-shared-encode-sender.md): consolidated Draft #16/#18/#22/#23/#25/#28 ladder, unclassified product-gate failure, staged revalidation, and stop line.- [Realtime quality adaptation](./research/realtime-quality-adaptation.md): correlated capture/send/receive diagnosis, production generation-rebuild gate, path-isolated dual representations, and bounded simulcast/Dynacast/SVC checks.- [Browser screen-audio quality](./research/browser-screen-audio-quality.md): capture/source compatibility, standard readback limits, Opus negotiation boundaries, and the retained no-control decision.+- [Display name and presence boundaries](./research/display-name-presence.md): browser-local storage failure behavior, Unicode normalization, control-character policy, and the Web-only presence capability boundary.- [Agent context governance research](./research/agent-context-governance.md): official Codex, Claude Code, Hermes Agent, and GitHub practices adopted by this repository.- [ADR-0001](./adr/0001-p2p-first-media-topology.md): accepted P2P-first media topology and its consequences.- [ADR-0002](./adr/0002-persistent-protected-rooms.md): Host admission, room-scoped private Viewer grants, explicit public-watch, rotation, and minimal SQLite persistence.diff --git a/docs/project-memory.md b/docs/project-memory.mdindex df8fb91f..c2e099f3 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -31,9 +31,9 @@ Last updated: 2026-08-20- 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.- Production reports poor film audio and self-echo when system capture includes voice software. Diagnose audio A/B/C and sync; Web cannot isolate arbitrary processes and `maxBitrate` is not quality-up. A Windows 11 native candidate defaults to game-process-tree audio and never widens silently; Windows 10 remains unresolved/unsupported. See `docs/research/browser-screen-audio-quality.md`.-- Candidate UI has local Viewer volume/mute, copyable room codes, and a favicon. Names/roster, endpoint details, and RTP loss remain pending; no wire, media, or routing effects.+- Candidate UI includes Viewer-local names and an opt-in Web Host online roster without changing media fanout. Host names, Viewer-side roster, endpoint details, and RTP loss remain pending.- Do not add scene detection, dynamic-FPS control, or forced AV1 without negotiation, encode, game, CPU/GPU, and sender evidence.-- ADR-0002 access is deployed: `HOST_ADMISSION_PASSWORD`, `screener-v2`, private grants/public-watch, rotate/revoke, and one nullable digest. No username/roster runtime.+- ADR-0002 access is deployed. Candidate names/presence are session-only and add no account, member, session, or roster table.- Deferred architecture audit: `docs/maintenance.md`.## Current Implementation@@ -51,7 +51,8 @@ Last updated: 2026-08-20- Source `main` at `f5d48ed` includes a memory-only Native v2 candidate, but production predates it and has no Native runtime gate. Render, hardware, two-edge/FIFO and TURN evidence remain absent.- Chrome 151 synthetic topology/quality-control runs kept fanout 2/1 and all viewers decoding; one relay close recovered in 5.32 seconds. This is control evidence only.- Room `1` publishes `HIGH+LOW` with Dynacast off and subscriber `HIGH` ceilings, and now has bounded local quality reparenting. Both remain unverified on real media; test zero-child leaves and calibrated C+B loss before broad rollout.-- Generation-bound C+B needs three hard-bad windows; parent samples are one-use per connection. Pending SFU binds intent/guard. Stale/successful peer work releases quality exclusion; real failure may take it over. No metadata/topology classification.+- Generation-bound C+B needs three hard-bad windows; parent samples are one-use per connection. Pending SFU binds intent/guard. Stale/successful peer work releases quality exclusion; real failure may take it over. It uploads no raw endpoint metadata and computes no score.+- The undeployed Web-only name/presence candidate leaves Native wire unchanged and keeps online Viewer sessions separate from Host media diagnostics; focused checks pass.## Provisional Quality Targetsdiff --git a/docs/research/display-name-presence.md b/docs/research/display-name-presence.mdnew file mode 100644index 00000000..a359ecdc--- /dev/null+++ b/docs/research/display-name-presence.md@@ -0,0 +1,13 @@+# Display name and presence boundaries++Accessed 2026-08-20. This note records only the browser and Unicode facts that constrain the local-name slice.++## Primary sources++- [WHATWG HTML: Web storage](https://html.spec.whatwg.org/multipage/webstorage.html#the-localstorage-attribute) defines `localStorage` as origin-scoped client storage. Access and writes may fail, so a display-name preference must remain optional and fall back without blocking room access.+- [ECMAScript: `String.prototype.normalize`](https://tc39.es/ecma262/multipage/text-processing.html#sec-string.prototype.normalize) provides explicit Unicode normalization. Screener uses NFC before applying its code-point limit and before sending the value.+- [Unicode UAX #31](https://www.unicode.org/reports/tr31/) documents normalization and the security concerns around invisible/default-ignorable and bidirectional controls. Display names are not identifiers, but rejecting controls and bidi overrides avoids misleading roster text while allowing ordinary multilingual labels and emoji.++## 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. A Web Host must opt in so the existing Native sender exact parser receives no new server message or field.diff --git a/docs/status.md b/docs/status.mdindex 542aa4ed..fac7c848 100644--- a/docs/status.md+++ b/docs/status.md@@ -25,6 +25,7 @@ also contains a no-go Native v2 candidate, but production does not run it.- 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` can publish exactly `HIGH+LOW` with Dynacast/backup codec off and subscriber `HIGH` ceilings; it has no retained real media frame.- Room `1` quality reparenting needs three C+B hard-bad pairs, reuses peer/SFU/failure and has one room cooldown; single-side reports do nothing. Thresholds need calibration.+- Source-only roster; Native wire/media unchanged.## Verified Evidencediff --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 df2378c0..46a1c364 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"@@ -94,7 +94,11 @@ rotate、revoke 或从 public-watch 切回 private-link 都是强撤销:服务客户端用 `sessionStorage` 保存随机的 128-bit `clientId`,作为当前标签页内稳定的参与者 key。同一 role/clientId 的新 WebSocket 会原子替换旧 socket;观看者断线后保留五秒 grace,期间不发送 `peer-left` 且 `peerId` 不变,重新鉴权时重发幂等的 `peer-joined`,超时才释放名额。host 鉴权或重连后,`authenticated` 携带包含 grace 成员的权威 viewer ID 列表供客户端删除已离开的 peer,服务端再重放当前在线观看者的 `peer-joined`,因此观看者可以先于 host 打开邀请,host 离线期间的离开也不会遗留幽灵连接。-显示名是独立的本地偏好:一个同源 `localStorage` 值供 Host 与 Viewer 共用,未设置时使用角色默认标签。客户端鉴权时发送经同一严格 schema 校验的纯文本名称,服务端只在当前在线房间内存中保存;每次加入、离开或会话替换后广播不超过一名 Host 加配置观看上限的完整权威 roster。展示标签使用名称加当前房间服务端 `peerId` 的至少六字符短后缀,房内碰撞时延长;不暴露 `clientId`,也不伪称全局 UUID。名称、短后缀和 roster 都不替代 role、Host token、Viewer grant、peer/session ID 或任何授权/路由判断,SQLite 不保存它们。该 UI/roster 实现保持为独立后续 PR,不混入授权迁移。+显示名是独立的本地偏好:同源 `localStorage` 只保存浏览器输入,存储不可用时静默退回内存 fallback;服务端只把 Viewer 的规范化名称挂在当前 authenticated socket state,断线即丢弃,不进入 RoomStore、SQLite 或日志。shared schema 先做 NFC、合并 Unicode space separators、去除边缘空格,再限制为 1 至 24 个 Unicode code points,并拒绝控制字符、行/段分隔符、BOM、双向控制符和孤立 surrogate;未设置时使用通用“访客”。普通多语言文本、组合字符和 emoji 仍可用。++Web Host 在 `authenticate` 中显式发送 `viewerPresence: true` capability;Native sender 和旧 Web Host 不发送,因此继续只收到原有 exact server wire。Viewer 可在 `authenticate.displayName` 发送名称,并以 `set-display-name` 更新当前会话。服务端只向已订阅的当前 Web Host 发送完整 `viewer-presence` snapshot,列表严格来自 RoomStore 当前带 sessionId 的在线 Viewer,不含五秒媒体恢复 grace 成员。加入、离线、会话替换、改名和 active route 改变都会重发快照;该只读广播不调用 connect/reconcile,也不建立任何媒体边。Host 的“在线”总数取 snapshot 长度,“Host 直连”取其中 active media topology 为 `host-direct` 的条目,最多两条的媒体 peer snapshot 只补充本机连接指标。++每个 presence 条目只有 `peerId`、`displayName` 和当前 active media topology:`host-direct`、`peer-relay`、`sfu` 或 `pending`。UI 始终展示名称加 peerId 尾部至少六字符短后缀;碰撞时逐字符有界延长至完整 peerId。peerId 不因此成为授权身份或路由输入。媒体拓扑标签使用“Host 直连 / Peer 中转 / SFU / 连接中”;ICE candidate path 单独使用“ICE 直连 / TURN 传输 / ICE 未知”,不能把 TURN transport 伪装成媒体拓扑。首个 slice 只实现 Viewer 本地改名和 Host 权威 Viewer roster,不上传或持久化 IP,也不改变 Host/Viewer 的授权、媒体或路由状态机。## 信令协议@@ -104,8 +108,10 @@ WebSocket 使用无 query/fragment 的同源 `/signal`。upgrade 只记录 Host-| 方向 | 消息 | 作用 || --- | --- | --- |-| client -> server | `authenticate` | Host 以 upgrade 时的 admission 状态加 room-scoped Host token 建立会话;Viewer 以 public room code 或 private Viewer grant 建立仅观看会话 |+| client -> server | `authenticate` | Host 以 upgrade 时的 admission 状态加 room-scoped Host token 建立会话,并可显式订阅 Web-only viewer presence;Viewer 以 public room code 或 private Viewer grant 建立仅观看会话并可附带规范化本地显示名 || server -> client | `authenticated` | 返回角色、peerId、可为空的房间期限、容量、host 状态、该 viewer 的历史 connectionId、host 的权威 viewer 列表和 ICE 配置 |+| viewer -> server | `set-display-name` | 只更新该 Viewer 当前 authenticated socket state 的规范化名称,不写房间或数据库状态 |+| server -> subscribed Web host | `viewer-presence` | 返回全部当前在线 Viewer 的权威 snapshot 与只读 active media topology;不触发媒体连接 || host -> server -> host | `set-viewer-access` / `viewer-access-updated` | Host 切换 public/private、rotate 或 revoke;raw grant 只在新建、rotate 或 public-to-private 成功响应中出现一次 || server -> host | `peer-joined` / `peer-left` | 建立或关闭该观看者的独立连接 || host -> viewer | `offer` / `candidate` | 带 `peerId` 与 `connectionId` 的定向信令 |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 11a163a5..be0eb553 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"@@ -18,7 +18,7 @@- [ ] 屏幕采集:分享者可主动选择显示器或应用窗口,开始、停止、临时暂停画面和切换分享来源。Host 本地预览必须直接使用 capture stream,不得为预览建立 viewer/媒体边或消耗 TURN、SFU、应用服务器 media egress;预览仍可能产生本地合成、缩放和 GPU 显示成本,不能把隐藏预览称为停止采集或编码。- [ ] 游戏声音:Windows Chrome/Edge 目标环境可请求系统音频;没有返回音轨时必须明确提示,而不是静默无声。- [ ] 观看端本地音量:播放控制栏提供 `0%` 至 `100%` 音量条和静音按钮,只改变当前浏览器的媒体元素,不修改 Host 音轨、编码、房间状态或其他观看者。切流、换父和 ICE 恢复保留当前页面内的值;刷新后不持久化。静音保留上次非零音量,拖动到非零值自动取消静音。-- [ ] 本地显示名与房间成员:用户可设置一个保存在当前浏览器 `localStorage` 的显示名;信令只在当前在线会话内保存和广播经严格长度/字符校验的纯文本标签,不写 SQLite。Host 页面显示“{分享者显示名} 的房间”,Host 与 Viewer 都看到包含分享者和当前观看者的权威 roster;展示身份使用“名称 + 当前房间 `peerId` 的短后缀”,短后缀碰撞时延长。显示名、后缀和 `clientId` 都不是账号、授权身份或全局 UUID,重复名称允许且不得参与授权、路由或质量决策。+- [ ] 本地显示名与房间成员:用户可设置一个只保存在当前浏览器同源 `localStorage` 的显示名;信令只在当前在线 socket 会话内保存和广播 NFC 规范化、最多 24 个 Unicode code points、拒绝控制/换行/双向覆盖符与孤立 surrogate 的纯文本标签,不写 SQLite 或日志。空值使用通用角色 fallback。Host 必须看到全部当前在线 Viewer 的权威总数与 roster,不能拿最多两条 Host 媒体直连数冒充在线人数;presence 更新也不得创建媒体连接。展示身份使用“名称 + 当前房间 `peerId` 的至少六字符短后缀”,房内碰撞时有界延长。显示名、后缀和 `clientId` 都不是账号、授权身份或全局 UUID,重复名称允许且不得参与授权、路由或质量决策。首个独立 slice 交付 Viewer 本地改名与 Viewer -> Host roster;Host 名称及 Viewer 侧完整 roster 留在同一需求的后续 slice。- [ ] 一对多观看:当前安全默认上限为 8、可配置范围为 1 至 16;自动分布式拓扑验收后,同一 release 将默认值和上限改为 20。当前 PoC 的逐观看者连接是测量基线,不再是超过两名观看者时的目标拓扑;未通过 20 人门禁时继续明确拒绝超额加入。- [ ] 端点 fanout 硬上限:任一非服务器端点任何时刻最多维护两条 active downstream media edges,包括加入、断线、换父和恢复过程;上游接收不计入这项上传预算。当前 browser relay 因逐跳重编码仍保守限制为一个 child,只有资源矩阵通过后才可升到二。第三名及后续观看者由系统自动分配给通过验收的 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 的实验门槛。diff --git a/src/client/components/StatusBadge.tsx b/src/client/components/StatusBadge.tsxindex 4459061f..153a180d 100644--- a/src/client/components/StatusBadge.tsx+++ b/src/client/components/StatusBadge.tsx@@ -1,4 +1,5 @@import { CircleAlert, Radio, Wifi, WifiOff } from "lucide-react";+import type { ViewerMediaTopology } from "../../shared/protocol";import type {MediaPath,SignalConnectionState,@@ -55,7 +56,7 @@ export function PathBadge({ path }: { path: MediaPath }) {return (<span className="path-badge path-direct" title="媒体未经过 TURN 中继"><Wifi size={14} aria-hidden="true" />- P2P 直连+ ICE 直连</span>);}@@ -63,18 +64,32 @@ export function PathBadge({ path }: { path: MediaPath }) {return (<span className="path-badge path-relay" title="此连接正在使用 TURN 中继"><Radio size={14} aria-hidden="true" />- TURN 中继+ TURN 传输</span>);}return (<span className="path-badge path-unknown" title="尚未选出可用的 ICE 路径"><WifiOff size={14} aria-hidden="true" />- 路径未知+ ICE 未知</span>);}+export function TopologyBadge({+ topology,+}: {+ topology: ViewerMediaTopology;+}) {+ const values: Record<ViewerMediaTopology, BadgeProps> = {+ "host-direct": { tone: "good", label: "Host 直连" },+ "peer-relay": { tone: "warning", label: "Peer 中转" },+ sfu: { tone: "warning", label: "SFU" },+ pending: { tone: "neutral", label: "连接中" },+ };+ return <Badge {...values[topology]} />;+}+export function WarningBanner({ children }: { children: React.ReactNode }) {return (<div className="notice notice-warning" role="status">diff --git a/src/client/lib/display-name.ts b/src/client/lib/display-name.tsnew file mode 100644index 00000000..8b2322ba--- /dev/null+++ b/src/client/lib/display-name.ts@@ -0,0 +1,43 @@+import {+ DEFAULT_VIEWER_DISPLAY_NAME,+ normalizeDisplayName,+ type DisplayName,+} from "../../shared/protocol";++const DISPLAY_NAME_STORAGE_KEY = "screener:display-name:v1";++export function readDisplayName(): DisplayName {+ try {+ const stored = window.localStorage.getItem(DISPLAY_NAME_STORAGE_KEY);+ if (!stored) {+ return DEFAULT_VIEWER_DISPLAY_NAME;+ }+ const normalized = normalizeDisplayName(stored);+ if (normalized === stored) {+ return normalized;+ }+ window.localStorage.removeItem(DISPLAY_NAME_STORAGE_KEY);+ } catch {+ // Restricted storage must not block joining a room.+ }+ return DEFAULT_VIEWER_DISPLAY_NAME;+}++export function saveDisplayName(value: string): DisplayName | null {+ const normalized = normalizeDisplayName(value);+ const useFallback = value.length === 0 || /^\p{Zs}+$/u.test(value);+ if (!normalized && !useFallback) {+ return null;+ }+ const displayName = normalized ?? DEFAULT_VIEWER_DISPLAY_NAME;+ try {+ if (useFallback) {+ window.localStorage.removeItem(DISPLAY_NAME_STORAGE_KEY);+ } else {+ window.localStorage.setItem(DISPLAY_NAME_STORAGE_KEY, displayName);+ }+ } catch {+ // The current signaling session can still use the in-memory value.+ }+ return displayName;+}diff --git a/src/client/lib/signaling.ts b/src/client/lib/signaling.tsindex 07ed9e62..99595187 100644--- a/src/client/lib/signaling.ts+++ b/src/client/lib/signaling.ts@@ -2,6 +2,7 @@ import {decodeServerMessage,SIGNALING_PROTOCOL,type ClientMessage,+ type DisplayName,type ServerMessage,} from "../../shared/protocol";import type { SignalConnectionState } from "../types";@@ -98,6 +99,14 @@ export class SignalingClient {return true;}+ setViewerDisplayName(displayName: DisplayName): boolean {+ if (this.identity.role !== "viewer") {+ return false;+ }+ this.identity.displayName = displayName;+ return this.send({ type: "set-display-name", displayName });+ }+sendThenStop(message: ClientMessage): void {if (this.stopped) {return;diff --git a/src/client/lib/viewer-presence.ts b/src/client/lib/viewer-presence.tsnew file mode 100644index 00000000..2400bcdd--- /dev/null+++ b/src/client/lib/viewer-presence.ts@@ -0,0 +1,50 @@+import type { ViewerPresenceEntry } from "../../shared/protocol";++export interface LabeledViewerPresence extends ViewerPresenceEntry {+ peerIdSuffix: string;+ label: string;+}++const MIN_PEER_ID_SUFFIX_LENGTH = 6;++export function labelViewerPresence(+ viewers: readonly ViewerPresenceEntry[],+): LabeledViewerPresence[] {+ const suffixLengths = viewers.map((viewer) =>+ Math.min(MIN_PEER_ID_SUFFIX_LENGTH, viewer.peerId.length),+ );++ while (true) {+ const collisions = new Map<string, number[]>();+ viewers.forEach((viewer, index) => {+ const suffix = viewer.peerId.slice(-suffixLengths[index]);+ const indexes = collisions.get(suffix) ?? [];+ indexes.push(index);+ collisions.set(suffix, indexes);+ });+ let extended = false;+ for (const indexes of collisions.values()) {+ if (indexes.length < 2) {+ continue;+ }+ for (const index of indexes) {+ if (suffixLengths[index] < viewers[index].peerId.length) {+ suffixLengths[index] += 1;+ extended = true;+ }+ }+ }+ if (!extended) {+ break;+ }+ }++ return viewers.map((viewer, index) => {+ const peerIdSuffix = viewer.peerId.slice(-suffixLengths[index]);+ return {+ ...viewer,+ peerIdSuffix,+ label: `${viewer.displayName} (${peerIdSuffix})`,+ };+ });+}diff --git a/src/client/pages/HostPage.tsx b/src/client/pages/HostPage.tsxindex b034820b..596c3dc8 100644--- a/src/client/pages/HostPage.tsx+++ b/src/client/pages/HostPage.tsx@@ -19,6 +19,7 @@ import {type IceConfig,type ServerMessage,type ViewerAccessPolicy,+ type ViewerPresenceEntry,} from "../../shared/protocol";import { AppHeader } from "../components/AppHeader";import { ConnectionDetailsToggle } from "../components/ConnectionDetailsToggle";@@ -28,6 +29,7 @@ import {PathBadge,PeerStatusBadge,SignalStatusBadge,+ TopologyBadge,WarningBanner,} from "../components/StatusBadge";import { StatsGrid } from "../components/StatsGrid";@@ -46,6 +48,7 @@ import {writeHostRoom,} from "../lib/session";import { SignalingClient } from "../lib/signaling";+import { labelViewerPresence } from "../lib/viewer-presence";import {applyCaptureProfile,captureDisplay,@@ -185,6 +188,9 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {const [peerSnapshots, setPeerSnapshots] = useState<Map<string, PeerSnapshot>>(() => new Map(),);+ const [viewerPresence, setViewerPresence] = useState<ViewerPresenceEntry[]>(+ [],+ );const [viewerQualityEvidence, setViewerQualityEvidence] = useState<Map<string, ViewerQualityEvidence>>(() => new Map());@@ -221,17 +227,28 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {const hostSfuRouteRef = useRef<HostSfuRoute | null>(null);const sfuStandbyPrewarmerRef = useRef<SfuStandbyPrewarmer | null>(null);- const viewers = useMemo(+ const mediaViewers = useMemo(() => Array.from(peerSnapshots.values()),[peerSnapshots],);+ const viewers = useMemo(+ () => labelViewerPresence(viewerPresence),+ [viewerPresence],+ );+ const hostDirectViewerCount = useMemo(+ () =>+ viewerPresence.filter(+ (viewer) => viewer.mediaTopology === "host-direct",+ ).length,+ [viewerPresence],+ );const selectedQualityProfileId = useMemo(() => matchingQualityProfileId(qualitySettings),[qualitySettings],);const qualityLimitation = useMemo(- () => qualityLimitationSummary(viewers),- [viewers],+ () => qualityLimitationSummary(mediaViewers),+ [mediaViewers],);useEffect(() => {@@ -363,6 +380,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {setDetails(null);setMaxViewers(null);setPeerSnapshots(new Map());+ setViewerPresence([]);viewerQualityEvidenceTimersRef.current.forEach((timer) =>window.clearTimeout(timer),);@@ -836,6 +854,10 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {);return;}+ if (message.type === "viewer-presence") {+ setViewerPresence(message.viewers);+ return;+ }if (message.type === "route-update") {if (peerAssistedRef.current) {if (@@ -1011,6 +1033,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {token: activeRoom.hostToken,clientId: getStableClientId("host", activeRoom.roomId),shareGeneration,+ viewerPresence: true,},{onStatus: (status) => {@@ -1294,7 +1317,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {</div><p className="section-meta">{phase === "live"- ? `${viewers.length}/${maxViewers ?? "-"} 人正在观看`+ ? `${viewers.length}/${maxViewers ?? "-"} 人在线 · ${hostDirectViewerCount} 条 Host 直连`: phase === "starting"? "正在连接": phase === "ended" && room@@ -1668,46 +1691,57 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {<div className="viewer-panel-heading"><div><h2 id="viewer-heading">观看者</h2>- <span>{viewers.length}/{maxViewers ?? "-"}</span>+ <span>+ 在线 {viewers.length}/{maxViewers ?? "-"} · Host 直连{" "}+ {hostDirectViewerCount}+ </span></div><Users size={18} aria-hidden="true" /></div><div className="viewer-list">- {viewers.map((viewer, index) => (- <article className="viewer-item" key={viewer.peerId}>- <div className="viewer-item-heading">- <div>- <h3>朋友 {index + 1}</h3>- <PeerStatusBadge state={viewer.connectionState} />+ {viewers.map((viewer) => {+ const snapshot = peerSnapshots.get(viewer.peerId);+ const qualityEvidence = viewerQualityEvidence.get(viewer.peerId);+ return (+ <article className="viewer-item" key={viewer.peerId}>+ <div className="viewer-item-heading">+ <div>+ <h3 title={viewer.label}>{viewer.label}</h3>+ {snapshot && (+ <PeerStatusBadge state={snapshot.connectionState} />+ )}+ </div>+ <TopologyBadge topology={viewer.mediaTopology} /></div>- {showConnectionDetails && (- <PathBadge path={viewer.metrics.path} />+ {showConnectionDetails && snapshot && (+ <>+ <div className="viewer-transport-heading">+ <span>Host 本机传输</span>+ <PathBadge path={snapshot.metrics.path} />+ </div>+ <StatsGrid+ metrics={snapshot.metrics}+ direction="send"+ senderParameters={snapshot.senderParameters}+ />+ </>)}- </div>- {showConnectionDetails && (- <>- <StatsGrid- metrics={viewer.metrics}- direction="send"- senderParameters={viewer.senderParameters}- />- {viewerQualityEvidence.get(viewer.peerId) && (- <>- <p className="section-meta">观看端接收</p>- <StatsGrid- metrics={metricsFromQualityEvidence(- viewerQualityEvidence.get(viewer.peerId)!,- )}- direction="receive"- />- </>- )}- </>- )}- {viewer.error && <p className="inline-error">{viewer.error}</p>}- </article>- ))}+ {showConnectionDetails && qualityEvidence && (+ <>+ <p className="section-meta">观看端接收</p>+ <StatsGrid+ metrics={metricsFromQualityEvidence(qualityEvidence)}+ direction="receive"+ />+ </>+ )}+ {snapshot?.error && (+ <p className="inline-error">{snapshot.error}</p>+ )}+ </article>+ );+ })}{viewers.length === 0 && (<div className="empty-viewers"><Users size={24} strokeWidth={1.5} aria-hidden="true" />diff --git a/src/client/pages/ViewerPage.tsx b/src/client/pages/ViewerPage.tsxindex fd404180..8bb9ed01 100644--- a/src/client/pages/ViewerPage.tsx+++ b/src/client/pages/ViewerPage.tsx@@ -3,6 +3,7 @@ import {Maximize2,Play,RefreshCw,+ Save,VideoOff,Volume2,VolumeX,@@ -26,6 +27,7 @@ import {WarningBanner,} from "../components/StatusBadge";import { StatsGrid } from "../components/StatsGrid";+import { readDisplayName, saveDisplayName } from "../lib/display-name";import { clearViewerGrant, getStableClientId } from "../lib/session";import { SignalingClient } from "../lib/signaling";import type { QualitySettings } from "../media/quality";@@ -88,6 +90,9 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {DEFAULT_VIEWER_VOLUME_STATE,);const [showConnectionDetails, setShowConnectionDetails] = useState(false);+ const [displayName, setDisplayName] = useState(() => readDisplayName());+ const [displayNameDraft, setDisplayNameDraft] = useState(displayName);+ const [displayNameError, setDisplayNameError] = useState<string | null>(null);const qualityLimitation = useMemo(() =>@@ -101,6 +106,8 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {const videoRef = useRef<HTMLVideoElement | null>(null);const peerRef = useRef<ViewerPeer | null>(null);+ const signalRef = useRef<SignalingClient | null>(null);+ const displayNameRef = useRef(displayName);const { muted, volumePercent } = playbackVolume;useEffect(() => {@@ -143,6 +150,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {role: "viewer",clientId: getStableClientId("viewer", roomId),...(viewerGrant ? { viewerGrant } : {}),+ displayName: displayNameRef.current,},{onStatus: (status) => {@@ -182,6 +190,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {},},);+ signalRef.current = signal;const qualityEvidenceReporter = new ViewerQualityEvidenceReporter((message) => active && signal.send(message),);@@ -753,6 +762,9 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {}sfuStandbyPrewarmer?.dispose();signal.stop();+ if (signalRef.current === signal) {+ signalRef.current = null;+ }void viewerSfuRoute?.disconnect();viewerSfuRoute = null;preparedParentPeerId = null;@@ -846,6 +858,19 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {}}+ function commitDisplayName(): void {+ const saved = saveDisplayName(displayNameDraft);+ if (!saved) {+ setDisplayNameError("名称格式无效或超过 24 个字符");+ return;+ }+ displayNameRef.current = saved;+ setDisplayName(saved);+ setDisplayNameDraft(saved);+ setDisplayNameError(null);+ signalRef.current?.setViewerDisplayName(saved);+ }+if (accessState !== "ready") {return (<div className="app-shell">@@ -891,6 +916,42 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {</div></div>+ <form+ className="viewer-name-control"+ onSubmit={(event) => {+ event.preventDefault();+ commitDisplayName();+ }}+ >+ <label htmlFor="viewer-display-name">显示名</label>+ <input+ id="viewer-display-name"+ type="text"+ value={displayNameDraft}+ maxLength={96}+ autoComplete="nickname"+ aria-invalid={displayNameError ? "true" : undefined}+ onChange={(event) => {+ setDisplayNameDraft(event.target.value);+ setDisplayNameError(null);+ }}+ />+ <button+ type="submit"+ className="icon-button"+ title="保存显示名"+ aria-label="保存显示名"+ disabled={displayNameDraft === displayName}+ >+ <Save size={17} />+ </button>+ {displayNameError && (+ <span className="viewer-name-error" role="alert">+ {displayNameError}+ </span>+ )}+ </form>+<section className="video-stage remote-stage" aria-label="共享画面"><videoref={videoRef}diff --git a/src/client/styles.css b/src/client/styles.cssindex 38b2f931..0e88ba7f 100644--- a/src/client/styles.css+++ b/src/client/styles.css@@ -794,6 +794,24 @@ h3 {gap: 8px;}+.viewer-item-heading h3 {+ min-width: 0;+ overflow: hidden;+ text-overflow: ellipsis;+ white-space: nowrap;+}++.viewer-transport-heading {+ display: flex;+ min-height: 28px;+ align-items: center;+ justify-content: space-between;+ gap: 8px;+ margin-bottom: 8px;+ color: var(--faint);+ font-size: 11px;+}+.empty-viewers {display: grid;min-height: 150px;@@ -907,6 +925,45 @@ h3 {justify-content: flex-end;}+.viewer-name-control {+ display: grid;+ width: min(100%, 380px);+ min-height: 40px;+ grid-template-columns: auto minmax(0, 1fr) 40px;+ gap: 8px;+ align-items: center;+ margin: 8px 0 12px;+}++.viewer-name-control label {+ color: var(--muted);+ font-size: 12px;+ font-weight: 600;+}++.viewer-name-control input {+ width: 100%;+ min-width: 0;+ height: 40px;+ padding: 0 10px;+ border: 1px solid var(--border);+ border-radius: 6px;+ outline: 0;+ color: var(--text);+ background: var(--surface);+}++.viewer-name-control input:focus {+ border-color: var(--green);+}++.viewer-name-error {+ grid-column: 2 / -1;+ color: #ff9797;+ font-size: 11px;+ overflow-wrap: anywhere;+}+.remote-stage {max-height: calc(100dvh - 250px);margin: 0 auto;@@ -1060,6 +1117,10 @@ h3 {justify-content: flex-start;}+ .viewer-name-control {+ width: 100%;+ }+.viewer-toolbar {flex-wrap: wrap;gap: 6px;diff --git a/src/server/hybrid-media-router.ts b/src/server/hybrid-media-router.tsindex a8f98303..6aca6f8f 100644--- a/src/server/hybrid-media-router.ts+++ b/src/server/hybrid-media-router.ts@@ -9,6 +9,7 @@ import {type RelayDownstreamEdges,type Role,type ServerMessage,+ type ViewerMediaTopology,} from "../shared/protocol.js";import type { SfuTokenIssuer } from "./livekit-token.js";import {@@ -107,6 +108,7 @@ export interface HybridMediaRouterOptions {sendToSession: (sessionId: string, message: ServerMessage) => void;getConnectionId: (roomId: string, viewerPeerId: string) => string | undefined;deleteConnectionId: (roomId: string, viewerPeerId: string) => void;+ onActiveRouteChanged?: (roomId: string) => void;now?: () => number;}@@ -304,6 +306,26 @@ export class HybridMediaRouter {};}+ getViewerMediaTopology(+ roomId: string,+ viewerPeerId: string,+ ): ViewerMediaTopology {+ const assignment = this.mediaRouteControllers+ .get(roomId)+ ?.getActiveRoute()+ .assignments.get(viewerPeerId);+ if (!assignment || assignment.upstream.kind === "none") {+ return "pending";+ }+ if (assignment.upstream.kind === "sfu") {+ return "sfu";+ }+ return assignment.upstream.peerId ===+ this.peerRelayTopology.getHostPeerId(roomId)+ ? "host-direct"+ : "peer-relay";+ }+handleViewerQualityEvidence(input: ForwardedViewerQualityEvidence): void {const { evidence, roomId, viewerSessionId, parentSessionId } = input;const { viewerPeerId, parentPeerId } = evidence;@@ -1735,6 +1757,7 @@ export class HybridMediaRouter {});}}+ this.options.onActiveRouteChanged?.(roomId);}private clearChangedRouteConnectionIds(diff --git a/src/server/signaling.ts b/src/server/signaling.tsindex 7801440b..5b090a57 100644--- a/src/server/signaling.ts+++ b/src/server/signaling.ts@@ -5,6 +5,7 @@ import type { Duplex } from "node:stream";import WebSocket, { WebSocketServer } from "ws";import {+ DEFAULT_VIEWER_DISPLAY_NAME,DEFAULT_QUALITY_SETTINGS,MAX_PARENT_EDGE_QUALITY_EVIDENCE_BYTES,MAX_SIGNAL_BYTES,@@ -17,6 +18,7 @@ import {type QualitySettings,type Role,type ServerMessage,+ type ViewerPresenceEntry,} from "../shared/protocol.js";import {RoomStore,@@ -41,6 +43,8 @@ interface AuthenticatedSession {peerId: string;roomExpiresAtMs: number | null;shareGeneration: string | null;+ displayName: string | null;+ viewerPresence: boolean;}interface SocketState {@@ -99,6 +103,7 @@ export class SignalingServer {>();private readonly qualitySettingsByRoom = new Map<string, QualitySettings>();private readonly shareGenerationsByRoom = new Map<string, string>();+ private readonly deferredViewerPresenceRooms = new Set<string>();private readonly hybridMediaRouter?: HybridMediaRouter;private readonly now: () => number;private readonly authenticationTimeoutMs: number;@@ -152,6 +157,7 @@ export class SignalingServer {),deleteConnectionId: (roomId, viewerPeerId) =>this.deleteViewerConnectionId(roomId, viewerPeerId),+ onActiveRouteChanged: (roomId) => this.sendViewerPresence(roomId),now: this.now,});}@@ -399,6 +405,11 @@ export class SignalingServer {? null: Date.parse(participant.expiresAt),shareGeneration,+ displayName:+ message.role === "viewer"+ ? (message.displayName ?? DEFAULT_VIEWER_DISPLAY_NAME)+ : null,+ viewerPresence: false,};if (participant.role === "viewer") {this.viewerQualityEvidenceGates.delete(@@ -466,6 +477,8 @@ export class SignalingServer {} else {this.send(socket, authenticatedMessage);}+ state.authenticated.viewerPresence =+ message.role === "host" && message.viewerPresence === true;if (participant.replacedSessionId) {const replaced = this.socketsBySessionId.get(participant.replacedSessionId);@@ -481,6 +494,8 @@ export class SignalingServer {);}+ this.sendViewerPresence(participant.roomId);+if (participant.role === "host") {for (const viewer of connectedViewers) {this.sendToSession(viewer.sessionId, { type: "host-status", online: true });@@ -630,6 +645,14 @@ export class SignalingServer {case "parent-edge-quality-evidence":this.handleParentEdgeQualityEvidence(socket, authenticated, message);return;+ case "set-display-name":+ if (authenticated.role !== "viewer") {+ this.sendError(socket, "FORBIDDEN", "Only viewers may set a display name");+ return;+ }+ authenticated.displayName = message.displayName;+ this.sendViewerPresence(authenticated.roomId);+ return;case "set-viewer-access":if (authenticated.role !== "host") {this.sendError(@@ -703,42 +726,48 @@ export class SignalingServer {this.clearRoomGraceTimers(authenticated.roomId);this.clearRoomConnectionIds(authenticated.roomId);- for (const viewer of update.revokedViewers) {- if (!viewer.sessionId) {- continue;- }- this.sendToSession(viewer.sessionId, {- type: "viewer-access-revoked",- viewerAuthorizationGeneration:- update.previousViewerAuthorizationGeneration,- });- }-- if (this.isPeerAssistedRoom(authenticated.roomId)) {+ this.deferredViewerPresenceRooms.add(authenticated.roomId);+ try {for (const viewer of update.revokedViewers) {- this.hybridMediaRouter!.removeViewer(- authenticated.roomId,- viewer.peerId,- );+ if (!viewer.sessionId) {+ continue;+ }+ this.sendToSession(viewer.sessionId, {+ type: "viewer-access-revoked",+ viewerAuthorizationGeneration:+ update.previousViewerAuthorizationGeneration,+ });}- } else {- const host = this.options.roomStore.getConnectedHost(authenticated.roomId);- if (host) {++ if (this.isPeerAssistedRoom(authenticated.roomId)) {for (const viewer of update.revokedViewers) {- this.sendToSession(host.sessionId, {- type: "peer-left",- peerId: viewer.peerId,- });+ this.hybridMediaRouter!.removeViewer(+ authenticated.roomId,+ viewer.peerId,+ );+ }+ } else {+ const host = this.options.roomStore.getConnectedHost(authenticated.roomId);+ if (host) {+ for (const viewer of update.revokedViewers) {+ this.sendToSession(host.sessionId, {+ type: "peer-left",+ peerId: viewer.peerId,+ });+ }}}- }- for (const viewer of update.revokedViewers) {- if (!viewer.sessionId) {- continue;+ for (const viewer of update.revokedViewers) {+ if (!viewer.sessionId) {+ continue;+ }+ this.closeRevokedViewerSession(viewer.sessionId);}- this.closeRevokedViewerSession(viewer.sessionId);+ } finally {+ this.deferredViewerPresenceRooms.delete(authenticated.roomId);}+ this.sendViewerPresence(authenticated.roomId);}const inviteUrl =@@ -1118,6 +1147,8 @@ export class SignalingServer {return;}+ this.sendViewerPresence(disconnected.roomId);+const key = viewerGraceKey(disconnected.roomId, disconnected.peerId);const timer = setTimeout(() => {this.viewerGraceTimers.delete(key);@@ -1277,6 +1308,56 @@ export class SignalingServer {return this.options.roomStore.getConnectedViewer(roomId, peerId);}+ private sendViewerPresence(roomId: string): void {+ if (this.deferredViewerPresenceRooms.has(roomId)) {+ return;+ }+ const host = this.options.roomStore.getConnectedHost(roomId);+ if (!host) {+ return;+ }+ const hostSocket = this.socketsBySessionId.get(host.sessionId);+ const hostState = hostSocket+ ? this.socketStates.get(hostSocket)?.authenticated+ : undefined;+ if (+ !hostSocket ||+ hostState?.role !== "host" ||+ hostState.roomId !== roomId ||+ hostState.peerId !== host.peerId ||+ !hostState.viewerPresence+ ) {+ return;+ }++ const viewers: ViewerPresenceEntry[] = [];+ for (const viewer of this.options.roomStore.getConnectedViewers(roomId)) {+ const viewerSocket = this.socketsBySessionId.get(viewer.sessionId);+ const viewerState = viewerSocket+ ? this.socketStates.get(viewerSocket)?.authenticated+ : undefined;+ if (+ viewerState?.role !== "viewer" ||+ viewerState.roomId !== roomId ||+ viewerState.peerId !== viewer.peerId ||+ viewerState.displayName === null+ ) {+ continue;+ }+ viewers.push({+ peerId: viewer.peerId,+ displayName: viewerState.displayName,+ mediaTopology: this.isPeerAssistedRoom(roomId)+ ? this.hybridMediaRouter!.getViewerMediaTopology(+ roomId,+ viewer.peerId,+ )+ : "host-direct",+ });+ }+ this.send(hostSocket, { type: "viewer-presence", viewers });+ }+private sendToSession(sessionId: string, message: ServerMessage): void {const socket = this.socketsBySessionId.get(sessionId);if (socket) {diff --git a/src/shared/protocol.ts b/src/shared/protocol.tsindex 0298af10..eda76f1d 100644--- a/src/shared/protocol.ts+++ b/src/shared/protocol.ts@@ -13,6 +13,46 @@ export const MAX_VIEWER_QUALITY_EVIDENCE_BYTES = 2 * 1024;export const MAX_PARENT_EDGE_QUALITY_EVIDENCE_BYTES = 2 * 1024;export const VIEWER_QUALITY_EVIDENCE_INTERVAL_MS = 2_000;export const VIEWER_QUALITY_EVIDENCE_EXPIRY_MS = 5_000;+export const MAX_DISPLAY_NAME_CODE_POINTS = 24;+export const DEFAULT_VIEWER_DISPLAY_NAME = "访客";++const FORBIDDEN_DISPLAY_NAME_CHARACTERS =+ /[\p{Cc}\p{Zl}\p{Zp}\u061c\u200b\u200e\u200f\u202a-\u202e\u2060\u2066-\u2069\ufeff]/u;++export function normalizeDisplayName(value: string): string | null {+ if (FORBIDDEN_DISPLAY_NAME_CHARACTERS.test(value)) {+ return null;+ }+ for (const character of value) {+ const codePoint = character.codePointAt(0)!;+ if (codePoint >= 0xd800 && codePoint <= 0xdfff) {+ return null;+ }+ }++ const normalized = value.normalize("NFC").trim().replace(/\p{Zs}+/gu, " ");+ const codePointCount = Array.from(normalized).length;+ return codePointCount >= 1 && codePointCount <= MAX_DISPLAY_NAME_CODE_POINTS+ ? normalized+ : null;+}++export const displayNameSchema = z+ .string()+ .min(1)+ .max(MAX_DISPLAY_NAME_CODE_POINTS * 4)+ .refine((value) => normalizeDisplayName(value) === value, {+ message: "Display name must be canonical",+ });+export type DisplayName = z.infer<typeof displayNameSchema>;++export const viewerMediaTopologySchema = z.enum([+ "host-direct",+ "peer-relay",+ "sfu",+ "pending",+]);+export type ViewerMediaTopology = z.infer<typeof viewerMediaTopologySchema>;const opaqueIdSchema = z.string()@@ -20,6 +60,15 @@ const opaqueIdSchema = z.max(128).regex(/^[A-Za-z0-9_-]+$/);+export const viewerPresenceEntrySchema = z+ .object({+ peerId: opaqueIdSchema,+ displayName: displayNameSchema,+ mediaTopology: viewerMediaTopologySchema,+ })+ .strict();+export type ViewerPresenceEntry = z.infer<typeof viewerPresenceEntrySchema>;+const tokenSchema = z.string().min(32)@@ -375,6 +424,7 @@ const authenticateMessageSchema = z.discriminatedUnion("role", [token: tokenSchema,clientId: opaqueIdSchema,shareGeneration: opaqueIdSchema.optional(),+ viewerPresence: z.literal(true).optional(),}).strict(),z@@ -385,6 +435,7 @@ const authenticateMessageSchema = z.discriminatedUnion("role", [role: z.literal("viewer"),clientId: opaqueIdSchema,viewerGrant: viewerGrantSchema.optional(),+ displayName: displayNameSchema.optional(),}).strict(),]);@@ -441,6 +492,12 @@ export const clientMessageSchema = z.union([.strict(),viewerQualityEvidenceMessageSchema,parentEdgeQualityEvidenceMessageSchema,+ z+ .object({+ type: z.literal("set-display-name"),+ displayName: displayNameSchema,+ })+ .strict(),z.object({type: z.literal("set-viewer-access"),@@ -574,6 +631,28 @@ export const serverMessageSchema = z.union([online: z.boolean(),}).strict(),+ z+ .object({+ type: z.literal("viewer-presence"),+ viewers: z+ .array(viewerPresenceEntrySchema)+ .max(MAX_VIEWERS_PER_ROOM_LIMIT),+ })+ .strict()+ .superRefine((message, context) => {+ const peerIds = new Set<string>();+ for (const viewer of message.viewers) {+ if (peerIds.has(viewer.peerId)) {+ context.addIssue({+ code: "custom",+ message: "Viewer presence peer IDs must be unique",+ path: ["viewers"],+ });+ return;+ }+ peerIds.add(viewer.peerId);+ }+ }),z.object({type: z.literal("viewer-access-updated"),diff --git a/tests/client-state.test.ts b/tests/client-state.test.tsindex bdbf7f76..14a3e560 100644--- a/tests/client-state.test.ts+++ b/tests/client-state.test.ts@@ -6,6 +6,10 @@ import {createRoom,getHostAdmission,} from "../src/client/lib/api.ts";+import {+ readDisplayName,+ saveDisplayName,+} from "../src/client/lib/display-name.ts";import {clearHostRoom,getStableClientId,@@ -21,6 +25,7 @@ import {shouldReconnectSignaling,SignalingClient,} from "../src/client/lib/signaling.ts";+import { 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";@@ -28,6 +33,53 @@ afterEach(() => {vi.unstubAllGlobals();});+describe("browser-local display name", () => {+ it("stores only the canonical preference and falls back when cleared", () => {+ const values = new Map<string, string>();+ vi.stubGlobal("window", {+ localStorage: {+ getItem: (key: string) => values.get(key) ?? null,+ setItem: (key: string, value: string) => values.set(key, value),+ removeItem: (key: string) => values.delete(key),+ },+ });++ expect(saveDisplayName(" Cafe\u0301\u00a0玩家 ")).toBe("Café 玩家");+ expect(readDisplayName()).toBe("Café 玩家");+ expect(saveDisplayName("\u202ehidden")).toBeNull();+ expect(saveDisplayName("\n")).toBeNull();+ expect(readDisplayName()).toBe("Café 玩家");+ expect(saveDisplayName(" ")).toBe("访客");+ expect(readDisplayName()).toBe("访客");+ });++ it("extends only colliding room-scoped peer ID suffixes", () => {+ const labeled = labelViewerPresence([+ {+ peerId: "viewer_AAAAAAsuffix",+ displayName: "同名",+ mediaTopology: "host-direct",+ },+ {+ peerId: "viewer_BBBBBBsuffix",+ displayName: "同名",+ mediaTopology: "peer-relay",+ },+ {+ peerId: "viewer_independent",+ displayName: "朋友",+ mediaTopology: "sfu",+ },+ ]);++ expect(labeled[0].peerIdSuffix.length).toBeGreaterThan(6);+ expect(labeled[1].peerIdSuffix.length).toBeGreaterThan(6);+ expect(labeled[0].peerIdSuffix).not.toBe(labeled[1].peerIdSuffix);+ expect(labeled[2].peerIdSuffix).toHaveLength(6);+ expect(labeled[0].label).toContain("同名 (");+ });+});+describe("client session identity", () => {it("works without secure-context-only crypto.randomUUID", () => {const values = new Map<string, string>();diff --git a/tests/protocol.test.ts b/tests/protocol.test.tsindex 64a73041..813d9da8 100644--- a/tests/protocol.test.ts+++ b/tests/protocol.test.ts@@ -1,6 +1,8 @@import { describe, expect, it } from "vitest";import {+ DEFAULT_VIEWER_DISPLAY_NAME,+ MAX_DISPLAY_NAME_CODE_POINTS,MAX_HOST_CLAIM_TTL_SECONDS,MAX_MEDIA_ROUTE_REVISION,MAX_PARENT_EDGE_QUALITY_EVIDENCE_BYTES,@@ -11,6 +13,7 @@ import {clientMessageSchema,createRoomRequestSchema,decodeClientMessage,+ normalizeDisplayName,participantRouteAssignmentSchema,serverMessageSchema,} from "../src/shared/protocol.js";@@ -134,6 +137,49 @@ describe("client signaling protocol", () => {).toBe(false);});+ it("normalizes display names and rejects misleading Unicode boundaries", () => {+ expect(normalizeDisplayName(" Cafe\u0301\u00a0朋友 ")).toBe("Café 朋友");+ expect(normalizeDisplayName("玩家 👩💻")).toBe("玩家 👩💻");+ expect(normalizeDisplayName("名".repeat(MAX_DISPLAY_NAME_CODE_POINTS))).toBe(+ "名".repeat(MAX_DISPLAY_NAME_CODE_POINTS),+ );+ expect(+ normalizeDisplayName("名".repeat(MAX_DISPLAY_NAME_CODE_POINTS + 1)),+ ).toBeNull();+ for (const invalid of ["a\nb", "a\u202eb", "a\ufeffb", "a\ud800b"]) {+ expect(normalizeDisplayName(invalid)).toBeNull();+ }++ expect(+ clientMessageSchema.safeParse({+ type: "authenticate",+ protocol: SIGNALING_PROTOCOL,+ roomId,+ role: "viewer",+ clientId: "client_12345678",+ displayName: "小明",+ }).success,+ ).toBe(true);+ expect(+ clientMessageSchema.safeParse({+ type: "authenticate",+ protocol: SIGNALING_PROTOCOL,+ roomId,+ role: "host",+ token,+ clientId: "client_12345678",+ viewerPresence: true,+ }).success,+ ).toBe(true);+ expect(+ clientMessageSchema.safeParse({+ type: "set-display-name",+ displayName: " Cafe\u0301 ",+ }).success,+ ).toBe(false);+ expect(DEFAULT_VIEWER_DISPLAY_NAME).toBe("访客");+ });+it("accepts only canonical bounded Viewer grants and access actions", () => {for (const malformedGrant of [`g0.${roomId}.1787076000.${"b".repeat(43)}`,@@ -616,6 +662,32 @@ describe("server signaling protocol", () => {).toBe(true);});+ it("accepts a strict, unique and bounded Viewer presence snapshot", () => {+ const viewer = {+ peerId: "viewer_12345678",+ displayName: "小明",+ mediaTopology: "peer-relay",+ } as const;+ expect(+ serverMessageSchema.safeParse({+ type: "viewer-presence",+ viewers: [viewer],+ }).success,+ ).toBe(true);+ expect(+ serverMessageSchema.safeParse({+ type: "viewer-presence",+ viewers: [viewer, viewer],+ }).success,+ ).toBe(false);+ expect(+ serverMessageSchema.safeParse({+ type: "viewer-presence",+ viewers: [{ ...viewer, ip: "203.0.113.1" }],+ }).success,+ ).toBe(false);+ });+it("represents persistent rooms without a room expiry", () => {expect(serverMessageSchema.safeParse({diff --git a/tests/server-signal.test.ts b/tests/server-signal.test.tsindex 1b4120df..4157dd49 100644--- a/tests/server-signal.test.ts+++ b/tests/server-signal.test.ts@@ -433,6 +433,7 @@ async function authenticate(clientId: string,relayCapacity: 0 | 1 | null = 1,shareGeneration?: string,+ presence: { displayName?: string; viewerPresence?: true } = {},) {client.socket.send(JSON.stringify(@@ -445,6 +446,7 @@ async function authenticate(token: room.hostToken,clientId,...(shareGeneration ? { shareGeneration } : {}),+ ...(presence.viewerPresence ? { viewerPresence: true } : {}),}: {type: "authenticate",@@ -453,6 +455,9 @@ async function authenticate(role,clientId,...(room.viewerGrant ? { viewerGrant: room.viewerGrant } : {}),+ ...(presence.displayName+ ? { displayName: presence.displayName }+ : {}),},),);@@ -493,6 +498,21 @@ async function nextActiveRouteAfter(}}+async function nextViewerPresenceMatching(+ client: TestClient,+ predicate: (+ message: Extract<ServerMessage, { type: "viewer-presence" }>,+ ) => boolean,+) {+ for (let attempt = 0; attempt < 20; attempt += 1) {+ const message = await client.inbox.next("viewer-presence");+ if (predicate(message)) {+ return message;+ }+ }+ throw new Error("Viewer presence did not reach the expected state");+}+async function nextPreparedRoute(client: TestClient) {while (true) {const message = await client.inbox.next("route-update");@@ -704,6 +724,188 @@ async function closeClient(client: TestClient): Promise<void> {}describe("WebSocket signaling", () => {+ it("keeps the exact Native Host wire unchanged without a presence opt-in", async () => {+ const harness = await startHarness();+ const host = await openClient(harness.webSocketUrl);+ await authenticate(host, harness.room, "host", "native-compatible-host");+ const viewer = await openClient(harness.webSocketUrl);+ await authenticate(+ viewer,+ harness.room,+ "viewer",+ "native-compatible-viewer",+ 1,+ undefined,+ { displayName: "移动观众" },+ );++ await host.inbox.next("peer-joined");+ await host.inbox.expectNone(40);+ });++ it("reports every online Viewer without expanding the Host media fanout", async () => {+ const harness = await startHarness({ peerAssistedMedia: true });+ const host = await openClient(harness.webSocketUrl);+ await authenticate(+ host,+ harness.room,+ "host",+ "presence-host",+ 1,+ undefined,+ { viewerPresence: true },+ );+ expect((await host.inbox.next("viewer-presence")).viewers).toEqual([]);++ const viewerNames = ["阿明", "阿青", undefined] as const;+ const viewers: TestClient[] = [];+ for (const [index, displayName] of viewerNames.entries()) {+ const viewer = await openClient(harness.webSocketUrl);+ viewers.push(viewer);+ await authenticate(+ viewer,+ harness.room,+ "viewer",+ `presence-viewer-${index}`,+ 1,+ undefined,+ displayName ? { displayName } : {},+ );+ }++ const full = await nextViewerPresenceMatching(+ host,+ (message) =>+ message.viewers.length === 3 &&+ message.viewers.some(+ (viewer) => viewer.mediaTopology === "peer-relay",+ ),+ );+ expect(full.viewers.map((viewer) => viewer.displayName)).toEqual([+ "阿明",+ "阿青",+ "访客",+ ]);+ expect(+ full.viewers.filter(+ (viewer) => viewer.mediaTopology === "host-direct",+ ),+ ).toHaveLength(2);++ viewers[2].socket.send(+ JSON.stringify({ type: "set-display-name", displayName: "后来改名" }),+ );+ const renamed = await nextViewerPresenceMatching(host, (message) =>+ message.viewers.some((viewer) => viewer.displayName === "后来改名"),+ );+ expect(renamed.viewers).toHaveLength(3);++ await closeClient(viewers[2]);+ const afterDisconnect = await nextViewerPresenceMatching(+ host,+ (message) => message.viewers.length === 2,+ );+ expect(afterDisconnect.viewers.map((viewer) => viewer.displayName)).toEqual([+ "阿明",+ "阿青",+ ]);+ });++ it("publishes one empty Viewer roster after ordinary rotate and revoke", async () => {+ const harness = await startHarness();+ const host = await openClient(harness.webSocketUrl);+ await authenticate(+ host,+ harness.room,+ "host",+ "ordinary-access-presence-host",+ 1,+ undefined,+ { viewerPresence: true },+ );+ expect((await host.inbox.next("viewer-presence")).viewers).toEqual([]);++ const firstViewer = await openClient(harness.webSocketUrl);+ const firstViewerAuth = await authenticate(+ firstViewer,+ harness.room,+ "viewer",+ "ordinary-access-presence-viewer-1",+ 1,+ undefined,+ { displayName: "第一位" },+ );+ expect((await host.inbox.next("peer-joined")).peerId).toBe(+ firstViewerAuth.peerId,+ );+ expect((await host.inbox.next("viewer-presence")).viewers).toEqual([+ {+ peerId: firstViewerAuth.peerId,+ displayName: "第一位",+ mediaTopology: "host-direct",+ },+ ]);++ const firstClosed = new Promise<number>((resolve) =>+ firstViewer.socket.once("close", (code) => resolve(code)),+ );+ host.socket.send(+ JSON.stringify({ type: "set-viewer-access", action: "rotate" }),+ );+ expect(await firstViewer.inbox.next("viewer-access-revoked")).toMatchObject({+ viewerAuthorizationGeneration:+ firstViewerAuth.viewerAuthorizationGeneration,+ });+ expect(await firstClosed).toBe(4004);+ expect((await host.inbox.next("peer-left")).peerId).toBe(+ firstViewerAuth.peerId,+ );+ expect((await host.inbox.next("viewer-presence")).viewers).toEqual([]);+ const rotated = await host.inbox.next("viewer-access-updated");+ await host.inbox.expectNone(30);++ const rotatedGrant = new URLSearchParams(+ new URL(rotated.inviteUrl!).hash.slice(1),+ ).get("v");+ expect(rotatedGrant).toBeTruthy();+ const rotatedRoom = {+ ...harness.room,+ viewerGrant: rotatedGrant,+ } satisfies CreatedRoom;+ const secondViewer = await openClient(harness.webSocketUrl);+ const secondViewerAuth = await authenticate(+ secondViewer,+ rotatedRoom,+ "viewer",+ "ordinary-access-presence-viewer-2",+ 1,+ undefined,+ { displayName: "第二位" },+ );+ expect((await host.inbox.next("peer-joined")).peerId).toBe(+ secondViewerAuth.peerId,+ );+ expect((await host.inbox.next("viewer-presence")).viewers).toHaveLength(1);++ const secondClosed = new Promise<number>((resolve) =>+ secondViewer.socket.once("close", (code) => resolve(code)),+ );+ host.socket.send(+ JSON.stringify({ type: "set-viewer-access", action: "revoke" }),+ );+ await secondViewer.inbox.next("viewer-access-revoked");+ expect(await secondClosed).toBe(4004);+ expect((await host.inbox.next("peer-left")).peerId).toBe(+ secondViewerAuth.peerId,+ );+ expect((await host.inbox.next("viewer-presence")).viewers).toEqual([]);+ expect(await host.inbox.next("viewer-access-updated")).toMatchObject({+ viewerPolicy: "private-link",+ inviteUrl: null,+ });+ await host.inbox.expectNone(30);+ });+it("protects Host admission without gating authorized Viewers", async () => {const hostAdmissionPassword = "protected-instance-password";const harness = await startHarness({ hostAdmissionPassword });@@ -4447,18 +4649,37 @@ describe("WebSocket signaling", () => {expect(reconnectedAuth.hostOnline).toBe(false);});- it("atomically replaces the same client socket without leave churn", async () => {+ it("replaces the same client presence once without leave churn", async () => {const harness = await startHarness({ viewerDisconnectGraceMs: 40 });const host = await openClient(harness.webSocketUrl);- await authenticate(host, harness.room, "host", "host-client-stable");+ await authenticate(+ host,+ harness.room,+ "host",+ "host-client-stable",+ 1,+ undefined,+ { viewerPresence: true },+ );+ expect((await host.inbox.next("viewer-presence")).viewers).toEqual([]);const original = await openClient(harness.webSocketUrl);const originalAuth = await authenticate(original,harness.room,"viewer","viewer-client-stable",+ 1,+ undefined,+ { displayName: "旧会话" },);await host.inbox.next("peer-joined");+ expect((await host.inbox.next("viewer-presence")).viewers).toEqual([+ {+ peerId: originalAuth.peerId,+ displayName: "旧会话",+ mediaTopology: "host-direct",+ },+ ]);const originalClosed = new Promise<number>((resolve) =>original.socket.once("close", (code) => resolve(code)),@@ -4469,11 +4690,21 @@ describe("WebSocket signaling", () => {harness.room,"viewer","viewer-client-stable",+ 1,+ undefined,+ { displayName: "新会话" },);expect(replacementAuth.peerId).toBe(originalAuth.peerId);expect(await originalClosed).toBe(4001);expect((await host.inbox.next("peer-joined")).peerId).toBe(originalAuth.peerId);+ expect((await host.inbox.next("viewer-presence")).viewers).toEqual([+ {+ peerId: originalAuth.peerId,+ displayName: "新会话",+ mediaTopology: "host-direct",+ },+ ]);await host.inbox.expectNone(70);});@@ -4640,18 +4871,37 @@ describe("WebSocket signaling", () => {await secondHost.inbox.expectNone(30);});- it("keeps a grace-period viewer in the host roster and announces its return", async () => {+ it("keeps media identity through grace while presence returns once", async () => {const harness = await startHarness({ viewerDisconnectGraceMs: 500 });const firstHost = await openClient(harness.webSocketUrl);- await authenticate(firstHost, harness.room, "host", "host-client-grace-roster");+ await authenticate(+ firstHost,+ harness.room,+ "host",+ "host-client-grace-roster",+ 1,+ undefined,+ { viewerPresence: true },+ );+ expect((await firstHost.inbox.next("viewer-presence")).viewers).toEqual([]);const firstViewer = await openClient(harness.webSocketUrl);const firstViewerAuth = await authenticate(firstViewer,harness.room,"viewer","viewer-client-grace-roster",+ 1,+ undefined,+ { displayName: "短线重连" },);await firstHost.inbox.next("peer-joined");+ expect((await firstHost.inbox.next("viewer-presence")).viewers).toEqual([+ {+ peerId: firstViewerAuth.peerId,+ displayName: "短线重连",+ mediaTopology: "host-direct",+ },+ ]);firstHost.socket.send(JSON.stringify({type: "signal",@@ -4666,6 +4916,7 @@ describe("WebSocket signaling", () => {await firstViewer.inbox.next("signal");await closeClient(firstViewer);+ expect((await firstHost.inbox.next("viewer-presence")).viewers).toEqual([]);await closeClient(firstHost);const secondHost = await openClient(harness.webSocketUrl);@@ -4674,8 +4925,12 @@ describe("WebSocket signaling", () => {harness.room,"host","host-client-grace-roster",+ 1,+ undefined,+ { viewerPresence: true },);expect(secondHostAuth.viewerPeerIds).toEqual([firstViewerAuth.peerId]);+ expect((await secondHost.inbox.next("viewer-presence")).viewers).toEqual([]);await secondHost.inbox.expectNone(30);const secondViewer = await openClient(harness.webSocketUrl);@@ -4684,12 +4939,23 @@ describe("WebSocket signaling", () => {harness.room,"viewer","viewer-client-grace-roster",+ 1,+ undefined,+ { displayName: "短线重连" },);expect(secondViewerAuth.peerId).toBe(firstViewerAuth.peerId);expect(secondViewerAuth.connectionId).toBe("connection-during-grace");expect((await secondHost.inbox.next("peer-joined")).peerId).toBe(firstViewerAuth.peerId,);+ expect((await secondHost.inbox.next("viewer-presence")).viewers).toEqual([+ {+ peerId: firstViewerAuth.peerId,+ displayName: "短线重连",+ mediaTopology: "host-direct",+ },+ ]);+ await secondHost.inbox.expectNone(30);secondViewer.socket.send(JSON.stringify({