im-rtc-call-engine 1.0.0

package/dist/media/mediaBridge.d.ts

@@ -0,0 +1,99 @@
+import type { MediaAdapter, MediaAdapterEvents } from './mediaAdapter.js';
+import type { ViewElement } from './viewRegistry.js';
+/** RemoteTrackOwner 是「这条 track_id 是谁的」的最小查询接口。 */
+export interface RemoteTrackOwner {
+    readonly uid: string;
+}
+/**
+ * MediaBridge 把媒体适配器与 uid↔元素的挂载登记捆在一起。
+ *
+ * # 为什么捆在一起
+ *
+ * 这三样东西的生命周期是同一个：**一轮房间**。通话结束、离房、房间被关掉时，
+ * PeerConnection 要重建、挂载登记要清空、「首帧抛过没有」也要忘掉。
+ * 散在门面里的话，总有一处会在某条结束路径上被漏掉——而漏掉的表现
+ * 是下一通电话带着上一通的轨道去协商，服务端只会记一句
+ * 「收到未登记的上行 Track」然后丢掉，界面上则是黑屏。
+ */
+export declare class MediaBridge {
+    readonly adapter: MediaAdapter;
+    private readonly views;
+    /** 已经抛过「首帧」的轨道，避免重复抛。 */
+    private readonly seenVideo;
+    /** 开摄像头之后等新画面上屏的那些人（见 awaitFirstVideoFrame）。 */
+    private readonly firstFrames;
+    private events;
+    constructor(adapter: MediaAdapter);
+    /** open 建两条 PeerConnection。 */
+    open(events: MediaAdapterEvents): void;
+    /**
+     * reset 把这一轮的媒体全部归零，并重建 PeerConnection。
+     *
+     * PC 是**跟着房间走**的：服务端每次进房都新建一对，客户端这边不重建的话，
+     * 上一轮的 transceiver 还挂在上面，下一轮的 offer 会多出几条服务端不认识的 m-line。
+     */
+    reset(): void;
+    /** close 彻底关掉（logout）。 */
+    close(): void;
+    /**
+     * addRemoteTrack 收下一条下行轨道。
+     *
+     * uid 允许为空——`ontrack` 与 `room.track_published` 谁先到都可能，
+     * 归属后到时由 claim 补上。
+     *
+     * `onFirstVideo` 在这条视频轨**真的开始出数据**时回调一次，见 waitForVideo。
+     */
+    addRemoteTrack(trackId: string, track: MediaStreamTrack, uid: string, onFirstVideo: (trackId: string) => void): void;
+    /**
+     * waitForVideo 等这条视频轨真的开始出数据。
+     *
+     * **`ontrack` 触发 ≠ 有画面**：远端轨道刚协商完时 `muted === true`，
+     * 要等第一个 RTP 包到达才 `unmute`。在 ontrack 那一刻就抛「首帧到达」，
+     * UI 会**提前撤掉 loading 然后露出黑屏**——正是这个事件要避免的那件事。
+     *
+     * 已经 unmute 的（比如轨道复用）就立刻回调，不必等一个永远不会再来的事件。
+     */
+    private waitForVideo;
+    /**
+     * syncRemoteTracks 把挂载登记与状态机的远端轨道表对账：**认领新的，摘掉没了的**。
+     *
+     * # 为什么摘除这一半不能少
+     *
+     * 原先这里只认领不摘除，`ViewRegistry.removeTrack` 整个是死代码。于是对方关掉摄像头
+     * （`room.track_unpublished`）或直接离房之后，那条已经不存在的轨道**仍然挂在该 uid 的
+     * `MediaStream` 上、仍然绑在 `<video>.srcObject` 上**：自画 UI 的宿主看到的是一帧
+     * 冻住的画面而不是清空（uikit 只是拿 `visibility:hidden` 盖住了它）；同一个人反复
+     * 开关摄像头还会让他的流里越堆越多条废轨道，直到整轮房间结束才随 `clear()` 释放。
+     *
+     * # 两条边界
+     *
+     * - **orphans 不参与对账**：`ontrack` 先到、`track_published` 后到是常态，那时轨道
+     *   还不在 remoteTracks 里——按对账扫的话会把刚到的轨道当场摘掉，正好打断认领机制。
+     *   只扫**已认领**的。
+     * - **本端预览不归房间管**：它用 `:local:` 前缀登记，永远不在 remoteTracks 里，
+     *   扫到就跳过。不跳的话拨出中的自拍小窗会被第一次 dispatch 摘掉。
+     */
+    syncRemoteTracks(remoteTracks: Readonly<Record<string, RemoteTrackOwner>>): void;
+    /**
+     * awaitFirstVideoFrame 等 uid **开摄像头之后的新画面真的上屏**，到了回调一次（带他此刻的视频轨）。
+     *
+     * 与 `addRemoteTrack` 的首帧判据是两件事：那条按轨道只抛一次，管的是「轨道开始出数据」；
+     * 这条每开一次摄像头等一次，管的是「元素上换成新画面了」。为什么要等见 `FirstFrameGate`。
+     */
+    awaitFirstVideoFrame(uid: string, onFrame: (trackId: string) => void): void;
+    /** attachView 把某个 uid 的远端画面挂到元素上；传 null 卸载。 */
+    attachView(uid: string, el: ViewElement | null): void;
+    /** attachLocalView 把本端某条轨道挂到元素上做预览；传 null 卸载。 */
+    attachLocalView(cid: string, el: ViewElement | null): void;
+    /**
+     * refreshLocalViews 让本端预览的挂载跟上适配器里的轨道。
+     *
+     * 本端轨道会在 cid 不变的情况下**换人**：通话中关了摄像头再打开，是重新采集一条、
+     * `replaceTrack` 换上去的；进房前关掉摄像头，轨道干脆就没了。`attachLocalView` 只在挂载时取一次轨道，
+     * 界面的 effect 又只看 cid——不在这里换掉的话，元素上挂着的还是那条停掉的轨道，自己看到的是定格 / 黑屏。
+     */
+    refreshLocalViews(): void;
+    private clear;
+    private videoTrackOf;
+}
+//# sourceMappingURL=mediaBridge.d.ts.map

