virlen-remote 0.1.0

package/src/transport/rtc.ts

@@ -0,0 +1,344 @@
+/**
+ * RTC transport —— 真实链路（WebRTC DataChannel）。
+ *
+ * 只依赖两个注入点，因此**可单测**（不需要真实 WebRTC）：
+ *   - `signaling`：信令通道（`SignalingChannel`，M3 用 SSE 实现；测试用环回实现）
+ *   - `createPeerConnection`：`RTCPeerConnection` 工厂（测试用假实现）
+ *
+ * 角色（见 §8 拍板）：**电脑(host) 发起 offer**，手机(guest) 应答。
+ * 电脑常驻房间，手机加入后由电脑发 offer —— 手机可能在后台切换，桌面是稳定进程。
+ *
+ * 状态映射：`connected → open`；`failed/closed → closed`；`disconnected → connecting`（等重连）。
+ */
+import type { Transport, TransportState } from './types'
+import type { KickedInfo, SignalingChannel, SignalingRole } from './signaling'
+import type { IceServerInit } from './ice'
+import { BridgeError, toBridgeError } from '../protocol/errors'
+
+export interface RtcTransportOptions {
+  role: SignalingRole
+  signaling: SignalingChannel
+  /**
+   * ICE 服务器列表。**不再有内置默认值**（M7，§31）：两端都由
+   * `resolveIceServers()` 决定（自定义 > 服务端下发 > 缓存 > 空）。
+   */
+  iceServers?: IceServerInit[]
+  /** 数据通道 label（对两端须一致）。 */
+  channelLabel?: string
+  /** 注入 `RTCPeerConnection` 工厂（测试用；默认取全局构造器）。 */
+  createPeerConnection?: (config: RTCConfiguration) => RTCPeerConnection
+}
+
+type SignalData =
+  | { kind: 'offer'; sdp: RTCSessionDescriptionInit }
+  | { kind: 'answer'; sdp: RTCSessionDescriptionInit }
+  | { kind: 'candidate'; cand: RTCIceCandidateInit | null }
+
+export class RtcTransport implements Transport {
+  private _state: TransportState = 'connecting'
+  private readonly messageListeners = new Set<(bytes: Uint8Array) => void>()
+  private readonly stateListeners = new Set<(state: TransportState) => void>()
+
+  private pc: RTCPeerConnection | null = null
+  private dc: RTCDataChannel | null = null
+  private pendingCandidates: RTCIceCandidateInit[] = []
+  private started = false
+  /** 被顶号（致命）：置位后一切重建/重连动作都无意义。 */
+  private replaced = false
+
+  private readonly readyPromise: Promise<void>
+  private readyResolve: (() => void) | null = null
+  private readyReject: ((error: Error) => void) | null = null
+
+  constructor(private readonly options: RtcTransportOptions) {
+    this.readyPromise = new Promise<void>((resolve, reject) => {
+      this.readyResolve = resolve
+      this.readyReject = reject
+    })
+    const sig = options.signaling
+    sig.onPeer = (peerId) => this.onPeer(peerId)
+    sig.onData = (data) => {
+      void this.handleRemote(data)
+    }
+    sig.onError = (err) => this.fail(err)
+    sig.onKicked = (info) => this.onKicked(info)
+  }
+
+  get state(): TransportState {
+    return this._state
+  }
+
+  get bufferedAmount(): number {
+    return this.dc?.bufferedAmount ?? 0
+  }
+
+  /** 链路真正可用的 Promise（DataChannel open 时 resolve）；失败/关闭时 reject。 */
+  whenReady(): Promise<void> {
+    return this.readyPromise
+  }
+
+  /** 加入信令房间并开始协商。使用方创建后调用一次（不需要 await，靠状态/`whenReady` 驱动）。 */
+  async start(): Promise<void> {
+    if (this.started) return
+    this.started = true
+    try {
+      await this.options.signaling.join()
+    } catch (err) {
+      this.fail(toBridgeError(err))
+    }
+  }
+
+  send(bytes: Uint8Array): void {
+    const dc = this.dc
+    if (this._state !== 'open' || !dc || dc.readyState !== 'open') return
+    // 注：DOM 定义的 `send` 要求 `ArrayBufferView<ArrayBuffer>`，而 `Uint8Array` 泛型是
+    // `ArrayBufferLike`（可能含 SharedArrayBuffer）。实际数据永远是普通 buffer，安全 cast。
+    dc.send(bytes as unknown as ArrayBufferView<ArrayBuffer>)
+  }
+
+  close(): void {
+    if (this._state === 'closed') return
+    this.teardownPeer()
+    try {
+      this.options.signaling.close()
+    } catch {
+      /* 忽略 */
+    }
+    this.setState('closed')
+    this.readyReject?.(new Error('transport closed'))
+  }
+
+  onMessage(listener: (bytes: Uint8Array) => void): () => void {
+    this.messageListeners.add(listener)
+    return () => {
+      this.messageListeners.delete(listener)
+    }
+  }
+
+  onStateChange(listener: (state: TransportState) => void): () => void {
+    this.stateListeners.add(listener)
+    return () => {
+      this.stateListeners.delete(listener)
+    }
+  }
+
+  // ───────────────────────── 内部：信令 → 协商 ─────────────────────────
+
+  private onPeer(peerId: string | null): void {
+    // 被顶号后信令已停用：此时任何对端变化都不该再重建 PC（重建出来也是死链路）
+    if (this.replaced) return
+    if (peerId === null) {
+      // 对端离开：清掉旧连接，回到等待态（手机重连后会重新触发）
+      this.teardownPeer()
+      this.setState('connecting')
+      return
+    }
+    // 只有 host 主动发起：guest 必须等 offer 到达才建 PC（否则会建两次 PC、上下文串味）
+    if (this.options.role === 'host') {
+      this.ensurePC()
+      void this.startOffer()
+    }
+  }
+
+  /**
+   * 被服务端顶号（同一台电脑已有别的手机接入）。
+   *
+   * 顺序是刻意的：**先把错误告知上层，再改状态**。上层（手机端 `connectionStore`）在
+   * 看到 `closed` 时会安排自动重连 —— 而重连会把刚接入的那台手机再顶掉（乒乓）。
+   * 所以「被顶号」这个事实必须先于状态变化到达。
+   */
+  private onKicked(info: KickedInfo): void {
+    if (this.replaced) return
+    this.replaced = true
+    this.fail(
+      new BridgeError('E_REPLACED', '该电脑已被另一台手机接管连接', {
+        data: { reason: info.reason },
+      }),
+    )
+    this.teardownPeer()
+    try {
+      this.options.signaling.close()
+    } catch {
+      /* 忽略 */
+    }
+    // 状态置 closed 收尾（`_state` 为 closed 时 `close()` 也不会重复处理）
+    this.setState('closed')
+  }
+
+  private ensurePC(): RTCPeerConnection {
+    if (this.pc) return this.pc
+    const factory = this.options.createPeerConnection ?? defaultFactory()
+    const pc = factory({ iceServers: this.options.iceServers ?? [] })
+    this.pc = pc
+
+    pc.onicecandidate = (e) => {
+      if (!e.candidate) return
+      void this.options.signaling.send({ kind: 'candidate', cand: candidateToJson(e.candidate) })
+    }
+    pc.onconnectionstatechange = () => this.onConnectionState(pc.connectionState)
+    pc.ondatachannel = (e) => this.setupDataChannel(e.channel)
+    return pc
+  }
+
+  private async startOffer(): Promise<void> {
+    const pc = this.pc
+    if (!pc) return
+    if (!this.dc) {
+      this.setupDataChannel(pc.createDataChannel(this.options.channelLabel ?? 'virlen'))
+    }
+    try {
+      const offer = await pc.createOffer()
+      await pc.setLocalDescription(offer)
+      await this.options.signaling.send({ kind: 'offer', sdp: pc.localDescription ?? offer })
+    } catch (err) {
+      this.fail(toBridgeError(err))
+    }
+  }
+
+  private async handleRemote(data: unknown): Promise<void> {
+    const msg = data as SignalData
+    if (!msg || typeof msg !== 'object' || typeof msg.kind !== 'string') return
+    try {
+      if (msg.kind === 'offer') {
+        // 每个 offer 视作新会话：清旧上下文，避免新旧 ICE 串味（同 rtc.js）
+        if (this.pc) this.teardownPeer()
+        const pc = this.ensurePC()
+        await pc.setRemoteDescription(msg.sdp)
+        await this.flushCandidates()
+        const answer = await pc.createAnswer()
+        await pc.setLocalDescription(answer)
+        await this.options.signaling.send({ kind: 'answer', sdp: pc.localDescription ?? answer })
+      } else if (msg.kind === 'answer') {
+        const pc = this.pc
+        if (!pc) return
+        if (pc.signalingState === 'have-local-offer') {
+          await pc.setRemoteDescription(msg.sdp)
+          await this.flushCandidates()
+        }
+      } else if (msg.kind === 'candidate') {
+        const pc = this.pc
+        if (!pc || !msg.cand) return
+        if (pc.remoteDescription && pc.remoteDescription.type) {
+          await pc.addIceCandidate(msg.cand).catch(() => {})
+        } else {
+          this.pendingCandidates.push(msg.cand)
+        }
+      }
+    } catch (err) {
+      this.fail(toBridgeError(err))
+    }
+  }
+
+  private async flushCandidates(): Promise<void> {
+    const list = this.pendingCandidates
+    this.pendingCandidates = []
+    const pc = this.pc
+    if (!pc) return
+    for (const cand of list) {
+      await pc.addIceCandidate(cand).catch(() => {})
+    }
+  }
+
+  private setupDataChannel(channel: RTCDataChannel): void {
+    this.dc = channel
+    try {
+      channel.binaryType = 'arraybuffer'
+    } catch {
+      /* 某些实现只读 */
+    }
+    channel.onopen = () => {
+      this.setState('open')
+      this.readyResolve?.()
+    }
+    channel.onclose = () => {
+      // 通道关闭：等待对端重连（不永久 closed）
+      this.setState('connecting')
+    }
+    channel.onmessage = (e: MessageEvent) => {
+      const bytes = toBytes(e.data)
+      if (!bytes) return
+      for (const listener of [...this.messageListeners]) listener(bytes)
+    }
+  }
+
+  private onConnectionState(connState: RTCPeerConnectionState): void {
+    switch (connState) {
+      case 'connected':
+        // ⚠️ **不在这里置 open**：`connectionState` 可能**早于** DataChannel 的 `open` 触发。
+        // 尤其 guest（手机）侧：dc 是 `ondatachannel` **异步交付**的，此刻 `this.dc` 可能还是 null
+        // → 上层 `whenReady` 已 resolve、`transport.state==='open'`，但 `send()` 因 dc 未就绪而
+        // **静默丢弃**（2026-09 真机踩过：手机“连接超时”，电脑端日志 open→4s→connecting）。
+        // 统一以 `dc.onopen` 为准 —— 回归用例在 rtc-transport.test.ts。
+        break
+      case 'failed':
+      case 'closed':
+        this.setState('closed')
+        this.readyReject?.(new Error(`peer connection ${connState}`))
+        break
+      case 'disconnected':
+        this.setState('connecting')
+        break
+      default:
+        break
+    }
+  }
+
+  private teardownPeer(): void {
+    this.pendingCandidates = []
+    try {
+      this.dc?.close()
+    } catch {
+      /* 忽略 */
+    }
+    try {
+      this.pc?.close()
+    } catch {
+      /* 忽略 */
+    }
+    this.dc = null
+    this.pc = null
+  }
+
+  private fail(error: Error): void {
+    this.readyReject?.(error)
+    this.onErrorListeners?.(error)
+  }
+
+  private onErrorListeners: ((error: Error) => void) | null = null
+
+  /** 订阅「链路级错误」（区别于状态变化）；返回取消订阅函数。 */
+  onError(listener: (error: Error) => void): () => void {
+    this.onErrorListeners = listener
+    return () => {
+      if (this.onErrorListeners === listener) this.onErrorListeners = null
+    }
+  }
+
+  private setState(state: TransportState): void {
+    if (this._state === state) return
+    this._state = state
+    for (const listener of [...this.stateListeners]) listener(state)
+  }
+}
+
+function defaultFactory(): (config: RTCConfiguration) => RTCPeerConnection {
+  return (config: RTCConfiguration) => {
+    const Ctor = (globalThis as { RTCPeerConnection?: new (c: RTCConfiguration) => RTCPeerConnection })
+      .RTCPeerConnection
+    if (!Ctor) {
+      throw new Error('当前环境没有 RTCPeerConnection，未注入 createPeerConnection')
+    }
+    return new Ctor(config)
+  }
+}
+
+function candidateToJson(candidate: RTCIceCandidate): RTCIceCandidateInit {
+  const withJson = candidate as RTCIceCandidate & { toJSON?: () => RTCIceCandidateInit }
+  return typeof withJson.toJSON === 'function' ? withJson.toJSON() : (candidate as unknown as RTCIceCandidateInit)
+}
+
+function toBytes(data: unknown): Uint8Array | null {
+  if (data instanceof Uint8Array) return data
+  if (data instanceof ArrayBuffer) return new Uint8Array(data)
+  return null
+}

