@steve02081504/fount-p2p 0.0.29 → 0.0.31

package/discovery/bt/index.mjs

@@ -297,9 +297,7 @@ export function createBluetoothDiscoveryProvider() {
 				cleanup()
 				reject(new Error('p2p: bt signal peripheral timeout'))
 			}, 8_000)
-			/**
-			 * @returns {void}
-			 */
+			/** 清理信号超时计时器并移除 discover 监听器 */
 			function cleanup() {
 				clearTimeout(deadline)
 				noble.removeListener('discover', onDiscover)

package/discovery/nostr.mjs

@@ -243,6 +243,7 @@ function connectRelay(relayUrl, timeoutMs = NOSTR_CONNECT_TIMEOUT_MS, signal) {
 			reject(error)
 		}
 		/**
+		 * 收到 abort 信号时失败
 		 * @returns {void}
 		 */
 		const onAbort = () => fail(new Error('nostr: aborted'))
@@ -294,6 +295,7 @@ function publishEventOnRelay(ws, relayUrl, event, signal, isCurrent) {
 			else resolve(ok)
 		}
 		/**
+		 * 收到 abort 信号时以失败结束
 		 * @returns {void}
 		 */
 		const onAbort = () => finish(false, new Error('nostr: aborted'))
@@ -492,9 +494,7 @@ function attachSharedRelaySocket(relayUrl, session, ws) {
 function scheduleSharedRelayConnect(relayUrl, session, delayMs = 0) {
 	if (!isLiveSharedSession(relayUrl, session) || session.connecting || session.ws) return
 	clearSharedRelayReconnect(session)
-	/**
-	 * @returns {void}
-	 */
+	/** 启动/恢复共享会话连接 */
 	const start = () => {
 		session.reconnectTimer = null
 		if (!isLiveSharedSession(relayUrl, session) || session.connecting || session.ws) return

package/files/chunk/store.mjs

@@ -5,6 +5,7 @@ import { dirname, join } from 'node:path'
 import { pipeline } from 'node:stream/promises'
 
 import { isHex64 } from '../../core/hexIds.mjs'
+import { trackFileStream } from '../../node/handles.mjs'
 import { getNodeDir } from '../../node/instance.mjs'
 
 /**
@@ -50,7 +51,7 @@ export async function getChunk(hash) {
  * @returns {import('node:fs').ReadStream} 可读流
  */
 export function createChunkReadStream(hash) {
-	return fs.createReadStream(chunkStorePath(hash))
+	return trackFileStream(fs.createReadStream(chunkStorePath(hash)))
 }
 
 /**
@@ -72,5 +73,5 @@ export async function putChunk(hash, data) {
 export async function putChunkFromStream(hash, readable) {
 	const filePath = chunkStorePath(hash)
 	await fsp.mkdir(dirname(filePath), { recursive: true })
-	await pipeline(readable, fs.createWriteStream(filePath))
+	await pipeline(readable, trackFileStream(fs.createWriteStream(filePath)))
 }

package/index.mjs

@@ -11,6 +11,7 @@ import {
 import { registerLinkProvider } from './link/providers/index.mjs'
 import { ensureNodeDefaults, getNodeHash } from './node/identity.mjs'
 import {
+	closeNode,
 	getNodeDir,
 	initNode,
 	isNodeInitialized,
@@ -58,6 +59,7 @@ import {
 export {
 	attachReputationSyncWire,
 	attachNodeScopeDefaultFeatures,
+	closeNode,
 	configureLinkRegistry,
 	createGroupLinkSet,
 	createScopedLinkRoom,

package/infra/priority.mjs

@@ -28,9 +28,7 @@ export function getInfraPriority() {
 	return { ...priorityConfig }
 }
 
-/**
- * @returns {void}
- */
+/** 将优先级配置应用到 link registry */
 export function applyPriorityToRegistry() {
 	const registry = getLinkRegistry()
 	if (!priorityConfig.useLocalReputation) {

package/infra/service.mjs

@@ -42,9 +42,7 @@ export function consumeOverlayRateToken(buckets, sender, now, limits) {
 	return true
 }
 
-/**
- * @returns {void}
- */
+/** 安装 overlay 速率门 */
 function installOverlayRateLimit() {
 	const limits = {
 		perMin: Math.max(1, Number(infraTunables.overlayRatePerMin) || 120),
@@ -56,9 +54,7 @@ function installOverlayRateLimit() {
 	})
 }
 
-/**
- * @returns {void}
- */
+/** 移除 overlay 速率门并清空桶 */
 function removeOverlayRateLimit() {
 	clearOverlayRateGate()
 	overlayRateBuckets.clear()

package/link/providers/ble_gatt.mjs

@@ -80,9 +80,7 @@ async function dialBleGatt(options) {
 			cleanup()
 			reject(new Error('p2p: ble_gatt peripheral scan timeout'))
 		}, 8_000)
-		/**
-		 * @returns {void}
-		 */
+		/** 清理扫描超时计时器与监听器并停止 BLE 扫描 */
 		function cleanup() {
 			clearTimeout(deadline)
 			noble.removeListener('discover', onDiscover)
@@ -249,9 +247,7 @@ export function createBleGattLinkProvider() {
 					sessionInbound = handler
 					return () => { sessionInbound = null }
 				},
-				/**
-				 * @returns {void}
-				 */
+				/** 关闭入站 transport */
 				closeTransport() {
 					activeInbound = null
 					sessionInbound = null

package/link/providers/lan_tcp.mjs

@@ -35,9 +35,7 @@ function connectTcp(host, port, timeoutMs = LAN_TCP_CONNECT_TIMEOUT_MS) {
 			conn.off('connect', onConnect)
 			reject(error)
 		}
-		/**
-		 * @returns {void}
-		 */
+		/** TCP 连接成功并返回 socket */
 		function onConnect() {
 			clearTimeout(timer)
 			conn.off('error', onError)
@@ -111,9 +109,7 @@ function attachLengthPrefix(socket, onPayload) {
 			header.writeUInt32BE(body.length)
 			socket.write(Buffer.concat([header, body]))
 		},
-		/**
-		 * @returns {void}
-		 */
+		/** 仅移除 data 监听器 */
 		destroy() {
 			socket.off('data', onData)
 		},
@@ -149,9 +145,7 @@ function createTcpPipe(options) {
 		sendFrame(_action, frame) {
 			codec.write(frame)
 		},
-		/**
-		 * @returns {void}
-		 */
+		/** 关闭 transport 与 socket */
 		closeTransport() {
 			codec.destroy()
 			socket.destroy()

package/link/providers/webrtc.mjs

@@ -68,8 +68,7 @@ export async function createWebRtcLink(options) {
 	const handshakeTimeoutMs = Number(options.handshakeTimeoutMs) || ms('10s')
 	const channelOpenTimeoutMs = Math.max(handshakeTimeoutMs, ms('30s'))
 	const rtc = options.rtc ?? await loadNodeRtcPolyfill()
-	// 纯 JS 后端只做 trickle（SDP 不含 candidate）；强制开启 trickle。
-	const trickleIceOff = !rtc.forcesTrickleIce && getSignalingRuntimeConfig().trickleIceOff === true
+	const trickleIceOff = getSignalingRuntimeConfig().trickleIceOff === true
 	const peerConnection = new rtc.RTCPeerConnection(options.iceServers?.length ? { iceServers: options.iceServers } : undefined)
 	const remoteSignalQueue = []
 	const seenRemoteSignals = createLruMap(1024)
@@ -183,6 +182,10 @@ export async function createWebRtcLink(options) {
 		const deadline = Date.now() + handshakeTimeoutMs
 		while (peerConnection.iceGatheringState !== 'complete' && Date.now() < deadline)
 			await new Promise(resolve => setTimeout(resolve, 50))
+		if (peerConnection.iceGatheringState !== 'complete') {
+			await pipe.close('ice-gathering-timeout')
+			throw new Error(`p2p: ice gathering incomplete after ${handshakeTimeoutMs}ms`)
+		}
 	}
 
 	/**

package/link/rtc/ice_local_hostname.mjs

@@ -50,18 +50,12 @@ export function filterIceLocalHostnameCandidate(candidate, RTCIceCandidateCtor,
 export function wrapRtcPeerConnectionForIceLocalHostname(BaseRTC, RTCIceCandidate, policy = 'drop') {
 	if (policy === 'none') return BaseRTC
 
-	const baseRoutesIce = !!BaseRTC.prototype.prepareIceCandidateEvent
-
 	return class IceLocalHostnameFilteredRTCPeerConnection extends BaseRTC {
 		/** @type {((event: RTCPeerConnectionIceEvent) => void) | null} */
 		#userIceHandler = null
-		/** @type {Set<(event: unknown) => void>} */
-		#iceListeners = new Set()
-		/** 去重：同一次 native 派发可能既走 attribute 又走 listener */
-		#lastIceEvent = null
 
 		/**
-		 * drop：不派发；rewrite：仅派发替换 candidate 后的事件。
+		 * drop：不派发；rewrite：构造仅携带替换 candidate 的派生事件。
 		 * @param {RTCPeerConnectionIceEvent | { candidate?: unknown }} event 原始 ICE 事件
 		 * @returns {RTCPeerConnectionIceEvent | { candidate?: unknown } | null} 规范化后的事件；drop 时为 null
 		 */
@@ -69,7 +63,10 @@ export function wrapRtcPeerConnectionForIceLocalHostname(BaseRTC, RTCIceCandidat
 			if (!event?.candidate) return event
 			const filtered = filterIceLocalHostnameCandidate(event.candidate, RTCIceCandidate, policy)
 			if (!filtered) return null
-			return filtered === event.candidate ? event : { candidate: filtered }
+			if (filtered === event.candidate) return event
+			const rewritten = new event.constructor('icecandidate')
+			rewritten.candidate = filtered
+			return rewritten
 		}
 
 		/**
@@ -77,9 +74,6 @@ export function wrapRtcPeerConnectionForIceLocalHostname(BaseRTC, RTCIceCandidat
 		 */
 		constructor(config) {
 			super(config)
-			if (baseRoutesIce) return
-
-			// native EventTarget：在派发前规范化，自管 listener，不依赖 stopImmediatePropagation。
 			Object.defineProperty(this, 'onicecandidate', {
 				configurable: true,
 				enumerable: true,
@@ -93,48 +87,22 @@ export function wrapRtcPeerConnectionForIceLocalHostname(BaseRTC, RTCIceCandidat
 				 */
 				set: handler => { this.#userIceHandler = handler },
 			})
-			super.addEventListener('icecandidate', event => this.#deliverIce(event))
 		}
 
 		/**
-		 * @param {RTCPeerConnectionIceEvent | { candidate?: unknown }} event 原始 ICE 事件
-		 * @returns {void}
+		 * 先完成 candidate 转换，再走标准 EventTarget 派发（保留 once/AbortSignal/capture 语义）。
+		 * addEventListener / removeEventListener 交由基类，故 once / AbortSignal / capture 均保留。
+		 * drop：不派发；pass-through：派发原事件；rewrite：派发替换 candidate 后的派生事件。
+		 * @param {Event} event 待派发事件
+		 * @returns {boolean} 事件是否未被取消
 		 */
-		#deliverIce = event => {
-			if (this.#lastIceEvent === event) return
-			this.#lastIceEvent = event
+		dispatchEvent(event) {
+			if (event?.type !== 'icecandidate') return super.dispatchEvent(event)
 			const normalized = this.prepareIceCandidateEvent(event)
-			if (normalized == null) return
+			if (normalized == null) return true
 			this.#userIceHandler?.(normalized)
-			for (const listener of this.#iceListeners) listener(normalized)
-		}
-
-		/**
-		 * @param {string} type 事件名
-		 * @param {(event: unknown) => void} listener 回调
-		 * @param {boolean | AddEventListenerOptions} [options] 监听选项
-		 * @returns {void}
-		 */
-		addEventListener(type, listener, options) {
-			if (!baseRoutesIce && type === 'icecandidate') {
-				this.#iceListeners.add(listener)
-				return
-			}
-			return super.addEventListener(type, listener, options)
-		}
-
-		/**
-		 * @param {string} type 事件名
-		 * @param {(event: unknown) => void} listener 回调
-		 * @param {boolean | EventListenerOptions} [options] 监听选项
-		 * @returns {void}
-		 */
-		removeEventListener(type, listener, options) {
-			if (!baseRoutesIce && type === 'icecandidate') {
-				this.#iceListeners.delete(listener)
-				return
-			}
-			return super.removeEventListener(type, listener, options)
+			if (normalized === event) return super.dispatchEvent(event)
+			return super.dispatchEvent(normalized)
 		}
 	}
 }

package/link/rtc/polyfill.mjs

@@ -4,7 +4,6 @@ import { getRtcPolyfillCacheEpoch, getSignalingRuntimeConfig } from '../../node/
 import { nodeDebug } from '../../node/log.mjs'
 
 import { wrapRtcPeerConnectionForIceLocalHostname } from './ice_local_hostname.mjs'
-import { bridgePeerConnection } from './w3c_bridge.mjs'
 
 /** @type {boolean} */
 let exitCleanupHooked = false
@@ -20,11 +19,9 @@ let cachedDefaultPolyfillEpoch = -1
  *   RTCPeerConnection: typeof RTCPeerConnection,
  *   RTCIceCandidate: typeof RTCIceCandidate,
  *   backend: string,
- *   forcesTrickleIce: boolean,
  * }} LoadedRtcPolyfill
  * @typedef {{
  *   id: string,
- *   forcesTrickleIce?: boolean,
  *   load: () => Promise<{ RTCPeerConnection: typeof RTCPeerConnection, RTCIceCandidate: typeof RTCIceCandidate }>,
  * }} RtcBackend
  */
@@ -57,12 +54,9 @@ async function ensureNodeDatachannelExitCleanup() {
  * @returns {Promise<{ RTCPeerConnection: typeof RTCPeerConnection, RTCIceCandidate: typeof RTCIceCandidate }>} node-datachannel 构造器
  */
 async function loadNodeDatachannelBackend() {
-	const mod = await import('node-datachannel/polyfill')
+	const module = await import('node-datachannel/polyfill')
 	await ensureNodeDatachannelExitCleanup()
-	return {
-		RTCPeerConnection: mod.RTCPeerConnection,
-		RTCIceCandidate: mod.RTCIceCandidate,
-	}
+	return module
 }
 
 /**
@@ -70,17 +64,12 @@ async function loadNodeDatachannelBackend() {
  * @returns {Promise<{ RTCPeerConnection: typeof RTCPeerConnection, RTCIceCandidate: typeof RTCIceCandidate }>} node-rtc-connection 构造器
  */
 async function loadNodeRtcConnectionBackend() {
-	const module = await import('node-rtc-connection')
-	return {
-		RTCPeerConnection: /** @type {typeof RTCPeerConnection} */ bridgePeerConnection(module.RTCPeerConnection),
-		RTCIceCandidate: module.RTCIceCandidate,
-	}
+	return import('node-rtc-connection')
 }
 
 /** @type {RtcBackend} */
 const PURE_JS_BACKEND = {
 	id: 'node-rtc-connection',
-	forcesTrickleIce: true,
 	load: loadNodeRtcConnectionBackend,
 }
 
@@ -119,7 +108,6 @@ async function loadNodeRtcPolyfillUncached(options) {
 				),
 				RTCIceCandidate: mod.RTCIceCandidate,
 				backend: backend.id,
-				forcesTrickleIce: backend.forcesTrickleIce === true,
 			}
 		}
 		catch (error) {

package/node/handles.mjs

@@ -0,0 +1,49 @@
+/**
+ * 节点生命周期内打开的文件流注册表。
+ *
+ * 文件流（chunk 读流 / 写流）在 Windows 上若未 destroy 会占用文件句柄，
+ * 导致节点目录删除失败。这里集中跟踪，`closeNode()` 通过
+ * `closeAllFileStreams()` 一次性释放全部仍打开的流。
+ */
+
+/** @type {Set<import('node:stream').Readable | import('node:stream').Writable>} */
+const streams = new Set()
+
+/**
+ * 跟踪一个文件流：销毁/关闭/出错时自动从注册表移除。
+ * @template {import('node:stream').Readable | import('node:stream').Writable} T
+ * @param {T} stream 文件流
+ * @returns {T} 原流
+ */
+export function trackFileStream(stream) {
+	streams.add(stream)
+	/** @returns {void} */
+	const forget = () => streams.delete(stream)
+	stream.once('close', forget)
+	stream.once('error', forget)
+	return stream
+}
+
+/**
+ * 关闭并销毁所有仍在打开的文件流（测试 teardown / 节点关闭）。
+ * @returns {Promise<number>} 被销毁的流数量
+ */
+export async function closeAllFileStreams() {
+	const targeted = [...streams]
+	const pending = []
+	for (const stream of targeted) {
+		if (!stream.closed)
+			pending.push(new Promise(resolve => stream.once('close', resolve)))
+		stream.destroy()
+	}
+	await Promise.all(pending)
+	for (const stream of targeted) streams.delete(stream)
+	return targeted.length
+}
+
+/**
+ * @returns {boolean} 是否仍有未释放的文件流（测试断言用）
+ */
+export function hasOpenFileStreams() {
+	return streams.size > 0
+}

package/node/instance.mjs

@@ -1,6 +1,7 @@
 import path from 'node:path'
 
 import { createFsEntityStore } from './entity_store.mjs'
+import { closeAllFileStreams } from './handles.mjs'
 import { defaultSignalingRuntimeConfig, resolveSignalingRuntimeConfig } from './signaling_config.mjs'
 
 /** @typedef {{ warn?: (...args: unknown[]) => void, error?: (...args: unknown[]) => void, info?: (...args: unknown[]) => void, log?: (...args: unknown[]) => void }} NodeLogger */
@@ -37,7 +38,7 @@ export function getRtcPolyfillCacheEpoch() {
  * @returns {NodeRuntime} 初始化后的运行时
  */
 export function initNode(options) {
-	if (runtime) throw new Error('p2p: initNode already called — use setNodeLogger / setSignalingRuntimeConfig or resetNodeForTests')
+	if (runtime) throw new Error('p2p: initNode already called — use setNodeLogger / setSignalingRuntimeConfig or closeNode')
 	if (options?.logger !== undefined || options?.signaling !== undefined)
 		throw new Error('p2p: initNode only accepts nodeDir/entityStore — use setNodeLogger / setSignalingRuntimeConfig')
 	const nodeDir = path.resolve(options.nodeDir)
@@ -138,11 +139,13 @@ export function onNodeChange(listener) {
 }
 
 /**
- * 测试专用：重置节点运行时。
- * @returns {void}
+ * 关闭节点：释放全部文件句柄（chunk 读/写流等）并清空运行时与监听器。
+ * 之后可用 initNode 重新引导。
+ * @returns {Promise<void>}
  */
-export function resetNodeForTests() {
+export async function closeNode() {
 	runtime = null
 	changeListeners.clear()
 	rtcPolyfillCacheEpoch++
+	await closeAllFileStreams()
 }

package/node/reputation_sync.mjs

@@ -78,9 +78,7 @@ function normalizeHashList(list) {
 		.filter(id => isHex64(id)))]
 }
 
-/**
- * @returns {void}
- */
+/** 将当前 sync 配置写盘 */
 function persistSyncConfig() {
 	writeNodeJsonSync(SYNC_DATA_NAME, loadSyncConfig())
 }
@@ -304,9 +302,7 @@ export async function pullReputationFromNode(nodeHash) {
 	return await resultPromise
 }
 
-/**
- * @returns {void}
- */
+/** 重置 sync 运行时（测试用） */
 export function resetReputationSyncForTests() {
 	syncConfig = null
 	detachReputationSyncWire()

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.29",
+	"version": "0.0.31",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",

package/transport/group_link_set.mjs

@@ -99,9 +99,7 @@ export function createGroupLinkSet(options) {
 		scheduleDial()
 	}
 
-	/**
-	 * @returns {void}
-	 */
+	/** 按成员选择目标并拨号 */
 	function selectAndDial() {
 		if (!autoconnectEnabled || !active) return
 		const targets = dialAll
@@ -119,9 +117,7 @@ export function createGroupLinkSet(options) {
 				void registry.ensureLinkToNode(nodeHash).catch(() => null)
 	}
 
-	/**
-	 * @returns {void}
-	 */
+	/** 延迟调度一次拨号 */
 	function scheduleDial() {
 		if (!autoconnectEnabled || !active || dialTimer) return
 		dialTimer = setTimeout(() => { dialTimer = null; selectAndDial() }, 200)

package/transport/link_registry.mjs

@@ -719,9 +719,7 @@ export function configureLinkRegistry(options = {}) {
 	pendingRegistryOptions = { ...pendingRegistryOptions, ...options }
 }
 
-/**
- * @returns {void}
- */
+/** 重置 link registry 运行时（测试用） */
 export function resetLinkRegistryForTests() {
 	defaultRegistry = null
 	pendingRegistryOptions = null

package/transport/offer_answer.mjs

@@ -48,9 +48,7 @@ export function createBufferedSignalSession(sendRemote) {
 			for (const handler of handlers)
 				handler(message)
 		},
-		/**
-		 * @returns {void}
-		 */
+		/** 清空积压消息 */
 		clear() {
 			backlog.length = 0
 			handlers.clear()

package/transport/runtime_bootstrap.mjs

@@ -111,9 +111,7 @@ export function createRuntimeBootstrap(deps) {
 			?? mergeSignalingRelayUrls(getNodeTransportSettings().relayUrls)
 	}
 
-	/**
-	 * @returns {void}
-	 */
+	/** 注册默认 discovery provider（lan/nostr） */
 	function registerDiscoveryDefaults() {
 		const providerIds = new Set(listDiscoveryProviders().map(provider => provider.id))
 		if (!providerIds.has('lan'))
@@ -124,9 +122,7 @@ export function createRuntimeBootstrap(deps) {
 			registerNostrProvider()
 	}
 
-	/**
-	 * @returns {void}
-	 */
+	/** 注册/替换 nostr discovery provider */
 	function registerNostrProvider() {
 		unregisterDiscoveryProvider('nostr')
 		registerDiscoveryProvider(createNostrDiscoveryProvider({

package/utils/async_mutex.mjs

@@ -42,9 +42,7 @@ export async function withAsyncMutex(key, criticalSection) {
 	const lockKey = key
 	const state = mutexState(lockKey)
 	return new Promise((resolve, reject) => {
-		/**
-		 * @returns {void}
-		 */
+		/** 执行临界区并最终释放锁 */
 		const run = () => {
 			Promise.resolve()
 				.then(criticalSection)

package/utils/ttl_map.mjs

@@ -56,9 +56,7 @@ export function createTtlMap(ttlMs, maxSize = 4096) {
 			}
 			return entry.value
 		},
-		/**
-		 * @returns {void}
-		 */
+		/** 清空全部条目 */
 		clear() {
 			map.clear()
 		},

package/link/rtc/w3c_bridge.mjs

@@ -1,152 +0,0 @@
-/**
- * 把 EventEmitter 风格的 RTC（如 node-rtc-connection）桥成 W3C 属性 handler。
- * 其余链路只认 onicecandidate / onmessage / onbufferedamountlow 等。
- */
-
-/** @type {WeakSet<object>} */
-const bridgedChannels = new WeakSet()
-
-/**
- * @param {object} target EventEmitter 目标
- * @param {string} property W3C 属性名（如 onmessage）
- * @param {string} eventName EventEmitter 事件名
- * @param {(payload: unknown) => unknown} [adapt] 事件载荷适配
- * @returns {void}
- */
-function defineEmitterHandler(target, property, eventName, adapt = payload => payload) {
-	let handler = null
-	target.on(eventName, payload => handler?.(adapt(payload)))
-	Object.defineProperty(target, property, {
-		configurable: true,
-		enumerable: true,
-		/**
-		 * @returns {((payload: unknown) => void) | null} 当前 handler
-		 */
-		get: () => handler,
-		/**
-		 * @param {((payload: unknown) => void) | null} value 新 handler
-		 * @returns {void}
-		 */
-		set: value => { handler = value },
-	})
-}
-
-/**
- * @param {RTCDataChannel} channel 原始 data channel
- * @returns {RTCDataChannel} 已挂 W3C handler 的通道
- */
-export function bridgeDataChannel(channel) {
-	if (bridgedChannels.has(channel) || !channel.on) return channel
-	bridgedChannels.add(channel)
-	defineEmitterHandler(channel, 'onmessage', 'message')
-	defineEmitterHandler(channel, 'onopen', 'open')
-	defineEmitterHandler(channel, 'onclose', 'close')
-	defineEmitterHandler(channel, 'onbufferedamountlow', 'bufferedamountlow')
-	return channel
-}
-
-/**
- * @param {typeof RTCPeerConnection} BaseRTC EventEmitter 风格 RTCPeerConnection
- * @returns {typeof RTCPeerConnection} W3C handler 版
- */
-export function bridgePeerConnection(BaseRTC) {
-	return class W3cRtcPeerConnection extends BaseRTC {
-		/** @type {((event: RTCPeerConnectionIceEvent) => void) | null} */
-		#iceHandler = null
-		/** @type {((event: { channel: RTCDataChannel }) => void) | null} */
-		#dataChannelHandler = null
-		/** @type {(() => void) | null} */
-		#connectionStateHandler = null
-		/** @type {Map<string, Set<(event: unknown) => void>>} */
-		#listeners = new Map()
-
-		/**
-		 * @param {RTCConfiguration} [config] RTC 配置
-		 */
-		constructor(config) {
-			super(config)
-			super.on('icecandidate', event => {
-				const normalized = this.prepareIceCandidateEvent(event)
-				if (normalized == null) return
-				this.#iceHandler?.(normalized)
-				this.#emit('icecandidate', normalized)
-			})
-			super.on('datachannel', event => {
-				const adapted = { channel: bridgeDataChannel(event.channel) }
-				this.#dataChannelHandler?.(adapted)
-				this.#emit('datachannel', adapted)
-			})
-			super.on('connectionstatechange', () => {
-				this.#connectionStateHandler?.()
-				this.#emit('connectionstatechange', undefined)
-			})
-		}
-
-		/**
-		 * ICE 事件规范化钩子；子类可覆盖（drop 返回 null，rewrite 返回替换后的事件）。
-		 * @param {RTCPeerConnectionIceEvent | { candidate?: unknown }} event 原始 ICE 事件
-		 * @returns {RTCPeerConnectionIceEvent | { candidate?: unknown } | null} 规范化后的事件
-		 */
-		prepareIceCandidateEvent(event) {
-			return event
-		}
-
-		/**
-		 * @param {string} type 事件名
-		 * @param {unknown} event 事件载荷（icecandidate 须已规范化）
-		 * @returns {void}
-		 */
-		#emit(type, event) {
-			const listeners = this.#listeners.get(type)
-			if (!listeners) return
-			for (const listener of listeners) listener(event)
-		}
-
-		/**
-		 * @param {string} type 事件名
-		 * @param {(event: unknown) => void} listener 回调
-		 * @returns {void}
-		 */
-		addEventListener(type, listener) {
-			let listeners = this.#listeners.get(type)
-			if (!listeners) {
-				listeners = new Set()
-				this.#listeners.set(type, listeners)
-			}
-			listeners.add(listener)
-		}
-
-		/**
-		 * @param {string} type 事件名
-		 * @param {(event: unknown) => void} listener 回调
-		 * @returns {void}
-		 */
-		removeEventListener(type, listener) {
-			this.#listeners.get(type)?.delete(listener)
-		}
-
-		/** @returns {((event: RTCPeerConnectionIceEvent) => void) | null} ICE candidate handler */
-		get onicecandidate() { return this.#iceHandler }
-		/** @param {((event: RTCPeerConnectionIceEvent) => void) | null} handler ICE candidate handler */
-		set onicecandidate(handler) { this.#iceHandler = handler }
-
-		/** @returns {((event: { channel: RTCDataChannel }) => void) | null} data channel handler */
-		get ondatachannel() { return this.#dataChannelHandler }
-		/** @param {((event: { channel: RTCDataChannel }) => void) | null} handler data channel handler */
-		set ondatachannel(handler) { this.#dataChannelHandler = handler }
-
-		/** @returns {(() => void) | null} connection state handler */
-		get onconnectionstatechange() { return this.#connectionStateHandler }
-		/** @param {(() => void) | null} handler connection state handler */
-		set onconnectionstatechange(handler) { this.#connectionStateHandler = handler }
-
-		/**
-		 * @param {string} label data channel 标签
-		 * @param {RTCDataChannelInit} [init] 创建选项
-		 * @returns {RTCDataChannel} 已桥接 W3C handler 的通道
-		 */
-		createDataChannel(label, init) {
-			return bridgeDataChannel(super.createDataChannel(label, init))
-		}
-	}
-}