package/dist/media/mediaBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaBridge.d.ts","sourceRoot":"","sources":["../../src/media/mediaBridge.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,yBAAyB;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwB;IACpD,OAAO,CAAC,MAAM,CAAmC;gBAErC,OAAO,EAAE,YAAY;IAIjC,+BAA+B;IAC/B,IAAI,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAKtC;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAMb,0BAA0B;IAC1B,KAAK,IAAI,IAAI;IAMb;;;;;;;OAOG;IACH,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,gBAAgB,EACvB,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GACtC,IAAI;IAOP;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IAkBpB;;;;;;;;;;;;;;;;;;OAkBG;IACH,gBAAgB,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,GAAG,IAAI;IAahF;;;;;OAKG;IACH,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAI3E,+CAA+C;IAC/C,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI;IAKrD,iDAAiD;IACjD,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI;IAW1D;;;;;;OAMG;IACH,iBAAiB,IAAI,IAAI;IAWzB,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,YAAY;CAGrB"}

package/dist/media/mediaBridge.js

@@ -0,0 +1,186 @@
+import { FirstFrameGate } from './firstFrameGate.js';
+import { ViewRegistry } from './viewRegistry.js';
+/**
+ * MediaBridge 把媒体适配器与 uid↔元素的挂载登记捆在一起。
+ *
+ * # 为什么捆在一起
+ *
+ * 这三样东西的生命周期是同一个：**一轮房间**。通话结束、离房、房间被关掉时，
+ * PeerConnection 要重建、挂载登记要清空、「首帧抛过没有」也要忘掉。
+ * 散在门面里的话，总有一处会在某条结束路径上被漏掉——而漏掉的表现
+ * 是下一通电话带着上一通的轨道去协商，服务端只会记一句
+ * 「收到未登记的上行 Track」然后丢掉，界面上则是黑屏。
+ */
+export class MediaBridge {
+    adapter;
+    views = new ViewRegistry();
+    /** 已经抛过「首帧」的轨道，避免重复抛。 */
+    seenVideo = new Set();
+    /** 开摄像头之后等新画面上屏的那些人（见 awaitFirstVideoFrame）。 */
+    firstFrames = new FirstFrameGate();
+    events = null;
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    /** open 建两条 PeerConnection。 */
+    open(events) {
+        this.events = events;
+        this.adapter.open(events);
+    }
+    /**
+     * reset 把这一轮的媒体全部归零，并重建 PeerConnection。
+     *
+     * PC 是**跟着房间走**的：服务端每次进房都新建一对，客户端这边不重建的话，
+     * 上一轮的 transceiver 还挂在上面，下一轮的 offer 会多出几条服务端不认识的 m-line。
+     */
+    reset() {
+        this.clear();
+        this.adapter.close();
+        if (this.events !== null)
+            this.adapter.open(this.events);
+    }
+    /** close 彻底关掉（logout）。 */
+    close() {
+        this.clear();
+        this.adapter.close();
+        this.events = null;
+    }
+    /**
+     * addRemoteTrack 收下一条下行轨道。
+     *
+     * uid 允许为空——`ontrack` 与 `room.track_published` 谁先到都可能，
+     * 归属后到时由 claim 补上。
+     *
+     * `onFirstVideo` 在这条视频轨**真的开始出数据**时回调一次，见 waitForVideo。
+     */
+    addRemoteTrack(trackId, track, uid, onFirstVideo) {
+        this.views.addTrack(trackId, track, uid);
+        if (track.kind !== 'video' || this.seenVideo.has(trackId))
+            return;
+        this.seenVideo.add(trackId);
+        this.waitForVideo(trackId, track, onFirstVideo);
+    }
+    /**
+     * waitForVideo 等这条视频轨真的开始出数据。
+     *
+     * **`ontrack` 触发 ≠ 有画面**：远端轨道刚协商完时 `muted === true`，
+     * 要等第一个 RTP 包到达才 `unmute`。在 ontrack 那一刻就抛「首帧到达」，
+     * UI 会**提前撤掉 loading 然后露出黑屏**——正是这个事件要避免的那件事。
+     *
+     * 已经 unmute 的（比如轨道复用）就立刻回调，不必等一个永远不会再来的事件。
+     */
+    waitForVideo(trackId, track, onFirstVideo) {
+        if (track.muted === false) {
+            onFirstVideo(trackId);
+            return;
+        }
+        // 测试里的假轨道可能没有事件接口；没有就退回「协商完即视为到达」，
+        // 总比一条都不抛强。
+        if (typeof track.addEventListener !== 'function') {
+            onFirstVideo(trackId);
+            return;
+        }
+        track.addEventListener('unmute', () => onFirstVideo(trackId), { once: true });
+    }
+    /**
+     * syncRemoteTracks 把挂载登记与状态机的远端轨道表对账：**认领新的，摘掉没了的**。
+     *
+     * # 为什么摘除这一半不能少
+     *
+     * 原先这里只认领不摘除，`ViewRegistry.removeTrack` 整个是死代码。于是对方关掉摄像头
+     * （`room.track_unpublished`）或直接离房之后，那条已经不存在的轨道**仍然挂在该 uid 的
+     * `MediaStream` 上、仍然绑在 `<video>.srcObject` 上**：自画 UI 的宿主看到的是一帧
+     * 冻住的画面而不是清空（uikit 只是拿 `visibility:hidden` 盖住了它）；同一个人反复
+     * 开关摄像头还会让他的流里越堆越多条废轨道，直到整轮房间结束才随 `clear()` 释放。
+     *
+     * # 两条边界
+     *
+     * - **orphans 不参与对账**：`ontrack` 先到、`track_published` 后到是常态，那时轨道
+     *   还不在 remoteTracks 里——按对账扫的话会把刚到的轨道当场摘掉，正好打断认领机制。
+     *   只扫**已认领**的。
+     * - **本端预览不归房间管**：它用 `:local:` 前缀登记，永远不在 remoteTracks 里，
+     *   扫到就跳过。不跳的话拨出中的自拍小窗会被第一次 dispatch 摘掉。
+     */
+    syncRemoteTracks(remoteTracks) {
+        for (const [trackId, info] of Object.entries(remoteTracks)) {
+            this.views.claim(trackId, info.uid);
+        }
+        for (const [trackId, owner] of this.views.claimedTracks()) {
+            if (owner.startsWith(LOCAL_VIEW_PREFIX))
+                continue;
+            if (Object.hasOwn(remoteTracks, trackId))
+                continue;
+            this.views.removeTrack(trackId);
+            // 忘掉「首帧抛过了」：同一条 track_id 再回来时该重新抛一次 firstVideoFrame。
+            this.seenVideo.delete(trackId);
+        }
+    }
+    /**
+     * awaitFirstVideoFrame 等 uid **开摄像头之后的新画面真的上屏**，到了回调一次（带他此刻的视频轨）。
+     *
+     * 与 `addRemoteTrack` 的首帧判据是两件事：那条按轨道只抛一次，管的是「轨道开始出数据」；
+     * 这条每开一次摄像头等一次，管的是「元素上换成新画面了」。为什么要等见 `FirstFrameGate`。
+     */
+    awaitFirstVideoFrame(uid, onFrame) {
+        this.firstFrames.arm(uid, this.views.viewOf(uid), () => onFrame(this.videoTrackOf(uid)));
+    }
+    /** attachView 把某个 uid 的远端画面挂到元素上；传 null 卸载。 */
+    attachView(uid, el) {
+        this.views.attach(uid, el);
+        if (el !== null)
+            this.firstFrames.attached(uid, el);
+    }
+    /** attachLocalView 把本端某条轨道挂到元素上做预览；传 null 卸载。 */
+    attachLocalView(cid, el) {
+        const key = localViewKey(cid);
+        if (el === null) {
+            this.views.attach(key, null);
+            return;
+        }
+        const track = this.adapter.localTrack(cid);
+        if (track !== undefined)
+            this.views.addTrack(track.id, track, key);
+        this.views.attach(key, el);
+    }
+    /**
+     * refreshLocalViews 让本端预览的挂载跟上适配器里的轨道。
+     *
+     * 本端轨道会在 cid 不变的情况下**换人**：通话中关了摄像头再打开，是重新采集一条、
+     * `replaceTrack` 换上去的；进房前关掉摄像头，轨道干脆就没了。`attachLocalView` 只在挂载时取一次轨道，
+     * 界面的 effect 又只看 cid——不在这里换掉的话，元素上挂着的还是那条停掉的轨道，自己看到的是定格 / 黑屏。
+     */
+    refreshLocalViews() {
+        for (const [trackId, key] of this.views.claimedTracks()) {
+            if (!key.startsWith(LOCAL_VIEW_PREFIX))
+                continue;
+            const current = this.adapter.localTrack(key.slice(LOCAL_VIEW_PREFIX.length));
+            if (current?.id === trackId)
+                continue;
+            // 先摘后挂：流空了会被删掉，再挂时是一条新 MediaStream，<video> 会重新加载。
+            this.views.removeTrack(trackId);
+            if (current !== undefined)
+                this.views.addTrack(current.id, current, key);
+        }
+    }
+    clear() {
+        this.views.clear();
+        this.seenVideo.clear();
+        this.firstFrames.clear();
+    }
+    videoTrackOf(uid) {
+        return this.views.streamFor(uid)?.getTracks().find((track) => track.kind === 'video')?.id ?? '';
+    }
+}
+/**
+ * LOCAL_VIEW_PREFIX 是本端预览的登记键前缀。
+ *
+ * 本端与远端共用一张登记表（挂载/卸载逻辑完全一样），所以只需要一个前缀区分开。
+ * 前缀里带冒号：uid 是宿主给的业务 id，冒号开头的 uid 本来就不该出现在业务里。
+ * `syncRemoteTracks` 的对账要靠它把本端预览摘出去。
+ */
+const LOCAL_VIEW_PREFIX = ':local:';
+/** localViewKey 给本端预览一个不会与 uid 撞车的登记键。 */
+function localViewKey(cid) {
+    return `${LOCAL_VIEW_PREFIX}${cid}`;
+}
+//# sourceMappingURL=mediaBridge.js.map

