Skip to content

armgit / Piik

Public Imported from GitHub
0

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.md
index 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.md
index 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 Targets
diff --git a/docs/research/display-name-presence.md b/docs/research/display-name-presence.md
new file mode 100644
index 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.md
index 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 Evidence
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 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.tsx
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.tsx
index 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.tsx
index 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="共享画面">
<video
ref={videoRef}
diff --git a/src/client/styles.css b/src/client/styles.css
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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({