@xmaxai/web-sdk 1.0.3 → 1.0.4

package/dist/{chunk-YMLRUDAO.js → chunk-FMAQXPTE.js}

@@ -3,10 +3,10 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
 // src/Foundation/Runtime/XmaxEnvironment.ts
-var XmaxEnvironment = /* @__PURE__ */ ((XmaxEnvironment2) => {
-  XmaxEnvironment2["china"] = "china";
-  XmaxEnvironment2["global"] = "global";
-  return XmaxEnvironment2;
+var XmaxEnvironment = /* @__PURE__ */ ((XmaxEnvironment3) => {
+  XmaxEnvironment3["china"] = "china";
+  XmaxEnvironment3["global"] = "global";
+  return XmaxEnvironment3;
 })(XmaxEnvironment || {});
 var API_BASE_URLS = {
   ["china" /* china */]: "https://cloud.xmax.22duck.cn/open/api/v1",
@@ -198,7 +198,7 @@ var XmaxError = class _XmaxError extends Error {
 };
 
 // src/Foundation/Runtime/RuntimeInfo.ts
-var XMAX_SDK_VERSION = "1.0.3";
+var XMAX_SDK_VERSION = "1.0.4";
 var _RuntimeInfo = class _RuntimeInfo {
   /**
    * 序列化为接口传输使用的 snake_case 字段。
@@ -521,22 +521,22 @@ var RealtimeVideoFormat = class _RealtimeVideoFormat {
    * @throws 尺寸、帧率或码率配置无效时抛出错误。
    */
   validate() {
-    if (this.width <= 0 || this.height <= 0 || this.fps <= 0 || this.width % 2 !== 0 || this.height % 2 !== 0) {
+    if (this.width <= 0 || this.height <= 0 || !Number.isFinite(this.fps) || this.fps <= 0 || this.width % 2 !== 0 || this.height % 2 !== 0) {
       throw new XmaxError(
         "INVALID_CONFIGURATION" /* invalidConfiguration */,
         "Realtime video width and height must be positive even numbers, and fps must be greater than zero"
       );
     }
-    if (this.minimumBitrate !== void 0 && this.minimumBitrate < 0) {
+    if (this.minimumBitrate !== void 0 && (!Number.isFinite(this.minimumBitrate) || this.minimumBitrate < 0)) {
       throw new XmaxError(
         "INVALID_CONFIGURATION" /* invalidConfiguration */,
-        "Minimum bitrate must not be negative"
+        "Minimum bitrate must be finite and not negative"
       );
     }
-    if (this.maximumBitrate !== void 0 && this.maximumBitrate <= 0) {
+    if (this.maximumBitrate !== void 0 && (!Number.isFinite(this.maximumBitrate) || this.maximumBitrate <= 0)) {
       throw new XmaxError(
         "INVALID_CONFIGURATION" /* invalidConfiguration */,
-        "Maximum bitrate must be greater than zero"
+        "Maximum bitrate must be finite and greater than zero"
       );
     }
     if (this.minimumBitrate !== void 0 && this.maximumBitrate !== void 0 && this.minimumBitrate > this.maximumBitrate) {
@@ -564,26 +564,39 @@ var RealtimeVideoFormat = class _RealtimeVideoFormat {
 // src/Service/Realtime/RealtimeModel.ts
 var RealtimeModel = /* @__PURE__ */ ((RealtimeModel2) => {
   RealtimeModel2["x2_0"] = "x2.0";
-  RealtimeModel2["x2_0_pro"] = "x2.0-pro";
   RealtimeModel2["x2_0_trtc"] = "x2.0-trtc";
+  RealtimeModel2["x2_0_agora"] = "x2.0-agora";
+  RealtimeModel2["x2_1_preview"] = "x2.1-preview";
   return RealtimeModel2;
 })(RealtimeModel || {});
+var MODEL_BASE_URLS = {
+  ["x2.0-agora" /* x2_0_agora */]: "https://dev.xmaxai.com/open/api/v1",
+  ["x2.1-preview" /* x2_1_preview */]: "https://dev.xmaxai.com/open/api/v1"
+};
 var RESOLUTION_BUCKETS = {
-  ["x2.0" /* x2_0 */]: [],
-  ["x2.0-pro" /* x2_0_pro */]: [
+  ["x2.1-preview" /* x2_1_preview */]: [
+    { width: 1024, height: 1920 },
+    { width: 1920, height: 1024 }
+  ],
+  ["x2.0-agora" /* x2_0_agora */]: [
     { width: 1024, height: 1920 },
     { width: 1920, height: 1024 }
   ],
+  ["x2.0" /* x2_0 */]: [],
   ["x2.0-trtc" /* x2_0_trtc */]: [
     { width: 1024, height: 1920 },
     { width: 1920, height: 1024 }
   ]
 };
 var MAXIMUM_INPUT_PIXELS = {
+  ["x2.1-preview" /* x2_1_preview */]: 21e5,
+  ["x2.0-agora" /* x2_0_agora */]: 21e5,
   ["x2.0" /* x2_0 */]: 128e4,
-  ["x2.0-pro" /* x2_0_pro */]: 21e5,
   ["x2.0-trtc" /* x2_0_trtc */]: 21e5
 };
+function modelBaseURL(model) {
+  return MODEL_BASE_URLS[model];
+}
 function resolutionBuckets(model) {
   return RESOLUTION_BUCKETS[model];
 }
@@ -1071,7 +1084,718 @@ async function watchMediaPermissionPrompt(includeMicrophone) {
   return { decided, dispose };
 }
 
-// src/Foundation/RTC/RtcEngineManager.ts
+// src/Foundation/RTC/Agora/AgoraRtcStatistics.ts
+var AgoraRtcStatistics = class _AgoraRtcStatistics {
+  /**
+   * 采集已发布的视频和已订阅的结果流统计，性能日志不控制回调采集。
+   */
+  static collect(client, listener) {
+    const rtc = client.getRTCStats();
+    const local = client.getLocalVideoStats();
+    const valid = _AgoraRtcStatistics.valid;
+    const loss = _AgoraRtcStatistics.loss;
+    const localVideo = client.localTracks.some((track) => track.trackMediaType === "video") ? {
+      width: valid(local.sendResolutionWidth, 1),
+      height: valid(local.sendResolutionHeight, 1),
+      frameRate: valid(local.sendFrameRate),
+      bitrateKbps: valid(local.sendBitrate / 1e3),
+      uplinkLossPercent: loss(local.currentPacketLossRate)
+    } : void 0;
+    const remote = Object.entries(client.getRemoteVideoStats()).map(([userID, stats]) => ({
+      userID,
+      width: valid(stats.receiveResolutionWidth, 1),
+      height: valid(stats.receiveResolutionHeight, 1),
+      frameRate: valid(stats.receiveFrameRate),
+      bitrateKbps: valid(stats.receiveBitrate / 1e3),
+      rttMs: valid(rtc.RTT),
+      uplinkLossPercent: localVideo?.uplinkLossPercent,
+      downlinkLossPercent: loss(stats.currentPacketLossRate),
+      endToEndDelayMs: valid(stats.end2EndDelay)
+    }));
+    listener?.onLocalVideoStatistics?.(localVideo && Object.freeze(localVideo));
+    listener?.onRemoteVideoStatistics?.(Object.freeze(remote.map((item) => Object.freeze(item))));
+    XmaxLogger.rtc.info(() => `Agora \u8FD0\u884C\u7EDF\u8BA1 (Agora RTC Statistics)
+${JSON.stringify({
+      rttMs: valid(rtc.RTT),
+      sentBytes: valid(rtc.SendBytes),
+      receivedBytes: valid(rtc.RecvBytes),
+      localVideo,
+      remoteVideo: remote,
+      localAudio: client.getLocalAudioStats(),
+      remoteAudio: client.getRemoteAudioStats()
+    }, null, 2)}`, 2 /* performance */);
+  }
+  /**
+   * 网络质量等级范围与公共枚举一致；不将整体 RTT 冒充上下行独立 RTT。
+   */
+  static network(stats, listener) {
+    const quality = (value) => Number.isInteger(value) && value >= 0 && value <= 6 ? value : void 0;
+    const result = Object.freeze({ uplinkQuality: quality(stats.uplinkNetworkQuality), downlinkQuality: quality(stats.downlinkNetworkQuality) });
+    listener?.onNetworkStatistics?.(result);
+    XmaxLogger.rtc.info(() => `Agora \u7F51\u7EDC\u8D28\u91CF (Agora Network Quality)
+${JSON.stringify(result, null, 2)}`, 2 /* performance */);
+  }
+  /**
+   * 过滤缺失、非有限或不合理的统计值。
+   */
+  static valid(value, minimum = 0) {
+    return typeof value === "number" && Number.isFinite(value) && value >= minimum ? value : void 0;
+  }
+  /**
+   * 声网丢包率为 0–1 比例，转换为公共百分比。
+   */
+  static loss(value) {
+    return Number.isFinite(value) && value >= 0 && value <= 1 ? value * 100 : void 0;
+  }
+};
+
+// src/Foundation/RTC/RtcVideoOrientation.ts
+function shouldTransposeRtcVideoSize(environment) {
+  const userAgent = environment?.userAgent ?? (typeof navigator === "undefined" ? "" : navigator.userAgent);
+  const maxTouchPoints = environment?.maxTouchPoints ?? (typeof navigator === "undefined" ? 0 : navigator.maxTouchPoints ?? 0);
+  const mobile = /Android|webOS|iPhone|iPad|iPod|Mobile/i.test(userAgent) || /Macintosh/i.test(userAgent) && maxTouchPoints > 1;
+  if (!mobile) {
+    return false;
+  }
+  const orientationType = environment?.orientationType ?? (typeof window === "undefined" ? void 0 : window.screen?.orientation?.type);
+  if (orientationType !== void 0) {
+    return orientationType.includes("portrait");
+  }
+  const degrees = environment?.orientationDegrees ?? (typeof window === "undefined" ? void 0 : window.orientation);
+  return degrees === 0 || degrees === 180;
+}
+function rtcOrientedVideoSize(size, environment) {
+  return shouldTransposeRtcVideoSize(environment) ? { width: size.height, height: size.width } : size;
+}
+
+// src/Foundation/RTC/Agora/AgoraRtcManager.ts
+var _AgoraRtcManager = class _AgoraRtcManager {
+  /**
+   * 保存服务环境与加载器，不触发浏览器依赖或设备权限请求。
+   */
+  constructor(options) {
+    /**
+     * 配置与 RTC 资源
+     */
+    __publicField(this, "environment");
+    __publicField(this, "loadSDK");
+    __publicField(this, "sdk");
+    __publicField(this, "client");
+    __publicField(this, "initialization");
+    __publicField(this, "lifecycle", 0);
+    __publicField(this, "camera");
+    __publicField(this, "microphone");
+    __publicField(this, "connection");
+    __publicField(this, "roomVersion", 0);
+    /**
+     * 凭据恢复与发布意图；RTC 自动断开可能清空 localTracks，因此单独保留发布意图。
+     */
+    __publicField(this, "tokenExpired", false);
+    __publicField(this, "rejoinOperation");
+    __publicField(this, "rejoinTask");
+    __publicField(this, "cancelRejoin");
+    __publicField(this, "videoPublishRequested", false);
+    __publicField(this, "audioPublishRequested", false);
+    /**
+     * 事件、统计与音频播放状态
+     */
+    __publicField(this, "listener");
+    __publicField(this, "statisticsTimer");
+    __publicField(this, "audioVolumes", /* @__PURE__ */ new Map());
+    __publicField(this, "requestedAudio", /* @__PURE__ */ new Set());
+    /**
+     * DataStream 串行发送与限速状态；等待中的消息通过房间版本取消。
+     */
+    __publicField(this, "sendTail", Promise.resolve());
+    __publicField(this, "sentPackets", []);
+    __publicField(this, "cancelSendDelay");
+    __publicField(this, "cancelActiveSend");
+    this.environment = options.environment;
+    this.loadSDK = options.loadSDK ?? (async () => (await import("agora-rtc-sdk-ng")).default);
+  }
+  /**
+   * 当前实例是否已创建声网 client。
+   */
+  get isInitialized() {
+    return this.client !== void 0;
+  }
+  /**
+   * 声网音频轨支持播放前设置音量；零音量额外停止播放以防浏览器差异。
+   */
+  get supportsRemoteAudioVolumeControl() {
+    return true;
+  }
+  /**
+   * 共享本实例的初始化任务，区域完全由接入方环境决定。
+   */
+  async initialize() {
+    if (this.client) return;
+    if (this.initialization) return this.initialization;
+    const version = this.lifecycle;
+    const operation = this.performInitialize(version);
+    this.initialization = operation;
+    try {
+      await operation;
+    } finally {
+      if (this.initialization === operation) this.initialization = void 0;
+    }
+  }
+  /**
+   * 加载模块、锁定区域并注册事件；迟到的初始化不能复活已销毁实例。
+   */
+  async performInitialize(version) {
+    const sdk = await this.loadSDK();
+    if (version !== this.lifecycle) throw this.cancelled();
+    const region = _AgoraRtcManager.regions.get(sdk);
+    if (region && region.environment !== this.environment) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Concurrent Agora clients must use the same XmaxEnvironment");
+    }
+    sdk.setLogLevel(4);
+    if (!region) sdk.setArea([this.environment === "china" /* china */ ? "CHINA" : "GLOBAL"]);
+    const client = sdk.createClient({ mode: "rtc", codec: "h264" });
+    if (typeof client.sendStreamMessage !== "function") {
+      throw new XmaxError("RTC_ERROR" /* rtcError */, "Agora DataStream is unavailable in this SDK version");
+    }
+    _AgoraRtcManager.regions.set(sdk, { environment: this.environment, count: (region?.count ?? 0) + 1 });
+    this.sdk = sdk;
+    this.client = client;
+    this.registerEvents(client);
+  }
+  /**
+   * 先失效全部异步工作，再释放房间、采集、监听和区域引用。
+   */
+  async destroy() {
+    this.lifecycle++;
+    const client = this.client;
+    this.listener = void 0;
+    this.clearRoom();
+    this.client = void 0;
+    client?.removeAllListeners();
+    this.camera?.close();
+    this.microphone?.close();
+    this.camera = void 0;
+    this.microphone = void 0;
+    const sdk = this.sdk;
+    this.sdk = void 0;
+    try {
+      await client?.leave();
+    } catch {
+      XmaxLogger.rtc.warning(() => "Agora \u9000\u623F\u5931\u8D25\uFF0C\u5DF2\u91CA\u653E\u672C\u5730\u8D44\u6E90 (Agora Leave Failed)");
+    } finally {
+      const region = sdk && _AgoraRtcManager.regions.get(sdk);
+      if (sdk && region && --region.count === 0) _AgoraRtcManager.regions.delete(sdk);
+    }
+  }
+  /**
+   * 通过声网采集相机但不发布，返回原生轨道供公共渲染层使用。
+   */
+  async startCameraCapture(options) {
+    const client = this.requireClient();
+    if (this.camera) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera capture is already running");
+    try {
+      const captureSize = rtcOrientedVideoSize(options);
+      const camera = await this.sdk.createCameraVideoTrack({
+        facingMode: options.position === "front" /* front */ ? "user" : "environment",
+        encoderConfig: { width: captureSize.width, height: captureSize.height, frameRate: options.frameRate }
+      });
+      if (this.client !== client) {
+        camera.close();
+        throw this.cancelled();
+      }
+      this.camera = camera;
+      return camera.getMediaStreamTrack();
+    } catch (error) {
+      throw this.mapError(error, "CAMERA_PERMISSION_DENIED" /* cameraPermissionDenied */);
+    }
+  }
+  /**
+   * 切换声网相机设备并返回切换后的原生轨道。
+   */
+  async switchCameraCapture(to) {
+    const camera = this.requireCamera();
+    await this.run(() => camera.setDevice({ facingMode: to === "front" /* front */ ? "user" : "environment" }));
+    if (this.camera !== camera) throw this.cancelled();
+    return camera.getMediaStreamTrack();
+  }
+  /**
+   * 停止采集并释放摄像头。
+   */
+  async stopCameraCapture() {
+    const camera = this.camera;
+    this.camera = void 0;
+    camera?.close();
+  }
+  /**
+   * 应用公共编码配置，补偿移动端竖屏的宽高转置。
+   */
+  async configureVideoEncoding(config) {
+    const camera = this.requireCamera();
+    const encodingSize = rtcOrientedVideoSize(config);
+    await this.run(async () => {
+      await camera.setEncoderConfiguration({
+        width: encodingSize.width,
+        height: encodingSize.height,
+        frameRate: config.frameRate,
+        bitrateMin: config.minimumBitrate,
+        bitrateMax: config.maximumBitrate
+      });
+      await camera.setOptimizationMode(config.encoderPreference === "maintainFramerate" /* maintainFramerate */ ? "motion" : "detail");
+    });
+  }
+  /**
+   * 使用会话下发的字符串频道与 UID 入房；不采信后端区域覆盖。
+   */
+  async joinRoom(configuration) {
+    await this.rejoinTask?.catch(() => {
+    });
+    const client = this.requireClient();
+    if (configuration.provider !== "agora" || this.connection) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Agora credentials and an idle room are required");
+    }
+    const version = ++this.roomVersion;
+    await this.run(() => client.join(configuration.appID, configuration.roomID, configuration.roomToken, configuration.userID));
+    if (client !== this.client || version !== this.roomVersion) {
+      await client.leave();
+      throw this.cancelled();
+    }
+    this.connection = configuration;
+    for (const user of client.remoteUsers) {
+      if (user.hasVideo) this.listener?.onRemoteVideoPublished(String(user.uid), true);
+    }
+    this.statisticsTimer = setInterval(() => {
+      if (this.client !== client || !this.connection || this.tokenExpired || this.rejoinOperation) return;
+      try {
+        AgoraRtcStatistics.collect(client, this.listener);
+      } catch {
+        XmaxLogger.rtc.warning(() => "Agora \u7EDF\u8BA1\u91C7\u6837\u5931\u8D25 (Agora Statistics Failed)");
+      }
+    }, 2e3);
+  }
+  /**
+   * 退房前取消排队消息、统计与音频播放；本地相机预览保持运行。
+   */
+  async leaveRoom() {
+    this.clearRoom();
+    if (this.client) await this.run(() => this.client.leave());
+  }
+  /**
+   * 应用同一频道的新 Token；即将过期时续签，已经过期时重新进房并恢复媒体。
+   */
+  async updateCredentials(config, signal) {
+    if (signal?.aborted) throw this.cancelled();
+    const current = this.connection;
+    const client = this.requireClient();
+    if (!current || config.provider !== "agora" || config.appID !== current.appID || config.roomID !== current.roomID || config.userID !== current.userID) {
+      throw new XmaxError("SESSION_ERROR" /* sessionError */, "Agora session binding changed");
+    }
+    const version = this.roomVersion;
+    if (!this.tokenExpired) {
+      try {
+        await this.run(() => client.renewToken(config.roomToken));
+      } catch (error) {
+        this.ensureRoomCurrent(client, version);
+        if (!this.tokenExpired) throw error;
+      }
+    }
+    this.ensureRoomCurrent(client, version);
+    if (signal?.aborted) throw this.cancelled();
+    if (this.tokenExpired) await this.rejoinRoom(client, config, signal);
+    else this.connection = config;
+  }
+  /**
+   * 串行恢复同一 RTC 房间，不创建业务会话或重新发送生成开始指令。
+   */
+  async rejoinRoom(client, config, signal) {
+    if (this.rejoinOperation) return this.rejoinOperation;
+    const version = ++this.roomVersion;
+    const task = Promise.resolve().then(() => this.performRejoin(client, config, version));
+    this.rejoinTask = task;
+    void task.finally(() => {
+      if (this.rejoinTask === task) this.rejoinTask = void 0;
+    }).catch(() => {
+    });
+    let cancel;
+    const operation = new Promise((resolve, reject) => {
+      cancel = () => {
+        if (this.isRoomCurrent(client, version)) this.roomVersion++;
+        reject(this.cancelled());
+      };
+      this.cancelRejoin = cancel;
+      signal?.addEventListener("abort", cancel, { once: true });
+      task.then(resolve, reject);
+      if (signal?.aborted) cancel();
+    });
+    this.rejoinOperation = operation;
+    try {
+      await operation;
+    } finally {
+      signal?.removeEventListener("abort", cancel);
+      if (this.cancelRejoin === cancel) this.cancelRejoin = void 0;
+      if (this.rejoinOperation === operation) this.rejoinOperation = void 0;
+    }
+    this.ensureRoomCurrent(client, version);
+    for (const user of client.remoteUsers) {
+      if (user.hasVideo) this.listener?.onRemoteVideoPublished(String(user.uid), true);
+    }
+  }
+  /**
+   * 使用新 Token 重建 RTC 连接，复用采集轨道并恢复远端音频订阅。
+   */
+  async performRejoin(client, config, version) {
+    this.ensureRoomCurrent(client, version);
+    this.cancelSendDelay?.();
+    this.cancelActiveSend?.();
+    this.listener?.onRoomRejoining?.();
+    for (const user of client.remoteUsers) user.audioTrack?.stop();
+    await this.run(() => client.leave());
+    this.ensureRoomCurrent(client, version);
+    await this.run(() => client.join(config.appID, config.roomID, config.roomToken, config.userID));
+    if (!this.isRoomCurrent(client, version)) {
+      await this.run(() => client.leave());
+      throw this.cancelled();
+    }
+    if (this.videoPublishRequested && this.camera) {
+      await this.run(() => client.publish(this.camera));
+      this.ensureRoomCurrent(client, version);
+    }
+    if (this.audioPublishRequested && this.microphone) {
+      await this.run(() => client.publish(this.microphone));
+      this.ensureRoomCurrent(client, version);
+    }
+    for (const user of client.remoteUsers) {
+      if (!user.hasAudio || !this.requestedAudio.has(String(user.uid))) continue;
+      const track = await this.run(() => client.subscribe(user, "audio"));
+      if (!this.isRoomCurrent(client, version)) {
+        track.stop();
+        throw this.cancelled();
+      }
+      this.applyAudioVolume(user);
+    }
+    this.connection = config;
+    this.tokenExpired = false;
+    this.sentPackets = [];
+  }
+  /**
+   * 发布已采集的视频轨道。
+   */
+  async publishLocalVideo() {
+    const client = this.requireClient();
+    const camera = this.requireCamera();
+    this.videoPublishRequested = true;
+    await this.rejoinOperation;
+    if (client !== this.client || !this.videoPublishRequested) throw this.cancelled();
+    if (client.localTracks.includes(camera)) return;
+    await this.run(() => client.publish(camera));
+  }
+  /**
+   * 停止视频发布但保留采集与预览。
+   */
+  async unpublishLocalVideo() {
+    this.videoPublishRequested = false;
+    if (this.rejoinTask || this.tokenExpired) return;
+    if (this.client && this.camera) await this.run(() => this.client.unpublish(this.camera));
+  }
+  /**
+   * 首次发布时申请麦克风；取消后的迟到采集立即释放。
+   */
+  async publishLocalAudio() {
+    const client = this.requireClient();
+    this.audioPublishRequested = true;
+    await this.rejoinOperation;
+    const version = this.roomVersion;
+    if (client !== this.client || !this.audioPublishRequested) throw this.cancelled();
+    try {
+      if (!this.microphone) {
+        const track = await this.sdk.createMicrophoneAudioTrack();
+        if (client !== this.client || version !== this.roomVersion) {
+          track.close();
+          throw this.cancelled();
+        }
+        this.microphone = track;
+      }
+      if (!client.localTracks.includes(this.microphone)) await client.publish(this.microphone);
+    } catch (error) {
+      throw this.mapError(error, "MICROPHONE_PERMISSION_DENIED" /* microphonePermissionDenied */);
+    }
+  }
+  /**
+   * 停止音频发布，采集交给关闭流程释放。
+   */
+  async unpublishLocalAudio() {
+    this.audioPublishRequested = false;
+    if (this.rejoinTask || this.tokenExpired) return;
+    if (this.client && this.microphone) await this.run(() => this.client.unpublish(this.microphone));
+  }
+  /**
+   * 订阅远端主视频并返回原生轨道，不创建额外播放视图。
+   */
+  async subscribeRemoteVideo(userID, subscribe) {
+    if (!subscribe && this.rejoinTask) return;
+    await this.rejoinOperation;
+    const client = this.requireClient();
+    const user = client.remoteUsers.find((user2) => String(user2.uid) === userID);
+    if (!user && !subscribe) return;
+    if (!user) throw new XmaxError("RTC_ERROR" /* rtcError */, "Agora remote video user is unavailable");
+    if (!subscribe) {
+      await this.run(() => client.unsubscribe(user, "video"));
+      return;
+    }
+    const version = this.roomVersion;
+    const track = await this.run(() => client.subscribe(user, "video"));
+    if (client !== this.client || version !== this.roomVersion) throw this.cancelled();
+    return track.getMediaStreamTrack();
+  }
+  /**
+   * 保存音频订阅意图；音频稍后发布时自动订阅，播放前应用音量。
+   */
+  async subscribeRemoteAudio(userID, subscribe) {
+    const client = this.requireClient();
+    const user = client.remoteUsers.find((user2) => String(user2.uid) === userID);
+    if (!subscribe) {
+      this.requestedAudio.delete(userID);
+      user?.audioTrack?.stop();
+      if (user?.audioTrack && !this.rejoinTask) await this.run(() => client.unsubscribe(user, "audio"));
+      return;
+    }
+    this.requestedAudio.add(userID);
+    if (this.rejoinOperation) {
+      const version2 = this.roomVersion;
+      await this.rejoinOperation;
+      this.ensureRoomCurrent(client, version2);
+      if (this.requestedAudio.has(userID)) await this.subscribeRemoteAudio(userID, true);
+      return;
+    }
+    if (!user?.hasAudio) return;
+    const version = this.roomVersion;
+    const track = await this.run(() => client.subscribe(user, "audio"));
+    if (client !== this.client || version !== this.roomVersion || !this.requestedAudio.has(userID)) {
+      track.stop();
+      return;
+    }
+    this.applyAudioVolume(user);
+  }
+  /**
+   * 缓存音量，订阅前可调用；零音量不调用 play，防止初始短暂漏声。
+   */
+  setRemoteAudioVolume(volume, userID) {
+    this.audioVolumes.set(userID, Math.max(0, Math.min(100, Number.isFinite(volume) ? Math.round(volume) : 0)));
+    const user = this.client?.remoteUsers.find((user2) => String(user2.uid) === userID);
+    if (this.rejoinTask || this.tokenExpired) {
+      user?.audioTrack?.stop();
+      return;
+    }
+    if (user) this.applyAudioVolume(user);
+  }
+  /**
+   * 应用当前用户的播放状态，保留声网对浏览器自动播放限制的处理。
+   */
+  applyAudioVolume(user) {
+    const track = user.audioTrack;
+    if (!track) return;
+    const volume = this.audioVolumes.get(String(user.uid)) ?? 0;
+    track.setVolume(volume);
+    if (volume > 0 && this.requestedAudio.has(String(user.uid))) track.play();
+    else track.stop();
+  }
+  /**
+   * 按房间顺序发送消息，限制每秒包数与总字节；失败返回给原业务调用。
+   */
+  sendRoomMessage(message) {
+    const version = this.roomVersion;
+    const client = this.client;
+    const bytes = new TextEncoder().encode(message).byteLength;
+    const operation = this.sendTail.then(async () => {
+      await this.rejoinOperation;
+      if (!client || client !== this.client || !this.connection || version !== this.roomVersion || this.tokenExpired) throw this.cancelled();
+      if (bytes > 1e3) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Room message exceeds the 1000-byte limit");
+      await this.waitForSendBudget(bytes, version);
+      await this.rejoinOperation;
+      if (client !== this.client || version !== this.roomVersion || !this.connection || this.tokenExpired) throw this.cancelled();
+      this.sentPackets.push({ time: Date.now(), bytes });
+      await this.sendWithTimeout(client, message);
+    });
+    this.sendTail = operation.catch(() => {
+    });
+    return operation;
+  }
+  /**
+   * 发送超过五秒视为失败；退房立即取消等待，底层迟到结果不影响新房间。
+   */
+  async sendWithTimeout(client, message) {
+    await new Promise((resolve, reject) => {
+      const finish = (error) => {
+        clearTimeout(timer);
+        if (this.cancelActiveSend === cancel) this.cancelActiveSend = void 0;
+        if (error) reject(this.mapError(error));
+        else resolve();
+      };
+      const cancel = () => finish(this.cancelled());
+      const timer = setTimeout(() => finish(new XmaxError("TIMEOUT" /* timeout */, "Agora room message send timed out")), 5e3);
+      this.cancelActiveSend = cancel;
+      void this.run(() => client.sendStreamMessage(message, false)).then(() => finish(), finish);
+    });
+  }
+  /**
+   * 按滑动时间窗限速，退房立即唤醒等待并取消，不遗留计时器。
+   */
+  async waitForSendBudget(bytes, version) {
+    while (version === this.roomVersion) {
+      const now = Date.now();
+      this.sentPackets = this.sentPackets.filter((packet) => now - packet.time < 1e3);
+      if (this.sentPackets.length < 30 && this.sentPackets.reduce((sum, packet) => sum + packet.bytes, bytes) <= 6e3) return;
+      await new Promise((resolve) => {
+        const finish = () => {
+          clearTimeout(timer);
+          this.cancelSendDelay = void 0;
+          resolve();
+        };
+        const timer = setTimeout(finish, Math.max(1, this.sentPackets[0].time + 1e3 - now));
+        this.cancelSendDelay = finish;
+      });
+    }
+    throw this.cancelled();
+  }
+  /**
+   * 设置公共 RTC 监听器。
+   */
+  setEventListener(listener) {
+    this.listener = listener;
+  }
+  /**
+   * 将声网发布、DataStream、网络质量与 Token 事件桥接到公共传输层。
+   */
+  registerEvents(client) {
+    const active = () => this.client === client && this.connection !== void 0 && !this.rejoinTask;
+    const mediaActive = () => active() && !this.tokenExpired;
+    const handleExpired = () => {
+      if (!active() || this.tokenExpired) return;
+      this.tokenExpired = true;
+      this.listener?.onTokenExpired?.();
+    };
+    client.on("user-published", (user, kind) => {
+      if (!mediaActive()) return;
+      if (kind === "video") this.listener?.onRemoteVideoPublished(String(user.uid), true);
+      if (kind === "audio" && this.requestedAudio.has(String(user.uid))) {
+        void this.subscribeRemoteAudio(String(user.uid), true).catch((error) => {
+          if (active()) this.listener?.onError?.(this.mapError(error));
+        });
+      }
+    });
+    client.on("user-unpublished", (user, kind) => {
+      if (!mediaActive()) return;
+      if (kind === "video") this.listener?.onRemoteVideoPublished(String(user.uid), false);
+      if (kind === "audio") user.audioTrack?.stop();
+    });
+    client.on("user-left", (user) => {
+      if (mediaActive()) this.listener?.onRemoteVideoPublished(String(user.uid), false);
+    });
+    client.on("stream-message", (uid, data) => {
+      if (mediaActive()) this.listener?.onCustomMessageReceived(String(uid), typeof data === "string" ? data : new TextDecoder().decode(data));
+    });
+    client.on("network-quality", (quality) => {
+      if (mediaActive()) AgoraRtcStatistics.network(quality, this.listener);
+    });
+    client.on("token-privilege-will-expire", () => {
+      if (active() && !this.tokenExpired) this.listener?.onTokenWillExpire?.();
+    });
+    client.on("token-privilege-did-expire", handleExpired);
+    client.on("connection-state-change", (state2, previous, reason) => {
+      if (state2 === "DISCONNECTED" && reason === "TOKEN_EXPIRE") {
+        handleExpired();
+        return;
+      }
+      if (active() && !this.tokenExpired && state2 === "DISCONNECTED" && previous !== "DISCONNECTED") {
+        this.listener?.onError?.(new XmaxError("RTC_ERROR" /* rtcError */, `Agora connection disconnected: ${reason ?? "unknown"}`));
+      }
+    });
+  }
+  /**
+   * 清理房间状态、播放和发送队列，不释放本地视频采集。
+   */
+  clearRoom() {
+    this.roomVersion++;
+    this.cancelRejoin?.();
+    this.connection = void 0;
+    this.tokenExpired = false;
+    this.videoPublishRequested = false;
+    this.audioPublishRequested = false;
+    clearInterval(this.statisticsTimer);
+    this.statisticsTimer = void 0;
+    this.cancelSendDelay?.();
+    this.cancelActiveSend?.();
+    this.sentPackets = [];
+    this.sendTail = Promise.resolve();
+    this.requestedAudio.clear();
+    this.audioVolumes.clear();
+    for (const user of this.client?.remoteUsers ?? []) user.audioTrack?.stop();
+  }
+  /**
+   * 判断异步恢复工作是否仍属于当前房间生命周期。
+   */
+  isRoomCurrent(client, version) {
+    return this.client === client && this.connection !== void 0 && this.roomVersion === version;
+  }
+  /**
+   * 退房、销毁或换房后停止后续恢复步骤。
+   */
+  ensureRoomCurrent(client, version) {
+    if (!this.isRoomCurrent(client, version)) throw this.cancelled();
+  }
+  /**
+   * 获取已初始化的 client。
+   */
+  requireClient() {
+    if (!this.client) throw new XmaxError("RTC_ERROR" /* rtcError */, "Agora is not initialized");
+    return this.client;
+  }
+  /**
+   * 获取已启动的相机采集。
+   */
+  requireCamera() {
+    if (!this.camera) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera capture is not running");
+    return this.camera;
+  }
+  /**
+   * 执行声网操作并统一错误类型。
+   */
+  async run(operation) {
+    try {
+      return await operation();
+    } catch (error) {
+      throw this.mapError(error);
+    }
+  }
+  /**
+   * 只传递错误码，不回显可能包含 Token 的厂商原始错误消息。
+   */
+  mapError(error, permissionCode) {
+    if (error instanceof XmaxError) return error;
+    const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "UNKNOWN";
+    const safeCode = /^[A-Z_0-9-]+$/.test(code) ? code : "UNKNOWN";
+    return new XmaxError(permissionCode && safeCode === "PERMISSION_DENIED" ? permissionCode : "RTC_ERROR" /* rtcError */, `Agora operation failed (${safeCode})`);
+  }
+  /**
+   * 构造异步操作失效错误。
+   */
+  cancelled() {
+    return new XmaxError("CANCELLED" /* cancelled */, "Agora operation was cancelled");
+  }
+};
+/**
+ * 模块级区域约束：setArea 是全局设置，拒绝同时运行不同区域，避免静默覆盖。
+ */
+__publicField(_AgoraRtcManager, "regions", /* @__PURE__ */ new Map());
+var AgoraRtcManager = _AgoraRtcManager;
+
+// src/Foundation/RTC/RtcProvider.ts
+var RtcProvider = /* @__PURE__ */ ((RtcProvider2) => {
+  RtcProvider2["trtc"] = "trtc";
+  RtcProvider2["agora"] = "agora";
+  RtcProvider2["vertc"] = "vertc";
+  return RtcProvider2;
+})(RtcProvider || {});
+
+// src/Foundation/RTC/TRTC/RtcEngineManager.ts
 var RtcEngineLease = class {
   /**
    * 为已创建的引擎生成独占租约标识，供引擎管理器核对释放请求。
@@ -1304,34 +2028,15 @@ var RtcStatsLogger = class {
   }
 };
 
-// src/Foundation/RTC/RtcVideoOrientation.ts
-function shouldTransposeRtcVideoSize(environment) {
-  const userAgent = environment?.userAgent ?? (typeof navigator === "undefined" ? "" : navigator.userAgent);
-  const maxTouchPoints = environment?.maxTouchPoints ?? (typeof navigator === "undefined" ? 0 : navigator.maxTouchPoints ?? 0);
-  const mobile = /Android|webOS|iPhone|iPad|iPod|Mobile/i.test(userAgent) || /Macintosh/i.test(userAgent) && maxTouchPoints > 1;
-  if (!mobile) {
-    return false;
-  }
-  const orientationType = environment?.orientationType ?? (typeof window === "undefined" ? void 0 : window.screen?.orientation?.type);
-  if (orientationType !== void 0) {
-    return orientationType.includes("portrait");
-  }
-  const degrees = environment?.orientationDegrees ?? (typeof window === "undefined" ? void 0 : window.orientation);
-  return degrees === 0 || degrees === 180;
-}
-function rtcOrientedVideoSize(size, environment) {
-  return shouldTransposeRtcVideoSize(environment) ? { width: size.height, height: size.width } : size;
-}
-
-// src/Foundation/RTC/RemoteAudioVolumeControl.ts
-function canControlRemoteAudioVolume(environment) {
+// src/Foundation/RTC/TRTC/TrtcAudioVolumeSupport.ts
+function canControlTrtcRemoteAudioVolume(environment) {
   const userAgent = environment?.userAgent ?? (typeof navigator === "undefined" ? "" : navigator.userAgent);
   const maxTouchPoints = environment?.maxTouchPoints ?? (typeof navigator === "undefined" ? 0 : navigator.maxTouchPoints ?? 0);
   const ios = /iPhone|iPad|iPod/i.test(userAgent) || /Macintosh/i.test(userAgent) && maxTouchPoints > 1;
   return !ios;
 }
 
-// src/Foundation/RTC/RtcManager.ts
+// src/Foundation/RTC/TRTC/TrtcRtcManager.ts
 var RTC_EVENT = {
   remoteVideoAvailable: "remote-video-available",
   remoteVideoUnavailable: "remote-video-unavailable",
@@ -1347,7 +2052,7 @@ var QOS_PREFERENCE_MAP = {
   ["maintainFramerate" /* maintainFramerate */]: "smooth",
   ["maintainQuality" /* maintainQuality */]: "clear"
 };
-var RtcManager = class {
+var TrtcRtcManager = class {
   /**
    * 创建 RTC 管理器。
    *
@@ -1515,6 +2220,9 @@ var RtcManager = class {
    * @throws 引擎未初始化、进房参数无效或进房失败时抛出错误。
    */
   async joinRoom(configuration) {
+    if (configuration.provider !== "trtc") {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "TRTC credentials required");
+    }
     const engine = this.requireEngine();
     const sdkAppId = Number(configuration.sdkAppID);
     if (!Number.isInteger(sdkAppId) || sdkAppId <= 0) {
@@ -1711,7 +2419,7 @@ var RtcManager = class {
    * 当前平台是否支持远端音量控制（iOS Safari/WKWebView 不支持）。
    */
   get supportsRemoteAudioVolumeControl() {
-    return canControlRemoteAudioVolume();
+    return canControlTrtcRemoteAudioVolume();
   }
   /**
    * 设置指定远端用户的音频播放音量。
@@ -1726,7 +2434,7 @@ var RtcManager = class {
   setRemoteAudioVolume(volume, userID) {
     const engine = this.requireEngine();
     const normalized = Math.min(Math.max(Math.round(volume), 0), 100);
-    if (!canControlRemoteAudioVolume()) {
+    if (!canControlTrtcRemoteAudioVolume()) {
       void engine.muteRemoteAudio(userID, normalized === 0).catch((error) => {
         XmaxLogger.rtc.warning(
           () => `\u8FDC\u7AEF\u97F3\u9891\u64AD\u653E\u72B6\u6001\u5207\u6362\u5931\u8D25 (Failed to Toggle Remote Audio Playback)
@@ -1742,7 +2450,7 @@ var RtcManager = class {
    *
    * @throws 未在房间中或消息编码后超过 1000 字节时抛出错误。
    */
-  sendRoomMessage(message) {
+  async sendRoomMessage(message) {
     const engine = this.requireEngine();
     if (!this.isInRoom) {
       throw new XmaxError(
@@ -1762,6 +2470,11 @@ var RtcManager = class {
       data: encoded.buffer
     });
   }
+  /**
+   * TRTC 凭据由会话层缓存，保持现有进房鉴权行为。
+   */
+  async updateCredentials(_configuration) {
+  }
   /**
    * 设置 RTC 事件监听器，传入空值时清除监听器。
    */
@@ -1838,53 +2551,679 @@ var RtcManager = class {
       }
       this.eventListener?.onRemoteVideoPublished(event.userId, false);
     });
-    source.on(RTC_EVENT.customMessage, (event) => {
-      if (event.cmdId !== CUSTOM_MESSAGE_CMD_ID) {
-        return;
-      }
-      let message;
-      try {
-        message = new TextDecoder().decode(event.data);
-      } catch {
-        XmaxLogger.rtc.warning(() => "\u81EA\u5B9A\u4E49\u6D88\u606F\u89E3\u7801\u5931\u8D25 (Failed to Decode Custom Message)");
-        return;
+    source.on(RTC_EVENT.customMessage, (event) => {
+      if (event.cmdId !== CUSTOM_MESSAGE_CMD_ID) {
+        return;
+      }
+      let message;
+      try {
+        message = new TextDecoder().decode(event.data);
+      } catch {
+        XmaxLogger.rtc.warning(() => "\u81EA\u5B9A\u4E49\u6D88\u606F\u89E3\u7801\u5931\u8D25 (Failed to Decode Custom Message)");
+        return;
+      }
+      this.eventListener?.onCustomMessageReceived(event.userId, message);
+    });
+  }
+  /**
+   * 返回当前引擎实例；未初始化时抛出错误。
+   */
+  requireEngine() {
+    const engine = this.lease?.engine;
+    if (!engine) {
+      throw new XmaxError(
+        "RTC_ERROR" /* rtcError */,
+        "RTC engine is not initialized"
+      );
+    }
+    return engine;
+  }
+  /**
+   * 将 TRTC 错误映射为 SDK 统一错误。
+   */
+  mapError(error) {
+    if (error instanceof XmaxError) {
+      return error;
+    }
+    const rtcError = error;
+    const originName = rtcError?.originError?.name ?? "";
+    const message = typeof rtcError?.message === "string" && rtcError.message.trim().length > 0 ? rtcError.message.trim() : String(error);
+    if (originName === "NotAllowedError" || originName === "SecurityError" || /NotAllowed/i.test(message)) {
+      return new XmaxError("CAMERA_PERMISSION_DENIED" /* cameraPermissionDenied */, message);
+    }
+    if (originName) {
+      return new XmaxError("MEDIA_ERROR" /* mediaError */, message);
+    }
+    return new XmaxError("RTC_ERROR" /* rtcError */, message);
+  }
+};
+
+// src/Foundation/RTC/VeRTC/VeRtcStatistics.ts
+var VeRtcStatistics = class {
+  static local(stats) {
+    return Object.freeze({
+      width: this.valid(stats.encodedFrameWidth, 1),
+      height: this.valid(stats.encodedFrameHeight, 1),
+      frameRate: this.valid(stats.sentFrameRate),
+      bitrateKbps: this.valid(stats.sentKBitrate),
+      uplinkLossPercent: this.loss(stats.videoLossRate)
+    });
+  }
+  static remote(userID, stats, uplinkLossPercent) {
+    return Object.freeze({
+      userID,
+      width: this.valid(stats.width, 1),
+      height: this.valid(stats.height, 1),
+      frameRate: this.valid(stats.decoderOutputFrameRate),
+      bitrateKbps: this.valid(stats.receivedKBitrate),
+      rttMs: this.valid(stats.rtt),
+      downlinkLossPercent: this.loss(stats.videoLossRate),
+      endToEndDelayMs: this.valid(stats.e2eDelay),
+      uplinkLossPercent
+    });
+  }
+  static quality(value) {
+    return Number.isInteger(value) && value >= 0 && value <= 6 ? value : void 0;
+  }
+  static valid(value, minimum = 0) {
+    return typeof value === "number" && Number.isFinite(value) && value >= minimum ? value : void 0;
+  }
+  static loss(value) {
+    return Number.isFinite(value) && value >= 0 && value <= 1 ? value * 100 : void 0;
+  }
+};
+
+// src/Foundation/RTC/VeRTC/VeRtcManager.ts
+var VERTC_APP_ID = "69a177e226e9b90176a86b96";
+var VeRtcManager = class {
+  constructor(options = {}) {
+    __publicField(this, "loadSDK");
+    __publicField(this, "sdk");
+    __publicField(this, "engine");
+    __publicField(this, "initialization");
+    __publicField(this, "lifecycle", 0);
+    __publicField(this, "captureVersion", 0);
+    __publicField(this, "camera");
+    __publicField(this, "microphone", false);
+    __publicField(this, "connection");
+    __publicField(this, "joined", false);
+    __publicField(this, "roomVersion", 0);
+    __publicField(this, "roomAbort", new AbortController());
+    __publicField(this, "recovery");
+    __publicField(this, "joining");
+    __publicField(this, "tokenExpired", false);
+    __publicField(this, "publishPrivilegeExpired", false);
+    __publicField(this, "subscribePrivilegeExpired", false);
+    __publicField(this, "videoRequested", false);
+    __publicField(this, "audioRequested", false);
+    __publicField(this, "listener");
+    __publicField(this, "publishedVideo", /* @__PURE__ */ new Set());
+    __publicField(this, "publishedAudio", /* @__PURE__ */ new Set());
+    __publicField(this, "requestedVideo", /* @__PURE__ */ new Set());
+    __publicField(this, "requestedAudio", /* @__PURE__ */ new Set());
+    __publicField(this, "audioVolumes", /* @__PURE__ */ new Map());
+    __publicField(this, "audioPlayers", /* @__PURE__ */ new Map());
+    __publicField(this, "audioSubscriptions", /* @__PURE__ */ new Map());
+    __publicField(this, "remoteStatistics", /* @__PURE__ */ new Map());
+    __publicField(this, "uplinkLossPercent");
+    this.loadSDK = options.loadSDK ?? (() => import("@volcengine/rtc"));
+  }
+  get isInitialized() {
+    return this.engine !== void 0;
+  }
+  get supportsRemoteAudioVolumeControl() {
+    if (typeof navigator === "undefined") return true;
+    return !(/iPad|iPhone|iPod/.test(navigator.userAgent) || /Macintosh/.test(navigator.userAgent) && navigator.maxTouchPoints > 1);
+  }
+  async initialize() {
+    if (this.engine) return;
+    if (this.initialization) return this.initialization;
+    const version = this.lifecycle;
+    const operation = (async () => {
+      const sdk = await this.loadSDK();
+      if (version !== this.lifecycle) throw this.cancelled();
+      sdk.default.setLogConfig({ logLevel: "none" });
+      const engine = sdk.default.createEngine(VERTC_APP_ID, { autoPlayPolicy: sdk.RTCAutoPlayPolicy.PLAY_MANUALLY });
+      this.sdk = sdk;
+      this.engine = engine;
+      this.registerEvents(engine);
+    })();
+    this.initialization = operation;
+    try {
+      await operation;
+    } finally {
+      if (this.initialization === operation) this.initialization = void 0;
+    }
+  }
+  async destroy() {
+    this.lifecycle++;
+    this.captureVersion++;
+    const engine = this.engine;
+    const sdk = this.sdk;
+    this.listener = void 0;
+    this.clearRoom();
+    this.engine = void 0;
+    this.sdk = void 0;
+    this.camera = void 0;
+    this.microphone = false;
+    engine?.removeAllListeners();
+    if (engine && sdk) sdk.default.destroyEngine(engine);
+  }
+  async startCameraCapture(options) {
+    const engine = this.requireEngine();
+    if (this.camera) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera capture is already running");
+    const version = ++this.captureVersion;
+    await this.run(() => engine.setVideoEncoderConfig({
+      ...rtcOrientedVideoSize({ width: options.width, height: options.height }),
+      frameRate: options.frameRate,
+      maxKbps: 1e3,
+      preferCodecName: this.sdk.VideoCodecType.H264,
+      contentHint: "motion"
+    }));
+    if (engine !== this.engine || version !== this.captureVersion) throw this.cancelled();
+    try {
+      await engine.startVideoCapture(options.position === "front" /* front */ ? "user" : "environment");
+      if (engine !== this.engine || version !== this.captureVersion) {
+        await engine.stopVideoCapture().catch(() => {
+        });
+        throw this.cancelled();
+      }
+      const track = engine.getLocalStreamTrack(this.sdk.StreamIndex.STREAM_INDEX_MAIN, "video");
+      if (!track) {
+        await engine.stopVideoCapture();
+        throw new XmaxError("RTC_ERROR" /* rtcError */, "VeRTC camera track is unavailable");
+      }
+      this.camera = track;
+      return track;
+    } catch (error) {
+      throw this.mapError(error, "CAMERA_PERMISSION_DENIED" /* cameraPermissionDenied */);
+    }
+  }
+  async switchCameraCapture(to) {
+    const engine = this.requireEngine();
+    this.requireCamera();
+    const version = this.captureVersion;
+    await this.run(() => engine.setVideoCaptureDevice(to === "front" /* front */ ? "user" : "environment"));
+    if (engine !== this.engine || version !== this.captureVersion) throw this.cancelled();
+    const track = engine.getLocalStreamTrack(this.sdk.StreamIndex.STREAM_INDEX_MAIN, "video");
+    if (!track) throw new XmaxError("RTC_ERROR" /* rtcError */, "VeRTC camera track is unavailable");
+    this.camera = track;
+    return track;
+  }
+  async stopCameraCapture() {
+    this.captureVersion++;
+    this.camera = void 0;
+    if (this.engine) await this.run(() => this.engine.stopVideoCapture());
+  }
+  async configureVideoEncoding(config) {
+    const engine = this.requireEngine();
+    this.requireCamera();
+    await this.run(() => engine.setVideoEncoderConfig({
+      ...rtcOrientedVideoSize({ width: config.width, height: config.height }),
+      frameRate: config.frameRate,
+      maxKbps: config.maximumBitrate,
+      contentHint: config.encoderPreference === "maintainFramerate" /* maintainFramerate */ ? "motion" : "detail",
+      preferCodecName: this.sdk.VideoCodecType.H264
+    }));
+  }
+  async joinRoom(config) {
+    await this.joining?.catch(() => {
+    });
+    await this.recovery?.catch(() => {
+    });
+    const engine = this.requireEngine();
+    if (config.provider !== "vertc" || config.appID !== VERTC_APP_ID || this.connection) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "VeRTC credentials for the configured AppID and an idle room are required");
+    }
+    this.clearRoom();
+    this.connection = config;
+    const version = this.roomVersion;
+    const task = this.performJoin(engine, config, version);
+    this.joining = task;
+    try {
+      await task;
+    } finally {
+      if (this.joining === task) this.joining = void 0;
+    }
+  }
+  async performJoin(engine, config, version) {
+    try {
+      await this.enter(engine, config);
+      if (!this.isCurrent(engine, version)) {
+        await engine.leaveRoom().catch(() => {
+        });
+        throw this.cancelled();
+      }
+      this.joined = true;
+      this.replayVideo();
+    } catch (error) {
+      if (this.isCurrent(engine, version)) this.clearRoom();
+      throw this.mapError(error);
+    }
+  }
+  enter(engine, config) {
+    return this.run(() => engine.joinRoom(config.roomToken, config.roomID, { userId: config.userID }, {
+      isAutoPublish: false,
+      isAutoSubscribeAudio: false,
+      isAutoSubscribeVideo: false,
+      roomProfileType: this.sdk.RoomProfileType.communication
+    }));
+  }
+  async leaveRoom() {
+    const engine = this.engine;
+    this.clearRoom();
+    if (engine) await this.run(() => engine.leaveRoom());
+  }
+  /** 正常续签仅 updateToken；被移出房间后重进，恢复发布与订阅意图。 */
+  async updateCredentials(config, signal) {
+    const engine = this.requireEngine();
+    const current = this.connection;
+    if (signal?.aborted) throw this.cancelled();
+    if (!current || config.provider !== "vertc" || config.appID !== current.appID || config.roomID !== current.roomID || config.userID !== current.userID) {
+      throw new XmaxError("SESSION_ERROR" /* sessionError */, "VeRTC session binding changed");
+    }
+    const version = this.roomVersion;
+    if (this.recovery) await this.cancellable(this.recovery, signal);
+    if (!this.isCurrent(engine, version)) throw this.cancelled();
+    const task = this.renew(engine, config, version);
+    this.recovery = task;
+    void task.finally(() => {
+      if (this.recovery === task) this.recovery = void 0;
+    }).catch(() => {
+    });
+    await this.cancellable(task, signal);
+  }
+  async renew(engine, config, version) {
+    if (!this.tokenExpired) {
+      try {
+        await this.run(() => engine.updateToken(config.roomToken));
+      } catch (error) {
+        this.ensureCurrent(engine, version);
+        if (!this.tokenExpired) throw error;
+      }
+    }
+    this.ensureCurrent(engine, version);
+    const restore = this.tokenExpired || this.publishPrivilegeExpired || this.subscribePrivilegeExpired;
+    if (restore) {
+      this.joined = false;
+      this.listener?.onRoomRejoining?.();
+      this.clearPlayers();
+      this.clearStatistics();
+      if (this.tokenExpired) {
+        this.publishedVideo.clear();
+        this.publishedAudio.clear();
+        await this.run(() => engine.leaveRoom());
+        this.ensureCurrent(engine, version);
+        await this.enter(engine, config);
+        if (!this.isCurrent(engine, version)) {
+          await engine.leaveRoom().catch(() => {
+          });
+          throw this.cancelled();
+        }
+      }
+      if ((this.tokenExpired || this.publishPrivilegeExpired) && this.videoRequested && this.camera) {
+        await this.run(() => engine.publishStream(this.sdk.MediaType.VIDEO));
+        this.ensureCurrent(engine, version);
+        if (!this.videoRequested) {
+          await this.run(() => engine.unpublishStream(this.sdk.MediaType.VIDEO));
+          this.ensureCurrent(engine, version);
+        }
+      }
+      if ((this.tokenExpired || this.publishPrivilegeExpired) && this.audioRequested && this.microphone) {
+        await this.run(() => engine.publishStream(this.sdk.MediaType.AUDIO));
+        this.ensureCurrent(engine, version);
+        if (!this.audioRequested) {
+          await this.run(() => engine.unpublishStream(this.sdk.MediaType.AUDIO));
+          this.ensureCurrent(engine, version);
+        }
+      }
+    }
+    this.connection = config;
+    this.tokenExpired = false;
+    this.publishPrivilegeExpired = false;
+    this.subscribePrivilegeExpired = false;
+    this.joined = true;
+    if (restore) {
+      this.replayVideo();
+      for (const userID of this.requestedAudio) {
+        if (this.publishedAudio.has(userID)) await this.subscribeRemoteAudio(userID, true);
+        this.ensureCurrent(engine, version);
+      }
+    }
+  }
+  async publishLocalVideo() {
+    const engine = this.requireEngine();
+    this.requireCamera();
+    this.videoRequested = true;
+    const version = this.roomVersion;
+    await this.recovery;
+    this.ensureCurrent(engine, version);
+    if (!this.videoRequested) throw this.cancelled();
+    await this.run(() => engine.publishStream(this.sdk.MediaType.VIDEO));
+  }
+  async unpublishLocalVideo() {
+    this.videoRequested = false;
+    if (this.joined && !this.tokenExpired) await this.run(() => this.requireEngine().unpublishStream(this.sdk.MediaType.VIDEO));
+  }
+  async publishLocalAudio() {
+    const engine = this.requireEngine();
+    this.audioRequested = true;
+    const version = this.roomVersion;
+    await this.recovery;
+    this.ensureCurrent(engine, version);
+    try {
+      if (!this.microphone) {
+        await engine.startAudioCapture();
+        if (!this.isCurrent(engine, version)) {
+          await engine.stopAudioCapture().catch(() => {
+          });
+          throw this.cancelled();
+        }
+        this.microphone = true;
+      }
+      if (!this.audioRequested) throw this.cancelled();
+      await engine.publishStream(this.sdk.MediaType.AUDIO);
+    } catch (error) {
+      throw this.mapError(error, "MICROPHONE_PERMISSION_DENIED" /* microphonePermissionDenied */);
+    }
+  }
+  async unpublishLocalAudio() {
+    this.audioRequested = false;
+    if (this.joined && !this.tokenExpired) await this.run(() => this.requireEngine().unpublishStream(this.sdk.MediaType.AUDIO));
+  }
+  async subscribeRemoteVideo(userID, subscribe) {
+    const engine = this.requireEngine();
+    const version = this.roomVersion;
+    if (!subscribe) {
+      this.requestedVideo.delete(userID);
+      this.remoteStatistics.delete(userID);
+      this.emitRemoteStatistics();
+      if (this.joined && !this.tokenExpired) await this.run(() => engine.unsubscribeStream(userID, this.sdk.MediaType.VIDEO));
+      return;
+    }
+    this.requestedVideo.add(userID);
+    await this.run(() => engine.subscribeStream(userID, this.sdk.MediaType.VIDEO));
+    this.ensureCurrent(engine, version);
+    if (!this.requestedVideo.has(userID)) return;
+    const track = engine.getRemoteStreamTrack(userID, this.sdk.StreamIndex.STREAM_INDEX_MAIN, "video");
+    if (!track) throw new XmaxError("RTC_ERROR" /* rtcError */, "VeRTC remote video track is unavailable");
+    return track;
+  }
+  async subscribeRemoteAudio(userID, subscribe) {
+    const engine = this.requireEngine();
+    const version = this.roomVersion;
+    if (!subscribe) {
+      this.requestedAudio.delete(userID);
+      this.clearPlayer(userID);
+      if (this.joined && !this.tokenExpired && this.publishedAudio.has(userID)) await this.run(() => engine.unsubscribeStream(userID, this.sdk.MediaType.AUDIO));
+      return;
+    }
+    this.requestedAudio.add(userID);
+    if (!this.joined || this.tokenExpired || !this.publishedAudio.has(userID)) return;
+    const subscription = {};
+    this.audioSubscriptions.set(userID, subscription);
+    await this.run(() => engine.subscribeStream(userID, this.sdk.MediaType.AUDIO));
+    if (!this.isCurrent(engine, version) || !this.joined || this.tokenExpired || this.audioSubscriptions.get(userID) !== subscription || !this.requestedAudio.has(userID) || !this.publishedAudio.has(userID)) return;
+    const track = engine.getRemoteStreamTrack(userID, this.sdk.StreamIndex.STREAM_INDEX_MAIN, "audio");
+    if (!track) return;
+    this.clearPlayer(userID);
+    const player = document.createElement("audio");
+    player.srcObject = new MediaStream([track]);
+    this.audioPlayers.set(userID, player);
+    this.applyAudioVolume(userID);
+  }
+  setRemoteAudioVolume(volume, userID) {
+    this.audioVolumes.set(userID, Number.isFinite(volume) ? Math.max(0, Math.min(100, Math.round(volume))) : 0);
+    this.applyAudioVolume(userID);
+  }
+  applyAudioVolume(userID) {
+    const player = this.audioPlayers.get(userID);
+    if (!player) return;
+    const volume = this.audioVolumes.get(userID) ?? 0;
+    player.muted = volume === 0 || !this.requestedAudio.has(userID);
+    if (this.supportsRemoteAudioVolumeControl) player.volume = volume / 100;
+    if (player.muted) player.pause();
+    else void player.play().catch(() => {
+      XmaxLogger.rtc.warning(() => "VeRTC audio playback requires a user interaction");
+    });
+  }
+  async sendRoomMessage(message) {
+    const engine = this.requireEngine();
+    const version = this.roomVersion;
+    if (!this.joined || this.tokenExpired) throw this.cancelled();
+    if (new TextEncoder().encode(message).byteLength > 64 * 1024) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "VeRTC room message exceeds the 64-KiB limit");
+    }
+    await this.cancellable(this.run(async () => {
+      const sent = engine.sendRoomMessage(message);
+      if (!sent) throw new XmaxError("RTC_ERROR" /* rtcError */, "VeRTC room message was not sent");
+      await sent;
+    }), void 0, 5e3);
+    this.ensureCurrent(engine, version);
+  }
+  setEventListener(listener) {
+    this.listener = listener;
+  }
+  registerEvents(engine) {
+    const events = this.sdk.default.events;
+    const active = () => engine === this.engine && this.connection !== void 0;
+    const mediaActive = () => active() && this.joined && !this.tokenExpired;
+    const video = (mediaType) => (mediaType & this.sdk.MediaType.VIDEO) !== 0;
+    const audio = (mediaType) => (mediaType & this.sdk.MediaType.AUDIO) !== 0;
+    engine.on(events.onUserPublishStream, ({ userId, mediaType }) => {
+      if (!active()) return;
+      if (video(mediaType)) {
+        this.publishedVideo.add(userId);
+        if (mediaActive()) this.listener?.onRemoteVideoPublished(userId, true);
+      }
+      if (audio(mediaType)) {
+        this.publishedAudio.add(userId);
+        if (mediaActive() && this.requestedAudio.has(userId)) {
+          void this.subscribeRemoteAudio(userId, true).catch((error) => {
+            if (mediaActive()) this.listener?.onError?.(this.mapError(error));
+          });
+        }
+      }
+    });
+    engine.on(events.onUserUnpublishStream, ({ userId, mediaType }) => {
+      if (!active()) return;
+      if (video(mediaType)) this.removeVideo(userId);
+      if (audio(mediaType)) {
+        this.publishedAudio.delete(userId);
+        this.clearPlayer(userId);
+      }
+    });
+    engine.on(events.onUserLeave, ({ userInfo }) => {
+      if (!active()) return;
+      this.removeVideo(userInfo.userId);
+      this.publishedAudio.delete(userInfo.userId);
+      this.clearPlayer(userInfo.userId);
+    });
+    engine.on(events.onRoomMessageReceived, ({ userId, message }) => {
+      if (mediaActive() && typeof message === "string") this.listener?.onCustomMessageReceived(userId, message);
+    });
+    const willExpire = () => {
+      if (active()) this.listener?.onTokenWillExpire?.();
+    };
+    engine.on(events.onTokenWillExpire, willExpire);
+    engine.on(events.onTokenPublishPrivilegeWillExpire, willExpire);
+    engine.on(events.onTokenSubscribePrivilegeWillExpire, willExpire);
+    engine.on(events.onTokenPublishPrivilegeDidExpired, () => {
+      if (!active() || this.publishPrivilegeExpired) return;
+      this.publishPrivilegeExpired = true;
+      this.listener?.onTokenExpired?.();
+    });
+    engine.on(events.onTokenSubscribePrivilegeDidExpired, () => {
+      if (!active() || this.subscribePrivilegeExpired) return;
+      this.subscribePrivilegeExpired = true;
+      this.clearPlayers();
+      this.listener?.onTokenExpired?.();
+    });
+    engine.on(events.onError, ({ errorCode }) => {
+      if (!active()) return;
+      if (errorCode === "TOKEN_EXPIRED") {
+        if (this.tokenExpired) return;
+        this.tokenExpired = true;
+        this.clearPlayers();
+        this.listener?.onTokenExpired?.();
+      } else this.listener?.onError?.(this.mapError({ code: errorCode }));
+    });
+    engine.on(events.onConnectionStateChanged, ({ state: state2 }) => {
+      if (!mediaActive() || state2 !== this.sdk.ConnectionState.CONNECTION_STATE_RECONNECTED) return;
+      this.listener?.onRoomRejoining?.();
+      this.clearPlayers();
+      this.clearStatistics();
+      this.replayVideo();
+      for (const userID of this.requestedAudio) {
+        void this.subscribeRemoteAudio(userID, true).catch((error) => {
+          if (mediaActive()) this.listener?.onError?.(this.mapError(error));
+        });
       }
-      this.eventListener?.onCustomMessageReceived(event.userId, message);
+    });
+    engine.on(events.onNetworkQuality, (up, down) => {
+      if (mediaActive()) this.listener?.onNetworkStatistics?.(Object.freeze({
+        uplinkQuality: VeRtcStatistics.quality(up),
+        downlinkQuality: VeRtcStatistics.quality(down)
+      }));
+    });
+    engine.on(events.onLocalStreamStats, (stats) => {
+      if (!mediaActive() || stats.isScreen || !this.videoRequested) return;
+      const result = VeRtcStatistics.local(stats.videoStats);
+      this.uplinkLossPercent = result.uplinkLossPercent;
+      this.listener?.onLocalVideoStatistics?.(result);
+      XmaxLogger.rtc.info(() => `VeRTC local video statistics: ${JSON.stringify(result)}`, 2 /* performance */);
+    });
+    engine.on(events.onRemoteStreamStats, (stats) => {
+      if (!mediaActive() || stats.isScreen || !this.requestedVideo.has(stats.userId)) return;
+      this.remoteStatistics.set(stats.userId, VeRtcStatistics.remote(stats.userId, stats.videoStats, this.uplinkLossPercent));
+      this.emitRemoteStatistics();
     });
   }
-  /**
-   * 返回当前引擎实例；未初始化时抛出错误。
-   */
+  replayVideo() {
+    for (const userID of this.publishedVideo) this.listener?.onRemoteVideoPublished(userID, true);
+  }
+  removeVideo(userID) {
+    this.publishedVideo.delete(userID);
+    this.remoteStatistics.delete(userID);
+    this.emitRemoteStatistics();
+    if (this.joined && !this.tokenExpired) this.listener?.onRemoteVideoPublished(userID, false);
+  }
+  emitRemoteStatistics() {
+    this.listener?.onRemoteVideoStatistics?.(Object.freeze([...this.remoteStatistics.values()]));
+  }
+  clearStatistics() {
+    this.remoteStatistics.clear();
+    this.uplinkLossPercent = void 0;
+    this.listener?.onLocalVideoStatistics?.(void 0);
+    this.emitRemoteStatistics();
+  }
+  clearPlayer(userID) {
+    this.audioSubscriptions.delete(userID);
+    const player = this.audioPlayers.get(userID);
+    if (player) {
+      player.pause();
+      player.srcObject = null;
+    }
+    this.audioPlayers.delete(userID);
+  }
+  clearPlayers() {
+    this.audioSubscriptions.clear();
+    for (const userID of this.audioPlayers.keys()) this.clearPlayer(userID);
+  }
+  clearRoom() {
+    this.roomVersion++;
+    this.roomAbort.abort();
+    this.roomAbort = new AbortController();
+    this.connection = void 0;
+    this.joined = false;
+    this.tokenExpired = false;
+    this.publishPrivilegeExpired = false;
+    this.subscribePrivilegeExpired = false;
+    this.videoRequested = false;
+    this.audioRequested = false;
+    this.publishedVideo.clear();
+    this.publishedAudio.clear();
+    this.requestedVideo.clear();
+    this.requestedAudio.clear();
+    this.audioVolumes.clear();
+    this.clearPlayers();
+    this.clearStatistics();
+  }
+  /** 业务取消立即结束等待；底层迟到结果由版本检查清理。 */
+  async cancellable(task, signal, timeoutMs) {
+    const roomSignal = this.roomAbort.signal;
+    return new Promise((resolve, reject) => {
+      const timer = timeoutMs === void 0 ? void 0 : setTimeout(() => {
+        cleanup();
+        reject(new XmaxError("TIMEOUT" /* timeout */, "VeRTC room message send timed out"));
+      }, timeoutMs);
+      const cleanup = () => {
+        clearTimeout(timer);
+        roomSignal.removeEventListener("abort", cancel);
+        signal?.removeEventListener("abort", cancel);
+      };
+      const cancel = () => {
+        if (signal?.aborted && !roomSignal.aborted) this.roomVersion++;
+        cleanup();
+        reject(this.cancelled());
+      };
+      roomSignal.addEventListener("abort", cancel, { once: true });
+      signal?.addEventListener("abort", cancel, { once: true });
+      task.then((value) => {
+        cleanup();
+        resolve(value);
+      }, (error) => {
+        cleanup();
+        reject(error);
+      });
+      if (roomSignal.aborted || signal?.aborted) cancel();
+    });
+  }
+  isCurrent(engine, version) {
+    return this.engine === engine && this.connection !== void 0 && this.roomVersion === version;
+  }
+  ensureCurrent(engine, version) {
+    if (!this.isCurrent(engine, version)) throw this.cancelled();
+  }
   requireEngine() {
-    const engine = this.lease?.engine;
-    if (!engine) {
-      throw new XmaxError(
-        "RTC_ERROR" /* rtcError */,
-        "RTC engine is not initialized"
-      );
-    }
-    return engine;
+    if (!this.engine) throw new XmaxError("RTC_ERROR" /* rtcError */, "VeRTC is not initialized");
+    return this.engine;
   }
-  /**
-   * 将 TRTC 错误映射为 SDK 统一错误。
-   */
-  mapError(error) {
-    if (error instanceof XmaxError) {
-      return error;
-    }
-    const rtcError = error;
-    const originName = rtcError?.originError?.name ?? "";
-    const message = typeof rtcError?.message === "string" && rtcError.message.trim().length > 0 ? rtcError.message.trim() : String(error);
-    if (originName === "NotAllowedError" || originName === "SecurityError" || /NotAllowed/i.test(message)) {
-      return new XmaxError("CAMERA_PERMISSION_DENIED" /* cameraPermissionDenied */, message);
-    }
-    if (originName) {
-      return new XmaxError("MEDIA_ERROR" /* mediaError */, message);
+  requireCamera() {
+    if (!this.camera) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera capture is not running");
+    return this.camera;
+  }
+  async run(operation) {
+    try {
+      return await operation();
+    } catch (error) {
+      throw this.mapError(error);
     }
-    return new XmaxError("RTC_ERROR" /* rtcError */, message);
+  }
+  mapError(error, permissionCode) {
+    if (error instanceof XmaxError) return error;
+    const value = error;
+    const code = typeof value?.code === "string" && /^[A-Z_0-9-]{1,64}$/.test(value.code) ? value.code : "UNKNOWN";
+    const denied = value?.name === "NotAllowedError" || code === "PERMISSION_DENIED" || code === "DEVICE_PERMISSION_DENIED";
+    return new XmaxError(permissionCode && denied ? permissionCode : "RTC_ERROR" /* rtcError */, `VeRTC operation failed (${code})`);
+  }
+  cancelled() {
+    return new XmaxError("CANCELLED" /* cancelled */, "VeRTC operation was cancelled");
   }
 };
 
+// src/Foundation/RTC/RtcFactory.ts
+function createRtcManager(provider, environment) {
+  switch (provider) {
+    case "agora" /* agora */:
+      return new AgoraRtcManager({ environment });
+    case "vertc" /* vertc */:
+      return new VeRtcManager();
+    default:
+      return new TrtcRtcManager();
+  }
+}
+
 // src/Foundation/Media/Camera/CameraFrameValidator.ts
 var CAMERA_WARMUP_MS = 200;
 function waitForValidCameraFrame(track, signal) {
@@ -2134,7 +3473,7 @@ var _CameraController = class _CameraController {
     __publicField(this, "storedUseMicrophone", false);
     __publicField(this, "storedFrameValidationEnabled", true);
     this.permissionManager = options?.permissionManager ?? new PermissionManager();
-    this.rtcManager = options?.rtcManager ?? new RtcManager();
+    this.rtcManager = options?.rtcManager ?? new TrtcRtcManager();
     this.mediaService = options?.mediaService ?? new MediaService();
     this.errorListener = options?.errorListener ?? (() => {
     });
@@ -2425,6 +3764,53 @@ var RealtimeSession = class {
   }
 };
 
+// src/Foundation/RTC/RoomJoinConfiguration.ts
+var RoomJoinConfiguration = class {
+  /**
+   * 创建房间加入参数。
+   *
+   * @param init.roomID TRTC 房间号。
+   * @param init.userID TRTC 登录身份。
+   * @param init.sdkAppID TRTC SDKAppID（字符串形式）。
+   * @param init.userSig TRTC 登录签名。
+   * @param init.privateMapKey TRTC 进房鉴权字段。
+   */
+  constructor(init) {
+    /**
+     * RTC 提供方。
+     */
+    __publicField(this, "provider", "trtc");
+    /**
+     * 进房参数
+     */
+    /**
+     * TRTC 房间号（字符串房间号）。
+     */
+    __publicField(this, "roomID");
+    /**
+     * TRTC 登录身份（`rtc_user_id`）。
+     */
+    __publicField(this, "userID");
+    /**
+     * TRTC SDKAppID（字符串形式，进房时转换为数值）。
+     */
+    __publicField(this, "sdkAppID");
+    /**
+     * TRTC 登录签名。
+     */
+    __publicField(this, "userSig");
+    /**
+     * TRTC 进房鉴权字段（字符串房间号对应的 privateMapKey）。
+     */
+    __publicField(this, "privateMapKey");
+    this.roomID = init.roomID;
+    this.userID = init.userID;
+    this.sdkAppID = init.sdkAppID;
+    this.userSig = init.userSig;
+    this.privateMapKey = init.privateMapKey;
+  }
+};
+
 // src/Service/Realtime/RealtimeSessionConnection.ts
 var RealtimeSessionConnection = class {
   /**
@@ -2443,7 +3829,7 @@ var RealtimeSessionConnection = class {
      * RTC 提供方
      */
     /**
-     * RTC 提供方标识（当前仅支持 `trtc`）。
+     * TRTC 凭据的提供方判别字段。
      */
     __publicField(this, "provider");
     /**
@@ -2485,6 +3871,12 @@ var RealtimeSessionConnection = class {
     this.botID = init.botID;
   }
 };
+function toRoomJoinConfiguration(connection) {
+  return connection.provider === "trtc" ? new RoomJoinConfiguration(connection) : connection;
+}
+function connectionAppID(connection) {
+  return connection.provider === "trtc" ? connection.sdkAppID : connection.appID;
+}
 
 // src/Service/Realtime/RealtimeSessionService.ts
 var RealtimeSessionService = class _RealtimeSessionService {
@@ -2500,6 +3892,7 @@ var RealtimeSessionService = class _RealtimeSessionService {
      * 服务层组件
      */
     __publicField(this, "apiService");
+    __publicField(this, "provider");
     /**
      * 心跳配置
      */
@@ -2509,7 +3902,16 @@ var RealtimeSessionService = class _RealtimeSessionService {
      * 运行状态
      */
     __publicField(this, "heartbeatVersion", 0);
+    /**
+     * 会话凭证缓存，支持心跳仅返回变更字段；关闭后清除。
+     */
+    __publicField(this, "credentials", /* @__PURE__ */ new Map());
+    __publicField(this, "refreshes", /* @__PURE__ */ new Map());
     this.apiService = options.apiService;
+    this.provider = options.provider ?? "trtc" /* trtc */;
+    if (!Object.values(RtcProvider).includes(this.provider)) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Unsupported RTC provider");
+    }
     this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? 1e4;
     this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
   }
@@ -2520,7 +3922,18 @@ var RealtimeSessionService = class _RealtimeSessionService {
     const payload = await this.apiService.post("/session", {
       model
     });
-    return _RealtimeSessionService.makeSession(payload, true);
+    try {
+      const session = this.makeSession(payload, true);
+      _RealtimeSessionService.ensureSessionActive(session);
+      const credentials = _RealtimeSessionService.decodeConnectionPayload(payload.modelExtra);
+      this.credentials.set(session.id, this.provider === "vertc" /* vertc */ ? { ...credentials, user_id: session.connection.userID } : credentials);
+      return session;
+    } catch (error) {
+      const sessionID = _RealtimeSessionService.nonEmpty(payload.sessionUid);
+      if (sessionID) await this.closeSession(sessionID).catch(() => {
+      });
+      throw error;
+    }
   }
   /**
    * 启动指定会话的周期心跳；重复启动会替换当前心跳。
@@ -2539,6 +3952,8 @@ var RealtimeSessionService = class _RealtimeSessionService {
    * 关闭指定实时会话；请求带 keepalive，页面卸载后仍能发出。
    */
   async closeSession(sessionID) {
+    this.credentials.delete(sessionID);
+    this.refreshes.delete(sessionID);
     try {
       await this.apiService.delete(
         `/session/${sessionID}`,
@@ -2563,7 +3978,7 @@ var RealtimeSessionService = class _RealtimeSessionService {
           return;
         }
         _RealtimeSessionService.ensureSessionActive(session);
-        handlers.onRefresh?.(session);
+        await handlers.onRefresh?.(session);
       } catch (error) {
         if (this.heartbeatVersion !== version) {
           return;
@@ -2577,11 +3992,35 @@ var RealtimeSessionService = class _RealtimeSessionService {
   /**
    * 发送一次心跳请求并解析会话数据（不要求携带完整连接参数）。
    */
-  async heartbeatSession(sessionID) {
+  heartbeatSession(sessionID) {
+    const pending = this.refreshes.get(sessionID);
+    if (pending) return pending;
+    const operation = this.performHeartbeat(sessionID);
+    this.refreshes.set(sessionID, operation);
+    void operation.finally(() => {
+      if (this.refreshes.get(sessionID) === operation) this.refreshes.delete(sessionID);
+    }).catch(() => {
+    });
+    return operation;
+  }
+  /**
+   * 合并心跳部分凭据；已关闭会话的迟到响应不重建缓存。
+   */
+  async performHeartbeat(sessionID) {
+    const previous = this.credentials.get(sessionID);
     const payload = await this.apiService.put(
       `/session/${sessionID}/heartbeat`
     );
-    return _RealtimeSessionService.makeSession(payload, false);
+    const incoming = _RealtimeSessionService.decodeConnectionPayload(payload.modelExtra);
+    if (payload.modelExtra != null && !incoming) {
+      throw new XmaxError("SESSION_ERROR" /* sessionError */, "Invalid heartbeat RTC credentials");
+    }
+    const merged = incoming ? { ...previous, ...incoming } : previous;
+    const session = this.makeSession({ ...payload, modelExtra: merged }, merged !== void 0);
+    if (session.id !== sessionID) throw new XmaxError("SESSION_ERROR" /* sessionError */, "Heartbeat session identity changed");
+    _RealtimeSessionService.ensureSessionActive(session);
+    if (previous && this.credentials.get(sessionID) === previous && merged) this.credentials.set(sessionID, merged);
+    return session;
   }
   /**
    * 校验会话仍处于活跃状态；状态明确非 ACTIVE 时抛出会话错误。
@@ -2598,12 +4037,12 @@ var RealtimeSessionService = class _RealtimeSessionService {
   /**
    * 由会话接口数据构造会话模型；`requiresConnection` 要求携带完整 RTC 连接参数。
    */
-  static makeSession(payload, requiresConnection) {
+  makeSession(payload, requiresConnection) {
     const sessionID = _RealtimeSessionService.nonEmpty(payload.sessionUid);
     if (!sessionID) {
       throw new XmaxError("SESSION_ERROR" /* sessionError */, "Invalid session response");
     }
-    const connection = _RealtimeSessionService.makeConnection(payload.modelExtra);
+    const connection = this.makeConnection(payload.modelExtra, payload.userUid);
     if (requiresConnection && !connection) {
       throw new XmaxError(
         "SESSION_ERROR" /* sessionError */,
@@ -2619,19 +4058,30 @@ var RealtimeSessionService = class _RealtimeSessionService {
     });
   }
   /**
-   * 解析 `modelExtra` 中的 TRTC 连接参数；字段不完整或提供方不支持时返回空。
+   * 解析 `modelExtra` 中的 RTC 连接参数；字段不完整或提供方不支持时返回空。
    */
-  static makeConnection(modelExtra) {
+  makeConnection(modelExtra, fallbackUserID) {
     const payload = _RealtimeSessionService.decodeConnectionPayload(modelExtra);
     if (!payload) {
       return void 0;
     }
-    if (_RealtimeSessionService.nonEmpty(payload.provider) !== "trtc") {
-      return void 0;
-    }
+    const provider = this.provider;
     const roomID = _RealtimeSessionService.nonEmpty(payload.room_id);
     const sdkAppID = _RealtimeSessionService.nonEmpty(payload.rtc_app_id);
-    const userID = _RealtimeSessionService.nonEmpty(payload.rtc_user_id);
+    const userID = provider === "vertc" /* vertc */ ? _RealtimeSessionService.nonEmpty(payload.user_id) ?? _RealtimeSessionService.nonEmpty(fallbackUserID) : _RealtimeSessionService.nonEmpty(payload.rtc_user_id);
+    if (!roomID || !sdkAppID || !userID) return void 0;
+    if (provider === "agora" /* agora */ || provider === "vertc" /* vertc */) {
+      const roomToken = _RealtimeSessionService.nonEmpty(payload.room_token);
+      if (!roomToken) return void 0;
+      return Object.freeze({
+        provider,
+        roomID,
+        appID: sdkAppID,
+        userID,
+        roomToken,
+        botID: _RealtimeSessionService.nonEmpty(provider === "vertc" /* vertc */ ? payload.bot_name : payload.rtc_bot_id)
+      });
+    }
     const userSig = _RealtimeSessionService.nonEmpty(payload.user_sig);
     const privateMapKey = _RealtimeSessionService.nonEmpty(
       payload.private_map_key_with_string_room_id
@@ -2655,12 +4105,12 @@ var RealtimeSessionService = class _RealtimeSessionService {
   static decodeConnectionPayload(modelExtra) {
     if (typeof modelExtra === "string") {
       try {
-        return JSON.parse(modelExtra);
+        return _RealtimeSessionService.decodeConnectionPayload(JSON.parse(modelExtra));
       } catch {
         return void 0;
       }
     }
-    if (typeof modelExtra === "object" && modelExtra !== null) {
+    if (typeof modelExtra === "object" && modelExtra !== null && !Array.isArray(modelExtra)) {
       return modelExtra;
     }
     return void 0;
@@ -2669,7 +4119,7 @@ var RealtimeSessionService = class _RealtimeSessionService {
    * 归一化可选字符串：去除首尾空白后为空时返回 `undefined`。
    */
   static nonEmpty(value) {
-    const normalized = value?.trim();
+    const normalized = typeof value === "string" ? value.trim() : void 0;
     return normalized || void 0;
   }
 };
@@ -2776,49 +4226,6 @@ var RemoteStream = class {
   }
 };
 
-// src/Foundation/RTC/RoomJoinConfiguration.ts
-var RoomJoinConfiguration = class {
-  /**
-   * 创建房间加入参数。
-   *
-   * @param init.roomID TRTC 房间号。
-   * @param init.userID TRTC 登录身份。
-   * @param init.sdkAppID TRTC SDKAppID（字符串形式）。
-   * @param init.userSig TRTC 登录签名。
-   * @param init.privateMapKey TRTC 进房鉴权字段。
-   */
-  constructor(init) {
-    /**
-     * 进房参数
-     */
-    /**
-     * TRTC 房间号（字符串房间号）。
-     */
-    __publicField(this, "roomID");
-    /**
-     * TRTC 登录身份（`rtc_user_id`）。
-     */
-    __publicField(this, "userID");
-    /**
-     * TRTC SDKAppID（字符串形式，进房时转换为数值）。
-     */
-    __publicField(this, "sdkAppID");
-    /**
-     * TRTC 登录签名。
-     */
-    __publicField(this, "userSig");
-    /**
-     * TRTC 进房鉴权字段（字符串房间号对应的 privateMapKey）。
-     */
-    __publicField(this, "privateMapKey");
-    this.roomID = init.roomID;
-    this.userID = init.userID;
-    this.sdkAppID = init.sdkAppID;
-    this.userSig = init.userSig;
-    this.privateMapKey = init.privateMapKey;
-  }
-};
-
 // src/Stream/Room/RoomEvent.ts
 var RoomEvent = class _RoomEvent {
   /**
@@ -2969,7 +4376,7 @@ var RoomHeartbeat = class {
         return;
       }
       try {
-        this.rtcManager.sendRoomMessage(RoomEvent.heartbeat({ userID }));
+        await this.rtcManager.sendRoomMessage(RoomEvent.heartbeat({ userID }));
       } catch (error) {
         if (this.cycleVersion !== version) {
           return;
@@ -2986,7 +4393,11 @@ var RoomHeartbeat = class {
 // src/Stream/Room/RoomMessageCodec.ts
 var CHUNK_EVENT = "__trtc_chunk__";
 var _RoomMessageCodec = class _RoomMessageCodec {
-  constructor() {
+  /**
+   * 创建厂商协议编解码器；TRTC 保持原事件名，Agora 使用 __agora_chunk__；null 表示不拆包。
+   */
+  constructor(chunkEvent = CHUNK_EVENT) {
+    __publicField(this, "chunkEvent", chunkEvent);
     /**
      * 接收缓存
      */
@@ -2996,10 +4407,10 @@ var _RoomMessageCodec = class _RoomMessageCodec {
    * 编码出站消息。
    *
    * @returns 不超过阈值时返回仅含原消息的单元素数组；
-   * 否则返回按 `__trtc_chunk__` 协议包装的分片 JSON 数组。
+   * 否则返回按当前提供方分片协议包装的 JSON 数组。
    */
   encodeOutgoing(message) {
-    if (_RoomMessageCodec.byteLength(message) <= _RoomMessageCodec.chunkThresholdBytes) {
+    if (this.chunkEvent === null || _RoomMessageCodec.byteLength(message) <= _RoomMessageCodec.chunkThresholdBytes) {
       return [message];
     }
     const eventId = _RoomMessageCodec.makeEventId();
@@ -3014,7 +4425,7 @@ var _RoomMessageCodec = class _RoomMessageCodec {
     );
     return slices.map(
       (data, index) => JSON.stringify({
-        event: CHUNK_EVENT,
+        event: this.chunkEvent,
         eventId,
         index,
         count,
@@ -3036,7 +4447,7 @@ var _RoomMessageCodec = class _RoomMessageCodec {
       XmaxLogger.room.warning(() => "\u623F\u95F4\u6D88\u606F\u4E0D\u662F\u5408\u6CD5 JSON (Room Message Is Not Valid JSON)");
       return void 0;
     }
-    const chunk = _RoomMessageCodec.parseChunk(parsed);
+    const chunk = this.parseChunk(parsed);
     if (!chunk) {
       return parsed;
     }
@@ -3080,12 +4491,12 @@ var _RoomMessageCodec = class _RoomMessageCodec {
   /**
    * 从已解析的值识别分片消息；字段不完整时按普通业务消息处理。
    */
-  static parseChunk(parsed) {
-    if (typeof parsed !== "object" || parsed === null) {
+  parseChunk(parsed) {
+    if (this.chunkEvent === null || typeof parsed !== "object" || parsed === null) {
       return void 0;
     }
     const record = parsed;
-    if (record.event !== CHUNK_EVENT || typeof record.eventId !== "string" || !Number.isInteger(record.index) || !Number.isInteger(record.count) || typeof record.data !== "string") {
+    if (record.event !== this.chunkEvent || typeof record.eventId !== "string" || record.eventId.length === 0 || !Number.isInteger(record.index) || !Number.isInteger(record.count) || typeof record.data !== "string") {
       return void 0;
     }
     const index = record.index;
@@ -3115,7 +4526,7 @@ var _RoomMessageCodec = class _RoomMessageCodec {
     let current = "";
     let currentBytes = 0;
     for (const char of message) {
-      const bytes = _RoomMessageCodec.byteLength(char);
+      const bytes = _RoomMessageCodec.byteLength(JSON.stringify(char)) - 2;
       if (currentBytes + bytes > budget && current.length > 0) {
         slices.push(current);
         current = "";
@@ -3184,6 +4595,8 @@ var RoomController = class {
      */
     __publicField(this, "heartbeat");
     __publicField(this, "codec");
+    __publicField(this, "customCodec");
+    __publicField(this, "sendTail", Promise.resolve());
     /**
      * 事件监听
      */
@@ -3196,6 +4609,7 @@ var RoomController = class {
     this.rtcManager = options.rtcManager;
     this.heartbeat = options.heartbeat ?? new RoomHeartbeat({ rtcManager: options.rtcManager });
     this.codec = options.codec ?? new RoomMessageCodec();
+    this.customCodec = options.codec !== void 0;
   }
   /**
    * 加入实时房间，并在异步边界前后确认连接操作仍然有效。
@@ -3218,15 +4632,10 @@ var RoomController = class {
     this.state = { kind: "joining", operationID };
     this.heartbeat.stop();
     try {
-      await this.rtcManager.joinRoom(
-        new RoomJoinConfiguration({
-          roomID: connection.roomID,
-          userID: connection.userID,
-          sdkAppID: connection.sdkAppID,
-          userSig: connection.userSig,
-          privateMapKey: connection.privateMapKey
-        })
+      if (!this.customCodec) this.codec = new RoomMessageCodec(
+        connection.provider === "vertc" ? null : connection.provider === "agora" ? "__agora_chunk__" : "__trtc_chunk__"
       );
+      await this.rtcManager.joinRoom(toRoomJoinConfiguration(connection));
       ensureActive();
       if (this.state.kind !== "joining" || this.state.operationID !== operationID || this.leaveOperation) {
         throw new XmaxError("CANCELLED" /* cancelled */, "RTC room join was cancelled");
@@ -3266,7 +4675,7 @@ var RoomController = class {
    * @throws 房间未就绪或信令发送失败时抛出错误。
    */
   startGeneration(options) {
-    this.send(
+    return this.send(
       RoomEvent.start({
         userID: this.requireUserID(),
         taskID: options.taskID,
@@ -3282,7 +4691,7 @@ var RoomController = class {
    * @throws 房间未就绪或信令发送失败时抛出错误。
    */
   changeGenerationCondition(options) {
-    this.send(
+    return this.send(
       RoomEvent.changeCondition({
         userID: this.requireUserID(),
         taskID: options.taskID,
@@ -3299,7 +4708,7 @@ var RoomController = class {
    */
   changeTargetSize(options) {
     options.ensureActive();
-    this.send(
+    return this.send(
       RoomEvent.changeTargetSize({
         userID: this.requireUserID(),
         taskID: options.taskID,
@@ -3312,18 +4721,18 @@ var RoomController = class {
    */
   stopGeneration(taskID) {
     if (!taskID || this.state.kind !== "joined") {
-      return;
+      return Promise.resolve();
     }
-    this.send(RoomEvent.stop({ userID: this.state.userID, taskID }));
+    return this.send(RoomEvent.stop({ userID: this.state.userID, taskID }));
   }
   /**
    * 发送生成任务的交互轨迹；任务标识或轨迹为空时忽略。
    */
   sendTracks(taskID, points) {
     if (!taskID || points.length === 0) {
-      return;
+      return Promise.resolve();
     }
-    this.send(
+    return this.send(
       RoomEvent.tracks({
         userID: this.requireUserID(),
         taskID,
@@ -3344,8 +4753,12 @@ var RoomController = class {
     this.state = { kind: "idle" };
     this.heartbeat.stop();
     this.codec.reset();
-    await this.rtcManager.leaveRoom();
-    this.leaveOperation = void 0;
+    this.sendTail = Promise.resolve();
+    try {
+      await this.rtcManager.leaveRoom();
+    } finally {
+      this.leaveOperation = void 0;
+    }
   }
   /**
    * 组包入站消息并按目标用户过滤后分发完整业务消息。
@@ -3367,18 +4780,26 @@ var RoomController = class {
    * 发送房间信令并输出日志。
    */
   send(message) {
-    for (const packet of this.codec.encodeOutgoing(message)) {
-      try {
-        this.rtcManager.sendRoomMessage(packet);
-      } catch (error) {
-        throw XmaxError.from(error);
+    const state2 = this.state;
+    const packets = this.codec.encodeOutgoing(message);
+    const operation = this.sendTail.then(async () => {
+      for (const packet of packets) {
+        if (state2 !== this.state || state2.kind !== "joined") {
+          throw new XmaxError("CANCELLED" /* cancelled */, "Room message was cancelled");
+        }
+        await this.rtcManager.sendRoomMessage(packet);
       }
-    }
-    XmaxLogger.room.info(
-      () => `\u53D1\u9001\u623F\u95F4\u4FE1\u4EE4 (Outbound Room Signaling)
+      XmaxLogger.room.info(
+        () => `\u53D1\u9001\u623F\u95F4\u4FE1\u4EE4 (Outbound Room Signaling)
 \u2514\u2500 ${XmaxLogger.localized("\u5185\u5BB9\uFF1A", "Content:")}
 ${JSON.stringify(JSON.parse(message), null, 2)}`
-    );
+      );
+    }).catch((error) => {
+      throw XmaxError.from(error);
+    });
+    this.sendTail = operation.catch(() => {
+    });
+    return operation;
   }
   /**
    * 返回当前房间中的用户标识；未进房时抛出错误。
@@ -3551,6 +4972,9 @@ function makeInitialState() {
     localVideoPublished: false,
     localAudioPublished: false,
     subscribedRemoteUserIDs: /* @__PURE__ */ new Set(),
+    publishedRemoteUserIDs: /* @__PURE__ */ new Set(),
+    remoteVideoTracks: /* @__PURE__ */ new Map(),
+    remoteVideoSubscriptions: /* @__PURE__ */ new Map(),
     subscribedRemoteAudioUserIDs: /* @__PURE__ */ new Set()
   };
 }
@@ -3604,6 +5028,10 @@ var StreamController = class {
     });
     this.generationTimeoutMs = options.generationTimeoutMs ?? 3e4;
     this.rtcManager.setEventListener({
+      onTokenWillExpire: options.onCredentialsRequired,
+      onTokenExpired: options.onCredentialsRequired,
+      onRoomRejoining: () => this.handleRoomRejoining(),
+      onError: (error) => this.errorListener(error),
       onNetworkStatistics: (statistics) => {
         if (this.state.localVideoPublished) {
           this.networkStatisticsListener?.(statistics);
@@ -3682,9 +5110,9 @@ var StreamController = class {
    * @throws 连接已取消，或 RTC 进房、房间配置与本地流发布失败时抛出错误。
    */
   async connect(connection, includeLocalAudio, ensureActive, beforePublish) {
+    this.configureRoom({ roomID: connection.roomID, botID: connection.botID });
     await this.roomController.join(connection, ensureActive);
     ensureActive();
-    this.configureRoom({ roomID: connection.roomID, botID: connection.botID });
     XmaxLogger.stream.info(
       () => `RTC \u623F\u95F4\u5DF2\u914D\u7F6E (RTC Room Configured)
 \u2514\u2500 roomID: ${connection.roomID}, botID: ${connection.botID ?? "(\u672A\u8BBE\u7F6E)"}`
@@ -3700,12 +5128,18 @@ var StreamController = class {
     await this.resetStream();
     await this.roomController.leave();
   }
+  /**
+   * 将会话刷新后的凭据应用到当前 RTC 连接。
+   */
+  async updateCredentials(connection, signal) {
+    await this.rtcManager.updateCredentials(toRoomJoinConfiguration(connection), signal);
+  }
   /**
    * 建立生成任务并发送开始信令。
    *
    * @returns 等待远端结果流确认的 Promise。
-   * @throws 任务标识无效、RTC 房间未就绪、已有生成任务，或开始信令
-   * 发送失败时同步抛出错误。
+   * @throws 任务标识无效、RTC 房间未就绪或已有生成任务时同步抛错；
+   * 发送失败或确认超时通过返回的 Promise 拒绝。
    */
   beginGeneration(options) {
     const taskID = options.taskID.trim();
@@ -3747,24 +5181,44 @@ var StreamController = class {
     };
     this.state.generationTaskID = taskID;
     this.state.generationWaiter = waiter;
+    void confirmation.catch(() => {
+    });
     try {
-      this.roomController.startGeneration({
+      const sending = this.roomController.startGeneration({
         taskID,
         videoFormat: options.videoFormat,
         targetSize: options.targetSize,
         context: options.context
       });
+      const state2 = this.state;
+      const sent = Promise.resolve(sending).then(() => {
+        if (this.state !== state2 || state2.generationTaskID !== taskID) return;
+        for (const userID of state2.publishedRemoteUserIDs) {
+          void this.handleRemoteVideoPublished(userID, true);
+        }
+      }).catch((error) => {
+        const mapped = XmaxError.from(error);
+        this.rejectGenerationStart(taskID, mapped);
+        if (this.state.generationTaskID === taskID) {
+          this.state.generationTaskID = void 0;
+          void this.roomController.stopGeneration(taskID).catch(() => {
+          });
+        }
+        throw mapped;
+      });
+      return Promise.all([sent, confirmation]).then(() => {
+      });
     } catch (error) {
       const mapped = XmaxError.from(error);
-      this.state.generationTaskID = void 0;
       this.rejectGenerationStart(taskID, mapped);
+      this.state.generationTaskID = void 0;
       try {
-        this.roomController.stopGeneration(taskID);
+        void this.roomController.stopGeneration(taskID).catch(() => {
+        });
       } catch {
       }
       throw mapped;
     }
-    return confirmation;
   }
   /**
    * 在远端首帧已经可显示后订阅当前生成流的音频。
@@ -3786,9 +5240,9 @@ var StreamController = class {
    *
    * @throws RTC 房间未就绪或条件变更信令发送失败时抛出错误。
    */
-  updateGeneration(options) {
+  async updateGeneration(options) {
     try {
-      this.roomController.changeGenerationCondition({
+      await this.roomController.changeGenerationCondition({
         taskID: options.taskID,
         videoFormat: options.videoFormat,
         targetSize: options.targetSize,
@@ -3803,9 +5257,9 @@ var StreamController = class {
    *
    * @throws 操作已取消、房间未就绪或信令发送失败时抛出错误。
    */
-  changeTargetSize(taskID, targetSize, ensureActive) {
+  async changeTargetSize(taskID, targetSize, ensureActive) {
     try {
-      this.roomController.changeTargetSize({ taskID, targetSize, ensureActive });
+      await this.roomController.changeTargetSize({ taskID, targetSize, ensureActive });
     } catch (error) {
       throw XmaxError.from(error);
     }
@@ -3821,7 +5275,7 @@ var StreamController = class {
       return;
     }
     try {
-      this.roomController.stopGeneration(stoppedTaskID);
+      await this.roomController.stopGeneration(stoppedTaskID);
     } catch (error) {
       throw XmaxError.from(error);
     }
@@ -3831,9 +5285,9 @@ var StreamController = class {
    *
    * @throws RTC 房间未就绪或轨迹信令发送失败时抛出错误。
    */
-  sendTracks(taskID, points) {
+  async sendTracks(taskID, points) {
     try {
-      this.roomController.sendTracks(taskID, points);
+      await this.roomController.sendTracks(taskID, points);
     } catch (error) {
       throw XmaxError.from(error);
     }
@@ -3908,6 +5362,12 @@ var StreamController = class {
     if (!this.state.roomID) {
       return;
     }
+    if (published) this.state.publishedRemoteUserIDs.add(trimmedUserID);
+    else {
+      this.state.publishedRemoteUserIDs.delete(trimmedUserID);
+      this.state.remoteVideoSubscriptions.delete(trimmedUserID);
+      this.state.remoteVideoTracks.delete(trimmedUserID);
+    }
     if (this.state.botID && this.state.botID !== trimmedUserID) {
       if (this.state.generationTaskID === void 0) {
         XmaxLogger.stream.warning(
@@ -3932,31 +5392,49 @@ var StreamController = class {
       this.clearRemoteStream();
     }
   }
+  /**
+   * RTC 重进房时废弃旧媒体绑定；业务任务、音频订阅意图和生成确认等待器继续保留。
+   */
+  handleRoomRejoining() {
+    this.state.publishedRemoteUserIDs.clear();
+    this.state.subscribedRemoteUserIDs.clear();
+    this.state.remoteVideoSubscriptions.clear();
+    this.state.remoteVideoTracks.clear();
+    this.state.activeRemoteStream = void 0;
+    this.clearRemoteStream();
+  }
   /**
    * 订阅远端视频并在成功后就绪或确认生成任务。
    */
   async subscribeRemoteVideo(userID) {
-    if (this.state.subscribedRemoteUserIDs.has(userID)) {
+    const state2 = this.state;
+    const existing = state2.remoteVideoTracks.get(userID);
+    if (existing) {
+      if (state2.generationWaiter) this.confirmOrUpdateRemoteStream(userID, existing);
       return;
     }
+    if (state2.remoteVideoSubscriptions.has(userID)) return;
+    const subscription = {};
+    state2.remoteVideoSubscriptions.set(userID, subscription);
+    const isCurrent = () => this.state === state2 && state2.remoteVideoSubscriptions.get(userID) === subscription;
     try {
       const track = await this.rtcManager.subscribeRemoteVideo(userID, true);
+      if (!isCurrent()) return;
       if (!track) {
         throw new XmaxError(
           "MEDIA_ERROR" /* mediaError */,
           "Remote video track is not available"
         );
       }
-      if (!this.state.roomID) {
-        return;
-      }
-      this.state.subscribedRemoteUserIDs.add(userID);
+      state2.subscribedRemoteUserIDs.add(userID);
+      state2.remoteVideoTracks.set(userID, track);
       XmaxLogger.stream.info(
         () => `\u8FDC\u7AEF\u89C6\u9891\u8BA2\u9605\u6210\u529F (Remote Video Subscribed)
 \u2514\u2500 userID: ${userID}`
       );
       this.confirmOrUpdateRemoteStream(userID, track);
     } catch (error) {
+      if (!isCurrent()) return;
       const mapped = XmaxError.from(error);
       const pendingTaskID = this.state.generationWaiter ? this.state.generationTaskID : void 0;
       if (pendingTaskID) {
@@ -3964,6 +5442,8 @@ var StreamController = class {
       } else {
         this.errorListener(mapped);
       }
+    } finally {
+      if (isCurrent()) state2.remoteVideoSubscriptions.delete(userID);
     }
   }
   /**
@@ -4680,6 +6160,10 @@ var XmaxRealtimeConnectionManager = class {
      * 会话资源
      */
     __publicField(this, "activeSession");
+    __publicField(this, "refreshVersion", 0);
+    __publicField(this, "credentialRefresh");
+    __publicField(this, "credentialApplication", Promise.resolve());
+    __publicField(this, "credentialController");
     /**
      * 远端轨道与渲染绑定
      */
@@ -4719,6 +6203,11 @@ var XmaxRealtimeConnectionManager = class {
         "Session does not contain RTC join information"
       );
     }
+    if (connection.provider !== (this.dependencies.provider ?? "trtc" /* trtc */)) {
+      throw new XmaxError("SESSION_ERROR" /* sessionError */, "RTC adapter configuration does not match the session service");
+    }
+    const refreshVersion = ++this.refreshVersion;
+    this.credentialController = new AbortController();
     const videoFormat = options.localTrack.videoFormat;
     if (!videoFormat) {
       throw new XmaxError(
@@ -4745,12 +6234,12 @@ var XmaxRealtimeConnectionManager = class {
         this.dependencies.onHeartbeatFailure(sessionID, error);
       },
       onRefresh: (refreshed) => {
-        this.handleSessionRefresh(refreshed);
+        return this.handleSessionRefresh(refreshed, refreshVersion);
       }
     });
     const remoteTrack = new RealtimeVideoTrack({
       id: connection.botID ?? "video-remote",
-      videoFormat: options.localTrack.videoFormat
+      videoFormat: options.remoteVideoFormat ?? options.localTrack.videoFormat
     });
     this.activeRemoteTrack = remoteTrack;
     this.registerRemoteBinding(remoteTrack);
@@ -4773,8 +6262,38 @@ var XmaxRealtimeConnectionManager = class {
    * 停止会话心跳；未配置会话服务时不执行操作。
    */
   stopHeartbeat() {
+    this.refreshVersion++;
+    this.credentialController?.abort();
+    this.credentialController = void 0;
+    this.credentialRefresh = void 0;
+    this.credentialApplication = Promise.resolve();
     this.dependencies.sessionService?.stopHeartbeat();
   }
+  /**
+   * RTC Token 过期时复用会话心跳获取新凭据，并合并同一实例的并发请求。
+   */
+  async refreshCredentials() {
+    if (this.credentialRefresh) return this.credentialRefresh;
+    const current = this.activeSession;
+    if (!current?.connection || current.connection.provider === "trtc") return;
+    const version = this.refreshVersion;
+    const operation = (async () => {
+      try {
+        const session = await this.requireSessionService().heartbeatSession(current.id);
+        await this.handleSessionRefresh(session, version, true);
+      } catch (error) {
+        if (version === this.refreshVersion && this.activeSession?.id === current.id) {
+          this.dependencies.onHeartbeatFailure(current.id, XmaxError.from(error));
+        }
+      }
+    })();
+    this.credentialRefresh = operation;
+    try {
+      await operation;
+    } finally {
+      if (this.credentialRefresh === operation) this.credentialRefresh = void 0;
+    }
+  }
   /**
    * 等待接收轨解除静音；超时只警告，取消必须立即退出并移除监听。
    */
@@ -4882,9 +6401,18 @@ var XmaxRealtimeConnectionManager = class {
    * 心跳成功后的凭据刷新：仅凭据变化时覆盖本地缓存；房间绑定信息
    * （提供方、房间、应用、登录身份）变化时当前连接失效，按失败结束。
    */
-  handleSessionRefresh(session) {
+  handleSessionRefresh(session, version, force = false) {
+    const operation = this.credentialApplication.then(() => this.applySessionRefresh(session, version, force));
+    this.credentialApplication = operation.catch(() => {
+    });
+    return operation;
+  }
+  /**
+   * 校验绑定并应用最新凭据，异步刷新期间失效的房间不得恢复缓存。
+   */
+  async applySessionRefresh(session, version, force) {
     const current = this.activeSession;
-    if (!current || current.id !== session.id) {
+    if (version !== this.refreshVersion || !current || current.id !== session.id) {
       return;
     }
     const next = session.connection;
@@ -4892,7 +6420,7 @@ var XmaxRealtimeConnectionManager = class {
       return;
     }
     const previous = current.connection;
-    const bindingChanged = previous !== void 0 && (next.provider !== previous.provider || next.roomID !== previous.roomID || next.sdkAppID !== previous.sdkAppID || next.userID !== previous.userID);
+    const bindingChanged = previous !== void 0 && (next.provider !== previous.provider || next.roomID !== previous.roomID || connectionAppID(next) !== connectionAppID(previous) || next.botID !== previous.botID || next.userID !== previous.userID);
     if (bindingChanged) {
       this.dependencies.onHeartbeatFailure(
         session.id,
@@ -4900,6 +6428,10 @@ var XmaxRealtimeConnectionManager = class {
       );
       return;
     }
+    if (next.provider !== "trtc" && (force || !previous || previous.provider === "trtc" || next.roomToken !== previous.roomToken)) {
+      await this.dependencies.streamController.updateCredentials(next, this.credentialController?.signal);
+      if (version !== this.refreshVersion || this.activeSession !== current) return;
+    }
     this.activeSession = new RealtimeSession({
       id: session.id,
       userID: session.userID ?? current.userID,
@@ -5012,16 +6544,17 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
   /**
    * 更新活动任务的生成条件；信令发送成功后才覆盖缓存，无任务或上下文时抛错。
    */
-  update(taskID, options) {
+  async update(taskID, options) {
     const context = options.context ?? this.currentContext;
     if (!taskID || !context) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "A realtime context is required to update the current generation");
     }
-    this.streamController.updateGeneration({
+    await this.streamController.updateGeneration({
       taskID,
       videoFormat: options.videoFormat,
       context
     });
+    if (this.activeTaskID !== taskID) throw RealtimeCoordinator.cancelledError();
     this.currentContext = context;
   }
   /**
@@ -5109,6 +6642,10 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
      */
     __publicField(this, "options");
     __publicField(this, "mediaService");
+    /**
+     * 本地流创建时的生成格式；上行编码调整不改变模型输入配置与远端插帧尺寸。
+     */
+    __publicField(this, "generationVideoFormat");
     /**
      * 插帧能力、用户配置与渲染版本
      */
@@ -5157,7 +6694,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     this.interpolationRequested = options.isFrameInterpolationEnabled;
     this.supportsInterpolation = dependencies?.supportsFrameInterpolation ?? (async (size) => await frameInterpolationAdapter(size) !== null);
     this.errorHandler = new RealtimeErrorHandler();
-    const rtcManager = dependencies?.rtcManager ?? new RtcManager();
+    const rtcManager = dependencies?.rtcManager ?? createRtcManager(options.provider, dependencies?.environment ?? "china" /* china */);
     this.cameraController = dependencies?.cameraController ?? new CameraController({
       rtcManager,
       mediaService: this.mediaService,
@@ -5165,9 +6702,12 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         void this.errorHandler.report(error);
       }
     });
-    const sessionService = dependencies?.sessionService ?? (dependencies?.apiService ? new RealtimeSessionService({ apiService: dependencies.apiService }) : void 0);
+    const sessionService = dependencies?.sessionService ?? (dependencies?.apiService ? new RealtimeSessionService({ apiService: dependencies.apiService, provider: options.provider }) : void 0);
     this.streamController = dependencies?.streamController ?? new StreamController({
       rtcManager,
+      onCredentialsRequired: () => {
+        void this.connectionManager.refreshCredentials();
+      },
       errorListener: (error) => {
         void this.errorHandler.report(error);
       },
@@ -5177,6 +6717,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       }
     });
     this.connectionManager = new XmaxRealtimeConnectionManager({
+      provider: options.provider,
       sessionService,
       streamController: this.streamController,
       timing: this.launchTimer,
@@ -5232,7 +6773,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   async setFrameInterpolationEnabled(enabled) {
     await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
-      const format = this.cameraController.currentTrack?.videoFormat;
+      const format = this.generationVideoFormat ?? this.cameraController.currentTrack?.videoFormat;
       const size = format && enabled ? this.mediaService.resolveFrameInterpolationSize(format) : void 0;
       if (enabled && !await this.checkInterpolationSupport(size, token)) {
         token.ensureCurrent();
@@ -5485,6 +7026,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
           throw error;
         }
         token.ensureCurrent();
+        this.generationVideoFormat = stream.videoTrack?.videoFormat;
         completeCamera();
         this.cameraController.setPreviewReadyHandler((isCurrent) => {
           void this.coordinator.localPreviewDidBecomeReady(isCurrent);
@@ -5500,6 +7042,26 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     this.permissionWatchDispose?.();
     this.permissionWatchDispose = void 0;
   }
+  /**
+   * 应用完整的上行视频格式，成功后更新本地轨道元数据，不改变生成格式或生命周期。
+   * 复用配置操作准入，避免与建连、切换摄像头或其他配置更新并发。
+   *
+   * @throws 无本地相机流、参数无效、操作冲突或底层编码更新失败时抛错。
+   */
+  async updateVideoFormat(videoFormat) {
+    await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
+      const track = this.cameraController.currentTrack;
+      const previousFormat = track?.videoFormat;
+      if (!track || !previousFormat) {
+        throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local camera stream is not started");
+      }
+      videoFormat.validate();
+      await this.streamController.setVideoEncoderConfig(videoFormat);
+      token.ensureCurrent();
+      this.generationVideoFormat ?? (this.generationVideoFormat = previousFormat);
+      track.updateVideoFormat(videoFormat);
+    });
+  }
   /**
    * 停止本地相机流并释放本地预览与 RTC 资源。
    */
@@ -5513,6 +7075,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         this.disposePermissionWatch();
         await this.cameraController.stopLocalCameraStream();
         token.ensureCurrent();
+        this.generationVideoFormat = void 0;
         await this.coordinator.commit(
           new RealtimeState({ connectionState: "Idle" /* idle */ }),
           token
@@ -5592,7 +7155,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
             "The local stream must be created and started by this realtime manager"
           );
         }
-        const videoFormat = localTrack.videoFormat;
+        const videoFormat = this.generationVideoFormat ?? localTrack.videoFormat;
         if (!videoFormat) {
           throw new XmaxError(
             "INVALID_CONFIGURATION" /* invalidConfiguration */,
@@ -5601,10 +7164,11 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         }
         const currentState = this.coordinator.currentState;
         if (currentState.connectionState === "Generating" /* generating */) {
-          this.generationManager.update(currentState.taskID, {
+          await this.generationManager.update(currentState.taskID, {
             videoFormat,
             context: options.context
           });
+          token.ensureCurrent();
           return this.connectionManager.makeRemoteStream();
         }
         const context = this.generationManager.validateContext(options.context);
@@ -5669,6 +7233,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       }
       const remote = await this.connectionManager.connect({
         localTrack,
+        remoteVideoFormat: this.generationVideoFormat,
         model: this.options.model,
         includeLocalAudio: this.cameraController.useMicrophone,
         ensureCurrent: () => token.ensureCurrent(),
@@ -5744,6 +7309,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     await this.generationManager.reset(taskID);
     const sessionID = await this.connectionManager.disconnect();
     if (scope === 1 /* all */) {
+      this.generationVideoFormat = void 0;
       this.disposePermissionWatch();
       try {
         await this.cameraController.stopLocalCameraStream();
@@ -5850,12 +7416,18 @@ var XmaxClient = class {
   }
   /**
    * 创建实时媒体 Manager。
+   * 模型专用地址优先于环境默认地址，并用于该 Manager 的整个会话生命周期。
    *
    * @param options 实时生成模型等业务配置。
    * @returns 可用于本地相机预览、实时连接与生成的实时 Manager。
    */
   createRealtimeManager(options) {
-    return new XmaxRealtimeManager(options, { apiService: this.apiService });
+    const baseURL = modelBaseURL(options.model);
+    const apiService = baseURL ? new ApiService({ apiKey: this.configuration.apiKey, baseURL }) : this.apiService;
+    return new XmaxRealtimeManager(options, {
+      apiService,
+      environment: this.configuration.environment
+    });
   }
   /**
    * 创建媒体处理与能力查询 Service。
@@ -5881,10 +7453,15 @@ var RealtimeConfiguration = class {
    * 创建实时业务配置。
    *
    * @param init.model 实时生成业务使用的模型。
+   * @param init.provider RTC 提供方，默认 TRTC；创建后不可切换。
    * @param init.isFrameInterpolationEnabled 是否默认开启远端生成画面的插帧。
    * @param init.frameInterpolation 插帧开关和显示帧率上限的详细配置。
    */
   constructor(init) {
+    /**
+     * RTC 配置
+     */
+    __publicField(this, "provider");
     /**
      * 模型配置
      */
@@ -5903,6 +7480,10 @@ var RealtimeConfiguration = class {
      * 已补全默认值的只读插帧配置。
      */
     __publicField(this, "frameInterpolation");
+    this.provider = init.provider ?? "trtc" /* trtc */;
+    if (!Object.values(RtcProvider).includes(this.provider)) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Unsupported RTC provider");
+    }
     this.model = init.model;
     const targetFrameRate = init.frameInterpolation?.targetFrameRate ?? 60;
     if (!Number.isFinite(targetFrameRate) || targetFrameRate < 1 || targetFrameRate > 60) {
@@ -8750,6 +10331,7 @@ export {
   StoredFile,
   StorageService,
   CameraPosition,
+  RtcProvider,
   RealtimeVideoTrack,
   RealtimeMediaStream,
   RealtimeConnectionState,
@@ -8763,4 +10345,4 @@ export {
   XmaxVideoView,
   XmaxRealtimeVideoView
 };
-//# sourceMappingURL=chunk-YMLRUDAO.js.map
+//# sourceMappingURL=chunk-FMAQXPTE.js.map