package/dist/media/mediaBridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaBridge.js","sourceRoot":"","sources":["../../src/media/mediaBridge.ts"],"names":[],"mappings":"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"}

package/dist/media/mediaPlane.d.ts

@@ -0,0 +1,58 @@
+import type { EngineBus } from '../engineBus.js';
+import type { Connection } from '../signaling/connection.js';
+import type { PcRole } from '../signaling/enums.js';
+import type { FrameSender } from '../signaling/frameSender.js';
+import type { MachineInput } from '../state/types.js';
+import type { MediaAdapterEvents } from './mediaAdapter.js';
+import type { MediaBridge } from './mediaBridge.js';
+/**
+ * 门面与媒体面之间的**接线**：候选进出、远端轨道落地、PC 状态转成内部事件。
+ *
+ * 从 `engine.ts` 拆出来的理由与 `roomMachine` / `roomRecv` 那一刀相同（CONVENTIONS §2）：
+ * 门面负责「路由输入、填 SDP、派发事件」，这一组只负责「把媒体适配器接上总线」，
+ * 本来就是两组关注点。
+ *
+ * **写成自由函数 + 显式依赖，而不是让它认识 `CallEngine`**：
+ * 下面这个接口就是这条接线用到的全部东西，多一样都要先写进来——
+ * 反向依赖门面的话，「门面自己不做决策」这条约束用肉眼就再也看不出来了。
+ */
+export interface MediaPlaneDeps {
+    readonly bridge: MediaBridge;
+    readonly bus: EngineBus;
+    readonly sender: FrameSender;
+    /** 当前连接；没登录时为 null。取成函数是因为它会随重连换对象。 */
+    connection: () => Connection | null;
+    /** 某条远端轨道属于谁；不知道时返回空串。 */
+    uidOf: (trackId: string) => string;
+    dispatch: (input: MachineInput) => Promise<void>;
+}
+/** mediaEvents 组装交给 MediaAdapter 的那组回调。 */
+export declare function mediaEvents(deps: MediaPlaneDeps): MediaAdapterEvents;
+/**
+ * addRemoteCandidate 把服务端来的候选交给媒体层。
+ *
+ * **这条路径一开始整条漏了**：候选只往上发、不往下收，于是下行连接能不能建立
+ * 全看运气——服务端的 SDP 里**碰巧**已经带上了主机候选就通，
+ * 没带上（进房即订阅时协商得早，服务端还没收集完）就永远停在 `new`，
+ * 界面上是「格子在、画面黑」，而且不报任何错。
+ *
+ * `candidate` 为空串表示收集结束，协议要求容忍（§3.3）。
+ */
+/**
+ * 会话恢复之后重新协商上行（协议 §1.4）。
+ *
+ * 服务端那侧主动重发 `room.offer{pc:"sub"}`，`pub` 这条的 offerer 是本端，只能自己重发。
+ *
+ * **触发点必须是「恢复之后」，不能只有 [onPcState] 里「PC 判 failed 的那一刻」那一条**：
+ * 网一断信令也跟着断，房间立刻变成 `reconnecting`，而 PC 要等约 30 秒才判 `failed`——
+ * 那时 `restart_pub_ice` 会被状态机以 `invalid_state` 拒掉，且它**不进 BUFFERABLE_OPS**，
+ * 于是永远丢失。iOS 真机 2026-09-07 抓到过实证（`动作被状态机本地拒绝
+ * op=restart_pub_ice room_state=reconnecting`），三端同一条路。
+ *
+ * **不查 PC 当前状态、无条件重启**：换了连接就等于换了网络路径，旧候选多半已废；
+ * 服务端那侧也是无条件重启 `sub`，两边对称。多一次协商比漏一次自愈便宜得多。
+ * 房间不在 joined 时状态机自会拒掉，不必在这里判。
+ */
+export declare function renegotiateAfterResume(deps: MediaPlaneDeps): Promise<void>;
+export declare function addRemoteCandidate(deps: MediaPlaneDeps, addTo: (pc: PcRole, init: RTCIceCandidateInit) => Promise<void>, data: Readonly<Record<string, unknown>>): Promise<void>;
+//# sourceMappingURL=mediaPlane.d.ts.map

