virlen-remote 0.1.0

package/dist/transport/signaling.js

@@ -0,0 +1,235 @@
+/**
+ * 信令通道抽象 + 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.js';
+import { roomFor } from '../protocol/identity.js';
+function normalizeBase(baseUrl) {
+    return baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+}
+export class SseSignalingClient {
+    constructor(options) {
+        this.options = options;
+        this.selfId = '';
+        this.peerId = null;
+        this.onPeer = null;
+        this.onData = null;
+        this.onError = null;
+        this.onKicked = null;
+        this.es = null;
+        this.closed = false;
+        /** 被顶号后置位：此后一切信令发送都无意义（房间已把我们移除）。 */
+        this.kicked = false;
+        this.base = normalizeBase(options.baseUrl);
+    }
+    async join() {
+        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());
+        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) {
+        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() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            this.es?.close();
+        }
+        catch {
+            /* 忽略 */
+        }
+        this.es = null;
+    }
+    fetch() {
+        if (this.options.fetchImpl)
+            return this.options.fetchImpl;
+        if (typeof fetch === 'function')
+            return fetch;
+        throw new BridgeError('E_INTERNAL', '当前环境没有 fetch，未注入 fetchImpl');
+    }
+    openEvents() {
+        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;
+    }
+    route(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        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 的判定
+     * 就在那条路径上 —— 先把「被顶号」这个事实告知，再关流，才不会出现「先判定为重连、后知道是顶号」。
+     */
+    handleKicked(reason) {
+        if (this.kicked)
+            return;
+        this.kicked = true;
+        this.peerId = null;
+        try {
+            this.onKicked?.({ reason });
+        }
+        finally {
+            this.close();
+        }
+    }
+    setPeer(peerId) {
+        if (this.peerId === peerId)
+            return;
+        this.peerId = peerId;
+        this.onPeer?.(peerId);
+    }
+}
+function defaultEventSourceFactory() {
+    return (url) => {
+        const ES = globalThis.EventSource;
+        if (!ES) {
+            throw new BridgeError('E_INTERNAL', '当前环境没有 EventSource，未注入 eventSourceFactory');
+        }
+        return new ES(url);
+    };
+}
+/** 从失败的 join 应答里取一句可读的原因（服务器给 `{ error }`）。 */
+async function readErrorDetail(res) {
+    try {
+        const body = (await res.json());
+        if (typeof body?.error === 'string' && body.error)
+            return `（${body.error}）`;
+    }
+    catch {
+        /* 非 JSON 应答：忽略 */
+    }
+    return '';
+}
+/**
+ * 查询一批房间的在线状态。
+ *
+ * 失败时**返回空数组而不抛错**：手机端列表的「在线状态」只是提示，
+ * 信令服务不可用/版本过旧（无 `/status`）时应当退化为「未知」，而不是把整个列表打挂。
+ */
+export async function fetchRoomStatus(options) {
+    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());
+        return Array.isArray(body?.rooms) ? body.rooms : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** 便利封装：`电脑 key → 在线?`（手机端列表用）。 */
+export async function fetchHostOnlineMap(baseUrl, hostKeys, fetchImpl) {
+    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();
+    for (const key of hostKeys)
+        out.set(key, byRoom.get(roomFor(key)) ?? false);
+    return out;
+}
+//# sourceMappingURL=signaling.js.map