package/src/transport/signaling.ts

@@ -0,0 +1,317 @@
+/**
+ * 信令通道抽象 + SSE 实现（对接 virlen-api `/api/rtc`）。
+ *
+ * 分层理由（docs/phone-control-bridge.md §6）：**RtcTransport 只依赖本接口**，不认识 HTTP/SSE。
+ * 于是：
+ *   - 单测可注入「环回信令」验证 offer/answer 编排（不碰网络）；
+ *   - 将来信令换成 WebSocket / 或挪到 Rust，**只换一个实现**。
+ *
+ * 协议（virlen-api `/api/rtc`，M6 设备房间语义，见 §30.3）：
+ *   POST  join   { room, role, deviceKey?, clientName? }
+ *                → { id, room, role, ip, hostOnline, peers }
+ *   GET   events ?room&id
+ *                → SSE：{ type: 'peers' | 'peer-joined' | 'peer-left' | 'signal' | 'kicked' }
+ *   POST  signal { room, from, to, data }
+ *   POST  status { rooms: string[] }   → { rooms: RoomStatus[] }（批量在线查询，不占房间）
+ *
+ * 角色语义（**M6 起服务器强制**）：
+ *   - `room` 由**电脑设备 key** 派生（`roomFor`），不再由客户端自定；
+ *   - 同一房间**最多一个 host、一个 guest**；新 guest 加入会**顶掉**旧 guest（旧端收 `kicked`）；
+ *   - 同 key 的 host 重入 = 接管（电脑重启后旧连接多是死连接）。
+ */
+import { BridgeError } from '../protocol/errors'
+import { roomFor, type RoomStatus } from '../protocol/identity'
+
+export type SignalingRole = 'host' | 'guest'
+
+/** 被顶号的通知内容（服务器 `kicked` 事件）。 */
+export interface KickedInfo {
+  /** `replaced` = 同一台电脑已有新的手机接入（本端被顶掉）；`takeover` = 电脑端重入接管。 */
+  reason: string
+}
+
+/** `EventSource` 的最小形状（注入测试替身用）。 */
+export interface EventSourceLike {
+  onopen: ((event: unknown) => void) | null
+  onerror: ((event: unknown) => void) | null
+  onmessage: ((event: { data: string }) => void) | null
+  close(): void
+}
+
+export interface SignalingChannel {
+  readonly selfId: string
+  readonly peerId: string | null
+  onPeer: ((peerId: string | null) => void) | null
+  onData: ((data: unknown) => void) | null
+  onError: ((error: Error) => void) | null
+  /**
+   * 本端被服务端顶号（**不是**普通掉线）。
+   *
+   * 为什么必须独立成回调而不是兼做 `onError`：上层要做出**完全相反的动作** ——
+   * 普通掉线自动重连，被顶号**绝不能自动重连**（否则两台手机会互相顶来顶去）。
+   */
+  onKicked: ((info: KickedInfo) => void) | null
+  /** 加入房间；返回本端 id。 */
+  join(): Promise<string>
+  /** 把一条信令发给当前对端（无对端时 no-op）。 */
+  send(data: unknown): Promise<void>
+  close(): void
+}
+
+export interface SseSignalingOptions {
+  /** 信令基址，如 `https://virlen.cn/api/rtc/`（末尾斜杠可有可无）。 */
+  baseUrl: string
+  room: string
+  role: SignalingRole
+  /** 本端设备 key（电脑 `dk-…` / 手机 `mk-…`）；服务器用于日志与 host 房主校验。 */
+  deviceKey?: string
+  /** 本端显示名（服务器日志可读性）。 */
+  clientName?: string
+  /**
+   * 加入时要求房间内已有 host（手机端用）。
+   * 无 host 时 `join()` 直接抛错 —— 比「先占住 guest 位再等 15 秒超时」诚实得多。
+   */
+  requireHostOnline?: boolean
+  /** 注入（测试用）；默认取全局 `fetch`。 */
+  fetchImpl?: typeof fetch
+  /** 注入（测试用）；默认 `(url) => new EventSource(url)`。 */
+  eventSourceFactory?: (url: string) => EventSourceLike
+}
+
+interface JoinResponse {
+  id: string
+  room: string
+  role: string
+  ip?: string
+  peers?: Array<{ id: string; role: string }>
+  /** 加入时房间里是否已有 host（M6）。 */
+  hostOnline?: boolean
+}
+
+type ServerEvent =
+  | { type: 'peers'; peers: Array<{ id: string; role: string }> }
+  | { type: 'peer-joined'; peer: { id: string; role: string } }
+  | { type: 'peer-left'; id: string }
+  | { type: 'signal'; from: string; data: unknown }
+  | { type: 'kicked'; reason?: string }
+
+function normalizeBase(baseUrl: string): string {
+  return baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`
+}
+
+export class SseSignalingClient implements SignalingChannel {
+  selfId = ''
+  peerId: string | null = null
+  onPeer: ((peerId: string | null) => void) | null = null
+  onData: ((data: unknown) => void) | null = null
+  onError: ((error: Error) => void) | null = null
+  onKicked: ((info: KickedInfo) => void) | null = null
+
+  private readonly base: string
+  private es: EventSourceLike | null = null
+  private closed = false
+  /** 被顶号后置位：此后一切信令发送都无意义（房间已把我们移除）。 */
+  private kicked = false
+
+  constructor(private readonly options: SseSignalingOptions) {
+    this.base = normalizeBase(options.baseUrl)
+  }
+
+  async join(): Promise<string> {
+    const res = await this.fetch()(this.base + 'join', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        room: this.options.room,
+        role: this.options.role,
+        ...(this.options.deviceKey ? { deviceKey: this.options.deviceKey } : {}),
+        ...(this.options.clientName ? { clientName: this.options.clientName } : {}),
+      }),
+    })
+    if (!res.ok) {
+      const detail = await readErrorDetail(res)
+      throw new BridgeError('E_TRANSPORT', `信令 join 失败：HTTP ${res.status}${detail}`)
+    }
+    const info = (await res.json()) as JoinResponse
+    this.selfId = info.id
+    // 手机端：电脑不在线就别占着 guest 位 —— 直接失败，让上层给「电脑不在线」
+    if (this.options.role === 'guest' && this.options.requireHostOnline && info.hostOnline === false) {
+      throw new BridgeError('E_TRANSPORT', '电脑不在线（信令房间内没有 host）', {
+        data: { reason: 'host-offline' },
+      })
+    }
+    this.openEvents()
+    // 房间里可能已有对端（本端后加入）→ 立刻通知，避免只依赖 peer-joined
+    const existing = (info.peers ?? []).find((p) => p.id !== this.selfId)
+    if (existing) this.setPeer(existing.id)
+    return this.selfId
+  }
+
+  async send(data: unknown): Promise<void> {
+    if (!this.peerId || this.kicked || this.closed) return
+    await this.fetch()(this.base + 'signal', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        room: this.options.room,
+        from: this.selfId,
+        to: this.peerId,
+        data,
+      }),
+    }).catch(() => {
+      /* 信令转发失败：ICE 会重试/另择候选，不回滚 */
+    })
+  }
+
+  close(): void {
+    if (this.closed) return
+    this.closed = true
+    try {
+      this.es?.close()
+    } catch {
+      /* 忽略 */
+    }
+    this.es = null
+  }
+
+  private fetch(): typeof fetch {
+    if (this.options.fetchImpl) return this.options.fetchImpl
+    if (typeof fetch === 'function') return fetch
+    throw new BridgeError('E_INTERNAL', '当前环境没有 fetch，未注入 fetchImpl')
+  }
+
+  private openEvents(): void {
+    const factory = this.options.eventSourceFactory ?? defaultEventSourceFactory()
+    const url = `${this.base}events?room=${encodeURIComponent(this.options.room)}&id=${encodeURIComponent(this.selfId)}`
+    const es = factory(url)
+    es.onopen = () => {
+      /* 连接就绪：无操作（首个事件即 peers） */
+    }
+    es.onerror = () => {
+      if (!this.closed) this.onError?.(new Error('信令事件流异常'))
+    }
+    es.onmessage = (ev) => this.route(ev.data)
+    this.es = es
+  }
+
+  private route(raw: string): void {
+    let msg: ServerEvent
+    try {
+      msg = JSON.parse(raw) as ServerEvent
+    } catch {
+      return
+    }
+    switch (msg.type) {
+      case 'peers': {
+        const other = msg.peers.find((p) => p.id !== this.selfId)
+        if (other) this.setPeer(other.id)
+        break
+      }
+      case 'peer-joined':
+        this.setPeer(msg.peer.id)
+        break
+      case 'peer-left':
+        this.setPeer(null)
+        break
+      case 'kicked':
+        this.handleKicked(msg.reason ?? 'replaced')
+        break
+      case 'signal':
+        this.onData?.(msg.data)
+        break
+      default:
+        break
+    }
+  }
+
+  /**
+   * 被顶号：先通知上层（它要据此关掉自动重连），再关掉事件流。
+   *
+   * 顺序很重要：`onKicked` 里上层会去 `transport.close()`，而 reconnect 的判定
+   * 就在那条路径上 —— 先把「被顶号」这个事实告知，再关流，才不会出现「先判定为重连、后知道是顶号」。
+   */
+  private handleKicked(reason: string): void {
+    if (this.kicked) return
+    this.kicked = true
+    this.peerId = null
+    try {
+      this.onKicked?.({ reason })
+    } finally {
+      this.close()
+    }
+  }
+
+  private setPeer(peerId: string | null): void {
+    if (this.peerId === peerId) return
+    this.peerId = peerId
+    this.onPeer?.(peerId)
+  }
+}
+
+function defaultEventSourceFactory(): (url: string) => EventSourceLike {
+  return (url: string) => {
+    const ES = (globalThis as unknown as { EventSource?: new (url: string) => EventSourceLike }).EventSource
+    if (!ES) {
+      throw new BridgeError('E_INTERNAL', '当前环境没有 EventSource，未注入 eventSourceFactory')
+    }
+    return new ES(url)
+  }
+}
+
+/** 从失败的 join 应答里取一句可读的原因（服务器给 `{ error }`）。 */
+async function readErrorDetail(res: Response): Promise<string> {
+  try {
+    const body = (await res.json()) as { error?: unknown }
+    if (typeof body?.error === 'string' && body.error) return `（${body.error}）`
+  } catch {
+    /* 非 JSON 应答：忽略 */
+  }
+  return ''
+}
+
+/** 批量查房间在线状态（**不加入房间**，不占 guest 位）。 */
+export interface FetchRoomStatusOptions {
+  /** 信令基址，如 `https://virlen.cn/api/rtc/`。 */
+  baseUrl: string
+  /** 要查的房间号（由 `roomFor(电脑 key)` 派生）。 */
+  rooms: string[]
+  fetchImpl?: typeof fetch
+}
+
+/**
+ * 查询一批房间的在线状态。
+ *
+ * 失败时**返回空数组而不抛错**：手机端列表的「在线状态」只是提示，
+ * 信令服务不可用/版本过旧（无 `/status`）时应当退化为「未知」，而不是把整个列表打挂。
+ */
+export async function fetchRoomStatus(options: FetchRoomStatusOptions): Promise<RoomStatus[]> {
+  const rooms = options.rooms.filter((r) => typeof r === 'string' && r)
+  if (rooms.length === 0) return []
+  const fetchImpl = options.fetchImpl ?? (typeof fetch === 'function' ? fetch : null)
+  if (!fetchImpl) return []
+  try {
+    const res = await fetchImpl(normalizeBase(options.baseUrl) + 'status', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ rooms }),
+    })
+    if (!res.ok) return []
+    const body = (await res.json()) as { rooms?: RoomStatus[] }
+    return Array.isArray(body?.rooms) ? body.rooms : []
+  } catch {
+    return []
+  }
+}
+
+/** 便利封装：`电脑 key → 在线?`（手机端列表用）。 */
+export async function fetchHostOnlineMap(
+  baseUrl: string,
+  hostKeys: string[],
+  fetchImpl?: typeof fetch,
+): Promise<Map<string, boolean>> {
+  const statuses = await fetchRoomStatus({ baseUrl, rooms: hostKeys.map(roomFor), ...(fetchImpl ? { fetchImpl } : {}) })
+  const byRoom = new Map(statuses.map((s) => [s.room, s.hostOnline]))
+  const out = new Map<string, boolean>()
+  for (const key of hostKeys) out.set(key, byRoom.get(roomFor(key)) ?? false)
+  return out
+}