package/dist/media/mediaPlane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaPlane.d.ts","sourceRoot":"","sources":["../../src/media/mediaPlane.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,uCAAuC;IACvC,UAAU,EAAE,MAAM,UAAU,GAAG,IAAI,CAAC;IACpC,0BAA0B;IAC1B,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AAgBD,2CAA2C;AAC3C,wBAAgB,WAAW,CAAC,IAAI,EAAE,cAAc,GAAG,kBAAkB,CAOpE;AAED;;;;;;;;;GASG;AACH;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhF;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,EAC/D,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/media/mediaPlane.js

@@ -0,0 +1,119 @@
+import { ErrorCode, RtcError } from '../errors.js';
+import { logger } from '../logger.js';
+import { parseCandidate } from '../signaling/candidate.js';
+/** 连续这么多次 ICE restart 之后仍判 failed，就认为救不回来了（协议 §7.2）。 */
+const PUB_ICE_GIVE_UP = 3;
+/** mediaEvents 组装交给 MediaAdapter 的那组回调。 */
+export function mediaEvents(deps) {
+    const pubIce = { restarts: 0, gaveUp: false };
+    return {
+        onLocalCandidate: (pc, candidate) => sendCandidate(deps, pc, candidate),
+        onRemoteTrack: (trackId, track) => onRemoteTrack(deps, trackId, track),
+        onConnectionStateChange: (pc, state) => onPcState(deps, pc, state, pubIce),
+    };
+}
+/**
+ * addRemoteCandidate 把服务端来的候选交给媒体层。
+ *
+ * **这条路径一开始整条漏了**：候选只往上发、不往下收，于是下行连接能不能建立
+ * 全看运气——服务端的 SDP 里**碰巧**已经带上了主机候选就通，
+ * 没带上（进房即订阅时协商得早，服务端还没收集完）就永远停在 `new`，
+ * 界面上是「格子在、画面黑」，而且不报任何错。
+ *
+ * `candidate` 为空串表示收集结束，协议要求容忍（§3.3）。
+ */
+/**
+ * 会话恢复之后重新协商上行（协议 §1.4）。
+ *
+ * 服务端那侧主动重发 `room.offer{pc:"sub"}`，`pub` 这条的 offerer 是本端，只能自己重发。
+ *
+ * **触发点必须是「恢复之后」，不能只有 [onPcState] 里「PC 判 failed 的那一刻」那一条**：
+ * 网一断信令也跟着断，房间立刻变成 `reconnecting`，而 PC 要等约 30 秒才判 `failed`——
+ * 那时 `restart_pub_ice` 会被状态机以 `invalid_state` 拒掉，且它**不进 BUFFERABLE_OPS**，
+ * 于是永远丢失。iOS 真机 2026-09-07 抓到过实证（`动作被状态机本地拒绝
+ * op=restart_pub_ice room_state=reconnecting`），三端同一条路。
+ *
+ * **不查 PC 当前状态、无条件重启**：换了连接就等于换了网络路径，旧候选多半已废；
+ * 服务端那侧也是无条件重启 `sub`，两边对称。多一次协商比漏一次自愈便宜得多。
+ * 房间不在 joined 时状态机自会拒掉，不必在这里判。
+ */
+export async function renegotiateAfterResume(deps) {
+    deps.bridge.adapter.restartPubICE();
+    await deps.dispatch({ kind: 'act', op: 'restart_pub_ice' });
+}
+export async function addRemoteCandidate(deps, addTo, data) {
+    const parsed = parseCandidate(data);
+    if (parsed === null)
+        return; // 空候选 = 收集结束，忽略（§3.3）
+    try {
+        await addTo(parsed.pc, parsed.init);
+    }
+    catch (err) {
+        // 乱序候选是常态（协议 §3.3 要求容忍）：转成 error 事件，不中断事件流。
+        deps.bus.emitError(err);
+    }
+}
+function sendCandidate(deps, pc, candidate) {
+    const connection = deps.connection();
+    if (connection === null)
+        return;
+    void deps.sender
+        .sendCandidate(connection, pc, candidate)
+        .catch((err) => deps.bus.emitError(err));
+}
+function onRemoteTrack(deps, trackId, track) {
+    // uid 可能还不知道（ontrack 与 track_published 谁先到都可能）——
+    // 那就先收着，bridge.claim 会在状态机补上归属之后认领。
+    const uid = deps.uidOf(trackId);
+    // firstVideoFrame 没有对应的信令帧——它是本地事件，UI 用来撤 loading。
+    // **等轨道真的出数据才抛**（见 MediaBridge.waitForVideo）：ontrack 那一刻
+    // 还没有任何一帧，提前抛等于让 UI 撤了 loading 去露黑屏。
+    deps.bridge.addRemoteTrack(trackId, track, uid, (id) => {
+        // uid 这时可能已经被 track_published 补上了，重新取一次比缓存的准。
+        const owner = deps.uidOf(id) || uid;
+        deps.bus.emit('firstVideoFrame', { uid: owner, trackId: id });
+    });
+    deps.bus.emit('remoteTrack', { trackId, track });
+}
+function onPcState(deps, pc, state, pubIce) {
+    logger.debug('PC 状态', { pc, state });
+    if (pc === 'sub' && state === 'connected') {
+        void deps.dispatch({ kind: 'internal', name: 'media_ready' });
+    }
+    if (pc === 'pub' && state === 'connected') {
+        // 救回来了，下一轮重新计数。
+        pubIce.restarts = 0;
+        pubIce.gaveUp = false;
+    }
+    /*
+      **ICE 失败不是终点，是该重连的信号。**
+  
+      `pub` 那条的 offerer 是本端，只能自己救；`sub` 那条由服务端救（协议 §3.3）。
+      不救的后果：网抖一下（切网、休眠、标签页被节流久了）人就**永久掉出这通通话**，
+      对端的格子从此是一块黑，而界面上一切正常、谁也不挂断。
+      真机联调时抓到过两条 PC 从某一刻起五分钟一轮地失败，再没回到 connected。
+      重启失败还会再进 failed，于是天然形成一个重试节奏。
+  
+      **但重试节奏不能没有尽头**（协议 §7.2）：一律自愈、永不上报的话，宿主从头到尾
+      收不到任何信号——上面那段描述的现象会一直挂着，而界面上什么都不会变。
+      连续 PUB_ICE_GIVE_UP 次重启后仍判 failed，抛一次 2006；之后继续重试但不再重复抛。
+    */
+    if (pc === 'pub' && state === 'failed') {
+        logger.info('上行通路失败，重启 ICE', {});
+        pubIce.restarts += 1;
+        if (pubIce.restarts >= PUB_ICE_GIVE_UP && !pubIce.gaveUp) {
+            pubIce.gaveUp = true;
+            logger.warn('上行通路连续重启仍失败，上报宿主', { restarts: pubIce.restarts });
+            deps.bus.emitError(new RtcError(ErrorCode.mediaNegotiationFailed));
+        }
+        deps.bridge.adapter.restartPubICE();
+        void deps.dispatch({ kind: 'act', op: 'restart_pub_ice' });
+        return;
+    }
+    if (pc === 'sub' && state === 'failed') {
+        // sub 那条我们救不了（offerer 是服务端，§3.3），只能立即报给宿主。
+        logger.warn('下行通路失败，等服务端重启', {});
+        deps.bus.emitError(new RtcError(ErrorCode.mediaNegotiationFailed));
+    }
+}
+//# sourceMappingURL=mediaPlane.js.map