package/dist/transport/signaling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signaling.js","sourceRoot":"","sources":["../../src/transport/signaling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,OAAO,EAAmB,MAAM,sBAAsB,CAAA;AA2E/D,SAAS,aAAa,CAAC,OAAe;IACpC,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,CAAA;AACxD,CAAC;AAED,MAAM,OAAO,kBAAkB;IAc7B,YAA6B,OAA4B;QAA5B,YAAO,GAAP,OAAO,CAAqB;QAbzD,WAAM,GAAG,EAAE,CAAA;QACX,WAAM,GAAkB,IAAI,CAAA;QAC5B,WAAM,GAA6C,IAAI,CAAA;QACvD,WAAM,GAAqC,IAAI,CAAA;QAC/C,YAAO,GAAoC,IAAI,CAAA;QAC/C,aAAQ,GAAwC,IAAI,CAAA;QAG5C,OAAE,GAA2B,IAAI,CAAA;QACjC,WAAM,GAAG,KAAK,CAAA;QACtB,qCAAqC;QAC7B,WAAM,GAAG,KAAK,CAAA;QAGpB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IAC5C,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,IAAI,GAAG,MAAM,EAAE;YACjD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI;gBACvB,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI;gBACvB,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACxE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC5E,CAAC;SACH,CAAC,CAAA;QACF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,CAAA;YACzC,MAAM,IAAI,WAAW,CAAC,aAAa,EAAE,mBAAmB,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,CAAA;QAChF,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAiB,CAAA;QAC/C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAA;QACrB,4CAA4C;QAC5C,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,iBAAiB,IAAI,IAAI,CAAC,UAAU,KAAK,KAAK,EAAE,CAAC;YACjG,MAAM,IAAI,WAAW,CAAC,aAAa,EAAE,qBAAqB,EAAE;gBAC1D,IAAI,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE;aACjC,CAAC,CAAA;QACJ,CAAC;QACD,IAAI,CAAC,UAAU,EAAE,CAAA;QACjB,2CAA2C;QAC3C,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,MAAM,CAAC,CAAA;QACrE,IAAI,QAAQ;YAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;QACvC,OAAO,IAAI,CAAC,MAAM,CAAA;IACpB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAa;QACtB,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM;YAAE,OAAM;QACtD,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,IAAI,GAAG,QAAQ,EAAE;YACvC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI;gBACvB,IAAI,EAAE,IAAI,CAAC,MAAM;gBACjB,EAAE,EAAE,IAAI,CAAC,MAAM;gBACf,IAAI;aACL,CAAC;SACH,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;YACZ,6BAA6B;QAC/B,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,MAAM;YAAE,OAAM;QACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;QAClB,IAAI,CAAC;YACH,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,CAAA;QAClB,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ;QACV,CAAC;QACD,IAAI,CAAC,EAAE,GAAG,IAAI,CAAA;IAChB,CAAC;IAEO,KAAK;QACX,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,CAAA;QACzD,IAAI,OAAO,KAAK,KAAK,UAAU;YAAE,OAAO,KAAK,CAAA;QAC7C,MAAM,IAAI,WAAW,CAAC,YAAY,EAAE,4BAA4B,CAAC,CAAA;IACnE,CAAC;IAEO,UAAU;QAChB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,kBAAkB,IAAI,yBAAyB,EAAE,CAAA;QAC9E,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,IAAI,eAAe,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAA;QACpH,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;QACvB,EAAE,CAAC,MAAM,GAAG,GAAG,EAAE;YACf,2BAA2B;QAC7B,CAAC,CAAA;QACD,EAAE,CAAC,OAAO,GAAG,GAAG,EAAE;YAChB,IAAI,CAAC,IAAI,CAAC,MAAM;gBAAE,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAA;QACxD,CAAC,CAAA;QACD,EAAE,CAAC,SAAS,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,CAAA;QAC1C,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;IACd,CAAC;IAEO,KAAK,CAAC,GAAW;QACvB,IAAI,GAAgB,CAAA;QACpB,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAgB,CAAA;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,OAAM;QACR,CAAC;QACD,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;YACjB,KAAK,OAAO,EAAE,CAAC;gBACb,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,MAAM,CAAC,CAAA;gBACzD,IAAI,KAAK;oBAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;gBACjC,MAAK;YACP,CAAC;YACD,KAAK,aAAa;gBAChB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;gBACzB,MAAK;YACP,KAAK,WAAW;gBACd,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;gBAClB,MAAK;YACP,KAAK,QAAQ;gBACX,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,IAAI,UAAU,CAAC,CAAA;gBAC3C,MAAK;YACP,KAAK,QAAQ;gBACX,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;gBACvB,MAAK;YACP;gBACE,MAAK;QACT,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,YAAY,CAAC,MAAc;QACjC,IAAI,IAAI,CAAC,MAAM;YAAE,OAAM;QACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;QAClB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;QAClB,IAAI,CAAC;YACH,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QAC7B,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,KAAK,EAAE,CAAA;QACd,CAAC;IACH,CAAC;IAEO,OAAO,CAAC,MAAqB;QACnC,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM;YAAE,OAAM;QAClC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAA;IACvB,CAAC;CACF;AAED,SAAS,yBAAyB;IAChC,OAAO,CAAC,GAAW,EAAE,EAAE;QACrB,MAAM,EAAE,GAAI,UAAgF,CAAC,WAAW,CAAA;QACxG,IAAI,CAAC,EAAE,EAAE,CAAC;YACR,MAAM,IAAI,WAAW,CAAC,YAAY,EAAE,2CAA2C,CAAC,CAAA;QAClF,CAAC;QACD,OAAO,IAAI,EAAE,CAAC,GAAG,CAAC,CAAA;IACpB,CAAC,CAAA;AACH,CAAC;AAED,+CAA+C;AAC/C,KAAK,UAAU,eAAe,CAAC,GAAa;IAC1C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAwB,CAAA;QACtD,IAAI,OAAO,IAAI,EAAE,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,IAAI,CAAC,KAAK,GAAG,CAAA;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;IACD,OAAO,EAAE,CAAA;AACX,CAAC;AAWD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAA+B;IACnE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAA;IACrE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACjC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;IACnF,IAAI,CAAC,SAAS;QAAE,OAAO,EAAE,CAAA;IACzB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,QAAQ,EAAE;YACrE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC;SAChC,CAAC,CAAA;QACF,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,EAAE,CAAA;QACtB,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA6B,CAAA;QAC3D,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAA;IACX,CAAC;AACH,CAAC;AAED,mCAAmC;AACnC,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAe,EACf,QAAkB,EAClB,SAAwB;IAExB,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;IACtH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;IACnE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAmB,CAAA;IACtC,KAAK,MAAM,GAAG,IAAI,QAAQ;QAAE,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAA;IAC3E,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/transport/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Transport 抽象 —— 协议层与「字节通道实现」之间的唯一边界。
+ *
+ * 两条关键设计：
+ * 1. **UI 永不直接碰这里**（docs/phone-control-bridge.md §1）：协议层只依赖本接口，
+ *    将来把 RTC 整体挪到 Rust 时，**只换一个实现**，上面全部不动。
+ * 2. **`bufferedAmount` 是必需的**：DataChannel 的 `send()` 不阻塞，
+ *    接收慢时缓冲会静默堆积到爆内存 → 协议层据此做背压（§3.2）。
+ */
+export type TransportState = 'connecting' | 'open' | 'closed';
+export interface Transport {
+    readonly state: TransportState;
+    /** 未发送出去的字节数（DataChannel 的 `bufferedAmount`；内存实现恒为 0）。 */
+    readonly bufferedAmount: number;
+    /** 发送一帧（可能被实现内部缓冲/异步投递）。链路非 open 时实现方负责丢弃。 */
+    send(bytes: Uint8Array): void;
+    /** 关闭链路。 */
+    close(): void;
+    /** 订阅「收到一帧」；返回取消订阅函数。 */
+    onMessage(listener: (bytes: Uint8Array) => void): () => void;
+    /** 订阅「链路状态变化」；返回取消订阅函数。 */
+    onStateChange(listener: (state: TransportState) => void): () => void;
+    /**
+     * 可选：等待链路真正可用（RTC 需要先完成信令 + ICE 才 open）。
+     * 内存 / Broadcast 实现创建即 open，可不实现此方法。
+     */
+    whenReady?(): Promise<void>;
+    /** 可选：启动链路（RTC 需要先加入信令房间并开始协商）。内存 / Broadcast 无需启动。 */
+    start?(): void | Promise<void>;
+    /**
+     * 可选：订阅「链路级错误」。
+     *
+     * 为什么必需（M6）：**被顶号**是一种错误而不是状态 —— 它对应的动作与「掉线（closed）」
+     * 完全相反（掉线要自动重连，被顶号绝不能）。只有 `code === 'E_REPLACED'` 会被这样使用，
+     * 见 `transport/rtc.ts` 与手机端 `store/connection.ts`。
+     *
+     * 内存 / Broadcast 实现没有致命错误，可不实现。
+     */
+    onError?(listener: (error: Error) => void): () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/transport/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/transport/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAA;AAE7D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAE9B,0DAA0D;IAC1D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAE/B,8CAA8C;IAC9C,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;IAE7B,YAAY;IACZ,KAAK,IAAI,IAAI,CAAA;IAEb,yBAAyB;IACzB,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAE5D,2BAA2B;IAC3B,aAAa,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAEpE;;;OAGG;IACH,SAAS,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAE3B,uDAAuD;IACvD,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE9B;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;CACvD"}

package/dist/transport/types.js

@@ -0,0 +1,11 @@
+/**
+ * Transport 抽象 —— 协议层与「字节通道实现」之间的唯一边界。
+ *
+ * 两条关键设计：
+ * 1. **UI 永不直接碰这里**（docs/phone-control-bridge.md §1）：协议层只依赖本接口，
+ *    将来把 RTC 整体挪到 Rust 时，**只换一个实现**，上面全部不动。
+ * 2. **`bufferedAmount` 是必需的**：DataChannel 的 `send()` 不阻塞，
+ *    接收慢时缓冲会静默堆积到爆内存 → 协议层据此做背压（§3.2）。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/transport/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/transport/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "virlen-remote",
+  "version": "0.1.0",
+  "description": "Virlen 手机控制 · 协议栈共享包 —— 帧 / RPC / 错误 / 能力协商 / 设备身份与授权凭证 / 配对载荷 / ICE 解析 / Transport（WebRTC / 内存 / Broadcast）",
+  "license": "MIT",
+  "author": "WeiChens",
+  "keywords": [
+    "virlen",
+    "webrtc",
+    "rtc",
+    "p2p",
+    "datachannel",
+    "signaling",
+    "sse",
+    "rpc",
+    "typescript",
+    "browser"
+  ],
+  "homepage": "https://github.com/WeiChens/virlen-remote#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WeiChens/virlen-remote.git"
+  },
+  "bugs": {
+    "url": "https://github.com/WeiChens/virlen-remote/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "devDependencies": {
+    "typescript": "~7.0.2",
+    "vitest": "^4.1.9"
+  }
+}

package/src/index.ts

@@ -0,0 +1,155 @@
+/**
+ * virlen-remote —— 手机控制协议栈共享包
+ *
+ * 电脑端（virlen-app）与手机端（virlen-mobile）共用同一份实现
+ * （见 docs/phone-control-bridge.md §1「越往下越同构」、§6「共享包」）。
+ *
+ * 分层：
+ *   protocol/   与传输无关的逻辑（帧 / RPC / 错误 / 能力协商 / 方法表）
+ *   transport/  字节通道抽象 + 内存实现（RTC 实现属 M3）
+ *
+ * **零运行时依赖**：WebRTC 用浏览器原生 `RTCPeerConnection`；Node 侧只用 memory transport 做测试。
+ */
+
+// ── protocol ──
+export { PROTOCOL_VERSION, HEADER_SIZE, DEFAULT_MAX_FRAME_PAYLOAD, FrameKind } from './protocol/frame'
+export { encodeHeader, decodeHeader, frameBody, encodeFrames, Reassembler } from './protocol/frame'
+export type { FrameHeader, DecodedMessage } from './protocol/frame'
+
+export { BridgeError, toBridgeError } from './protocol/errors'
+export type { ErrorCode, WireError, BridgeErrorOptions } from './protocol/errors'
+
+export { newRequestId } from './protocol/ids'
+
+// ── 设备身份与授权凭证（M6，§30）──
+export {
+  HOST_KEY_PREFIX,
+  MOBILE_KEY_PREFIX,
+  GRANT_PREFIX,
+  ROOM_PREFIX,
+  GRANT_TTL_MS,
+  GRANT_MAX_LIFETIME_MS,
+  randomKey,
+  newDeviceKey,
+  newGrantToken,
+  isDeviceKey,
+  roomFor,
+  hostKeyFromRoom,
+  issueGrant,
+  isGrantExpired,
+  renewGrant,
+  checkGrant,
+  describeGrantRemaining,
+} from './protocol/identity'
+export type { DeviceKind, GrantRecord, CredentialRejectReason, RoomStatus } from './protocol/identity'
+
+// ── 配对载荷（二维码内容，两端同一份）──
+export {
+  PAIRING_PAYLOAD_VERSION,
+  PAIRING_TICKET_TTL_MS,
+  buildPairingPayload,
+  encodePairingPayload,
+  parsePairingPayload,
+  roomOfPayload,
+} from './protocol/pairing'
+export type { PairingPayload } from './protocol/pairing'
+
+export { normalizeChoiceAnswer, answerActionError, CHOICE_JOINER } from './protocol/answer'
+export type { ChoiceAnswer } from './protocol/answer'
+
+export { negotiate, intersectCapabilities } from './protocol/hello'
+
+export { Endpoint } from './protocol/endpoint'
+export type {
+  CallContext,
+  EventContext,
+  RpcHandler,
+  EventSubscriber,
+  CallOptions,
+  EndpointOptions,
+} from './protocol/endpoint'
+
+export { createCaller, createSubscriber, registerHandlers } from './protocol/api'
+export { DEFAULT_CONTEXT_WINDOW_TOKENS, COMPRESS_MIN_RATIO } from './protocol/api'
+export type {
+  ParamsOf,
+  ResultOf,
+  TypedCaller,
+  TypedSubscriber,
+  HandlerImpl,
+  HostApi,
+  MobileApi,
+  HostEvents,
+  MobileEvents,
+  SessionSummaryDTO,
+  MessageDTO,
+  RuntimeDTO,
+  InteractionDTO,
+  InteractionOutcome,
+  StreamMode,
+  ApprovalTier,
+  SendParams,
+  MsgPageParams,
+  MsgPageDTO,
+  AnswerParams,
+  AnswerAction,
+  AnswerResult,
+  AnswerRejectReason,
+  CreateSessionParams,
+  RenameSessionParams,
+  PinSessionParams,
+  DeleteSessionParams,
+  ModelProviderDTO,
+  WorkspaceOptionDTO,
+  ContextInfoDTO,
+  SetModelParams,
+  ContextParams,
+  CompressParams,
+} from './protocol/api'
+export type { HelloParams, HelloResult, ClientInfo, NegotiationInput, Negotiated } from './protocol/hello'
+
+export { registerHostHandlers } from './protocol/host'
+export type { HostDataSource, HostEmit, HostRegistration, RegisterHostOptions } from './protocol/host'
+// ── transport ──
+export type { Transport, TransportState } from './transport/types'
+export { MemoryTransport, createMemoryPair } from './transport/memory'
+export type { MemoryTransportMetrics } from './transport/memory'
+export { BroadcastTransport, createBroadcastPair } from './transport/broadcast'
+export { SseSignalingClient, fetchRoomStatus, fetchHostOnlineMap } from './transport/signaling'
+export type {
+  SignalingChannel,
+  SignalingRole,
+  SseSignalingOptions,
+  EventSourceLike,
+  KickedInfo,
+  FetchRoomStatusOptions,
+} from './transport/signaling'
+export { RtcTransport } from './transport/rtc'
+export type { RtcTransportOptions } from './transport/rtc'
+
+// ── ICE 配置（M7，§31）：客户端不再内置任何 TURN 凭证 ──
+export {
+  ICE_CONFIG_VERSION,
+  ICE_API_PATH,
+  ICE_CUSTOM_STORAGE_KEY,
+  ICE_REMOTE_STORAGE_KEY,
+  ICE_CACHE_TTL_MS,
+  ICE_FETCH_TIMEOUT_MS,
+  sanitizeIceServers,
+  parseIceText,
+  formatIceServers,
+  describeIceSource,
+  fetchIceServers,
+  resolveIceServers,
+  readCustomIceText,
+  writeCustomIceText,
+} from './transport/ice'
+export type {
+  IceServerInit,
+  IceSource,
+  IceStoragePort,
+  ResolvedIceServers,
+  ParseIceResult,
+  FetchIceOptions,
+  ResolveIceOptions,
+} from './transport/ice'

package/src/protocol/answer.ts

@@ -0,0 +1,89 @@
+/**
+ * 应答载荷的规范化 —— **手机侧与电脑侧共用同一份**（M4）。
+ *
+ * 为什么必须共用：手机回答「AI 提问」时，最终要交给引擎的是一个 `ToolResult`
+ * （`{ content, uiData }`），而电脑侧 UI 早就定下了这个形态（见 `tool-ui.tsx`）：
+ * `content` = `[selected.join(', '), customReply].filter(Boolean).join('；')`。
+ *
+ * 如果手机侧、电脑侧桥接层、mock 宿主各写一份「怎么拼」，三份必然漂移
+ * —— 而漂移的表现是「AI 收到了内容，但消息渲染不出来（`uiData` 缺失）」这种**看不出错在谁**的故障。
+ * 故：**唯一实现放这里**，其余全部调用它。
+ *
+ * 手机端允许三种输入（宽容解析，避免因 UI 形态变化而连带改协议）：
+ * - 字符串 → 等价于「自定义回复」；
+ * - 字符串数组 → 等价于「选中了这些选项」；
+ * - 对象 `{ selected?, customReply? }` → 精确形态（推荐）。
+ *
+ * 空结果一律返回 `null`（调用方据此回 `invalid-value`）——
+ * 给引擎发一条空回执会让 AI 无从判断用户到底选了什么。
+ */
+import type { AnswerAction, AnswerRejectReason, InteractionDTO } from './api'
+
+export interface ChoiceAnswer {
+  content: string
+  uiData: { selected: string[]; customReply: string }
+}
+
+/** 分隔符：与电脑侧 UI 的 `t('；')` 一致（中文分号）。 */
+export const CHOICE_JOINER = '；'
+
+export function normalizeChoiceAnswer(value: unknown): ChoiceAnswer | null {
+  let selected: string[] = []
+  let customReply = ''
+
+  if (typeof value === 'string') {
+    customReply = value.trim()
+  } else if (Array.isArray(value)) {
+    selected = value
+      .filter((v): v is string => typeof v === 'string')
+      .map((v) => v.trim())
+      .filter(Boolean)
+  } else if (value && typeof value === 'object') {
+    const v = value as { selected?: unknown; customReply?: unknown }
+    if (Array.isArray(v.selected)) {
+      selected = v.selected
+        .filter((x): x is string => typeof x === 'string')
+        .map((x) => x.trim())
+        .filter(Boolean)
+    }
+    if (typeof v.customReply === 'string') customReply = v.customReply.trim()
+  } else {
+    return null
+  }
+
+  if (!selected.length && !customReply) return null
+  const parts: string[] = []
+  if (selected.length) parts.push(selected.join(', '))
+  if (customReply) parts.push(customReply)
+  return { content: parts.join(CHOICE_JOINER), uiData: { selected, customReply } }
+}
+
+/**
+ * 应答动作的**合法性校验** —— 真实电脑侧（`interaction-registry`）与 mock 宿主共用同一份。
+ *
+ * 为什么放在共享包（M4 教训延续，2026-09-27 真机反馈）：动作「对某类交互是否合法」是**协议语义**，
+ * 不是某一端的实现细节。两端各写一份时 mock 会偏宽松 ——
+ * 「手机对 AI 提问点取消 → 真实电脑端回 `unsupported-by-host`」这类缺陷在手机端单测里测不出来，
+ * 只能等到真机才暴露。
+ *
+ * 判据（与桌面 `tool-ui.tsx` 的按钮一一对应）：
+ * - `choice`（AI 提问）：`choose` 确认 / `deny` 取消 / `shelve` 暂存；`allow` 无意义；
+ * - `authorization`（授权）：`allow` / `deny` / `shelve`；`choose` 无意义；
+ * - `authorization + presentation: 'terminal'`（终端内确认）：**没有暂存语义**
+ *   （它是「命令已就绪，等你按回车」，没有可暂存的对象）。
+ *
+ * @returns 不合法时返回拒绝原因（固定 `unsupported-by-host`）；合法时返回 `null`。
+ */
+export function answerActionError(
+  interaction: Pick<InteractionDTO, 'kind' | 'presentation'>,
+  action: AnswerAction,
+): AnswerRejectReason | null {
+  if (interaction.kind === 'choice') {
+    return action === 'allow' ? 'unsupported-by-host' : null
+  }
+  if (action === 'choose') return 'unsupported-by-host'
+  if (action === 'shelve' && interaction.presentation === 'terminal') {
+    return 'unsupported-by-host'
+  }
+  return null
+}