package/dist/media/mediaPlane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaPlane.js","sourceRoot":"","sources":["../../src/media/mediaPlane.ts"],"names":[],"mappings":"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"}

package/dist/media/videoProfile.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 视频画质档位。
+ *
+ * # 为什么是「宿主给」而不是「服务端下发」
+ *
+ * 与换 token 是同一条边界（协议 §1.5）：**策略归宿主，engine 不自己去要。**
+ * 画质该多高取决于宿主的业务（付费档位、当前网络、机型），engine 不认识那些东西。
+ * 宿主要「后台可控」就把这个值放进自己的配置接口里下发给 App——
+ * 那正是宿主后台该管的事，也不需要动 RTC 协议。
+ *
+ * （真要让 **RTC 服务端**统一下发，那是往 `sys.hello.ok.limits` 加字段，
+ * 等于改五个仓 + 一致性向量，是单独一刀，不该混在别的改动里。）
+ *
+ * # 档位怎么定
+ *
+ * 分辨率按主流三档；码率取的是 simulcast 最高层的目标值（协议 §3.5 的表）。
+ * **`maxBitrateBps` 必须和服务端 `internal/sfu/bwe.go` 的 `bitrateHigh` 对得上**：
+ * 那边拿它做带宽预算，两边不一致的话，带宽估计会按一个错的数字去决定降不降层。
+ */
+export interface VideoProfile {
+    readonly name: string;
+    readonly width: number;
+    readonly height: number;
+    readonly frameRate: number;
+    /** 最高层的目标码率。simulcast 的 m / l 层按 1/3、1/10 折算。 */
+    readonly maxBitrateBps: number;
+}
+/** 三个预设档位。默认 720p——1080p 在九宫格里没有意义，只是白烧上行带宽。 */
+export declare const VideoProfiles: {
+    readonly p360: {
+        readonly name: "360p";
+        readonly width: 640;
+        readonly height: 360;
+        readonly frameRate: 24;
+        readonly maxBitrateBps: 500000;
+    };
+    readonly p720: {
+        readonly name: "720p";
+        readonly width: 1280;
+        readonly height: 720;
+        readonly frameRate: 30;
+        readonly maxBitrateBps: 1500000;
+    };
+    readonly p1080: {
+        readonly name: "1080p";
+        readonly width: 1920;
+        readonly height: 1080;
+        readonly frameRate: 30;
+        readonly maxBitrateBps: 3000000;
+    };
+};
+/** 缺省档位。 */
+export declare const defaultVideoProfile: VideoProfile;
+/**
+ * simulcastEncodings 把档位翻成三层 simulcast 的编码参数。
+ *
+ * # rid 必须恰好是 l / m / h
+ *
+ * 服务端直接拿 RID 当层名（`internal/sfu/layer.go` 的 `ridToLayer`），**不做映射表**。
+ * 拼错一个字母就会被当成「空 RID = 单层发布」，于是三层全被认成 h，
+ * 层选择彻底失效而且不报错。
+ *
+ * # 顺序是 l → m → h
+ *
+ * `scaleResolutionDownBy` 是相对采集分辨率的**缩小倍数**，所以 h 恒为 1。
+ * 按由低到高排是各家 SFU 的通行做法（LiveKit 的 q/h/f 同序），
+ * Chrome 在这个顺序下最稳。
+ *
+ * 码率折算沿用 VideoProfile 里写的那套：m 取 1/3、l 取 1/10。
+ */
+export declare function simulcastEncodings(profile: VideoProfile): RTCRtpEncodingParameters[];
+/**
+ * videoConstraints 把档位翻成 `getUserMedia` 的约束。
+ *
+ * 用 `ideal` 不用 `exact`：**`exact` 在不支持该分辨率的摄像头上直接抛
+ * `OverconstrainedError`，通话就打不出去了**。画质是偏好，不是硬条件。
+ */
+export declare function videoConstraints(profile: VideoProfile): MediaTrackConstraints;
+//# sourceMappingURL=videoProfile.d.ts.map

package/dist/media/videoProfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"videoProfile.d.ts","sourceRoot":"","sources":["../../src/media/videoProfile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,gDAAgD;AAChD,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;CAIuB,CAAC;AAElD,YAAY;AACZ,eAAO,MAAM,mBAAmB,EAAE,YAAiC,CAAC;AAEpE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,wBAAwB,EAAE,CAMpF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,qBAAqB,CAM7E"}

package/dist/media/videoProfile.js

@@ -0,0 +1,46 @@
+/** 三个预设档位。默认 720p——1080p 在九宫格里没有意义，只是白烧上行带宽。 */
+export const VideoProfiles = {
+    p360: { name: '360p', width: 640, height: 360, frameRate: 24, maxBitrateBps: 500_000 },
+    p720: { name: '720p', width: 1280, height: 720, frameRate: 30, maxBitrateBps: 1_500_000 },
+    p1080: { name: '1080p', width: 1920, height: 1080, frameRate: 30, maxBitrateBps: 3_000_000 },
+};
+/** 缺省档位。 */
+export const defaultVideoProfile = VideoProfiles.p720;
+/**
+ * simulcastEncodings 把档位翻成三层 simulcast 的编码参数。
+ *
+ * # rid 必须恰好是 l / m / h
+ *
+ * 服务端直接拿 RID 当层名（`internal/sfu/layer.go` 的 `ridToLayer`），**不做映射表**。
+ * 拼错一个字母就会被当成「空 RID = 单层发布」，于是三层全被认成 h，
+ * 层选择彻底失效而且不报错。
+ *
+ * # 顺序是 l → m → h
+ *
+ * `scaleResolutionDownBy` 是相对采集分辨率的**缩小倍数**，所以 h 恒为 1。
+ * 按由低到高排是各家 SFU 的通行做法（LiveKit 的 q/h/f 同序），
+ * Chrome 在这个顺序下最稳。
+ *
+ * 码率折算沿用 VideoProfile 里写的那套：m 取 1/3、l 取 1/10。
+ */
+export function simulcastEncodings(profile) {
+    return [
+        { rid: 'l', scaleResolutionDownBy: 4, maxBitrate: Math.round(profile.maxBitrateBps / 10) },
+        { rid: 'm', scaleResolutionDownBy: 2, maxBitrate: Math.round(profile.maxBitrateBps / 3) },
+        { rid: 'h', scaleResolutionDownBy: 1, maxBitrate: profile.maxBitrateBps },
+    ];
+}
+/**
+ * videoConstraints 把档位翻成 `getUserMedia` 的约束。
+ *
+ * 用 `ideal` 不用 `exact`：**`exact` 在不支持该分辨率的摄像头上直接抛
+ * `OverconstrainedError`，通话就打不出去了**。画质是偏好，不是硬条件。
+ */
+export function videoConstraints(profile) {
+    return {
+        width: { ideal: profile.width },
+        height: { ideal: profile.height },
+        frameRate: { ideal: profile.frameRate },
+    };
+}
+//# sourceMappingURL=videoProfile.js.map

package/dist/media/videoProfile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"videoProfile.js","sourceRoot":"","sources":["../../src/media/videoProfile.ts"],"names":[],"mappings":"AA4BA,gDAAgD;AAChD,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,EAAE,aAAa,EAAE,OAAO,EAAE;IACtF,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,EAAE,aAAa,EAAE,SAAS,EAAE;IACzF,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,aAAa,EAAE,SAAS,EAAE;CAC7C,CAAC;AAElD,YAAY;AACZ,MAAM,CAAC,MAAM,mBAAmB,GAAiB,aAAa,CAAC,IAAI,CAAC;AAEpE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAqB;IACtD,OAAO;QACL,EAAE,GAAG,EAAE,GAAG,EAAE,qBAAqB,EAAE,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,GAAG,EAAE,CAAC,EAAE;QAC1F,EAAE,GAAG,EAAE,GAAG,EAAE,qBAAqB,EAAE,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,GAAG,CAAC,CAAC,EAAE;QACzF,EAAE,GAAG,EAAE,GAAG,EAAE,qBAAqB,EAAE,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,aAAa,EAAE;KAC1E,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAqB;IACpD,OAAO;QACL,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE;QAC/B,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE;QACjC,SAAS,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,EAAE;KACxC,CAAC;AACJ,CAAC"}

package/dist/media/videoProfile.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=videoProfile.test.d.ts.map

package/dist/media/videoProfile.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"videoProfile.test.d.ts","sourceRoot":"","sources":["../../src/media/videoProfile.test.ts"],"names":[],"mappings":""}