@xmaxai/web-sdk 1.0.5 → 1.0.7

package/dist/{chunk-JN6HURTT.cjs → chunk-EKOYOFES.cjs}

@@ -205,7 +205,7 @@ var XmaxError = class _XmaxError extends Error {
 };
 
 // src/Foundation/Runtime/RuntimeInfo.ts
-var XMAX_SDK_VERSION = "1.0.5";
+var XMAX_SDK_VERSION = "1.0.7";
 var _RuntimeInfo = class _RuntimeInfo {
   /**
    * 序列化为接口传输使用的 snake_case 字段。
@@ -600,7 +600,6 @@ var RtcProvider = /* @__PURE__ */ ((RtcProvider2) => {
 var RealtimeModel = /* @__PURE__ */ ((RealtimeModel2) => {
   RealtimeModel2["x2_0"] = "x2.0";
   RealtimeModel2["x2_0_trtc"] = "x2.0-trtc";
-  RealtimeModel2["x2_0_agora"] = "x2.0-agora";
   RealtimeModel2["x2_1_preview"] = "x2.1-preview";
   return RealtimeModel2;
 })(RealtimeModel || {});
@@ -616,12 +615,10 @@ function modelDefaults(model) {
 var MODEL_DISPLAY_NAMES = {
   ["x2.0" /* x2_0 */]: "X2.0",
   ["x2.0-trtc" /* x2_0_trtc */]: "X2.1-preview-trtc",
-  ["x2.0-agora" /* x2_0_agora */]: "X2.1-preview-agora",
-  ["x2.1-preview" /* x2_1_preview */]: "X2.1-preview-vertc"
+  ["x2.1-preview" /* x2_1_preview */]: "X2.1-preview-agora"
 };
 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"
+  ["x2.1-preview" /* x2_1_preview */]: "https://cloud.xmax.22duck.cn/open/api/v1"
 };
 var RESOLUTION_BUCKETS = {
   ["x2.0" /* x2_0 */]: [],
@@ -629,10 +626,6 @@ var RESOLUTION_BUCKETS = {
     { width: 1024, height: 1920 },
     { width: 1920, height: 1024 }
   ],
-  ["x2.0-agora" /* x2_0_agora */]: [
-    { width: 1024, height: 1920 },
-    { width: 1920, height: 1024 }
-  ],
   ["x2.1-preview" /* x2_1_preview */]: [
     { width: 1024, height: 1920 },
     { width: 1920, height: 1024 }
@@ -641,7 +634,6 @@ var RESOLUTION_BUCKETS = {
 var MAXIMUM_INPUT_PIXELS = {
   ["x2.0" /* x2_0 */]: 128e4,
   ["x2.0-trtc" /* x2_0_trtc */]: 21e5,
-  ["x2.0-agora" /* x2_0_agora */]: 21e5,
   ["x2.1-preview" /* x2_1_preview */]: 21e5
 };
 function modelDisplayName(model) {
@@ -674,8 +666,7 @@ function defaultCameraVideoFormat(model) {
 var MODEL_RTC_PROVIDERS = {
   ["x2.0" /* x2_0 */]: Object.freeze(["vertc" /* vertc */]),
   ["x2.0-trtc" /* x2_0_trtc */]: Object.freeze(["trtc" /* trtc */]),
-  ["x2.0-agora" /* x2_0_agora */]: Object.freeze(["agora" /* agora */]),
-  ["x2.1-preview" /* x2_1_preview */]: Object.freeze(["vertc" /* vertc */])
+  ["x2.1-preview" /* x2_1_preview */]: Object.freeze(["agora" /* agora */])
 };
 function supportedRtcProviders(model) {
   return isKnownModel(model) ? MODEL_RTC_PROVIDERS[model] : CUSTOM_MODEL_RTC_PROVIDERS;
@@ -1269,6 +1260,11 @@ ${JSON.stringify({
       receivedBytes: valid(rtc.RecvBytes),
       localVideo,
       remoteVideo: remote,
+      capture: {
+        width: valid(local.captureResolutionWidth, 1),
+        height: valid(local.captureResolutionHeight, 1),
+        frameRate: valid(local.captureFrameRate)
+      },
       localAudio: client.getLocalAudioStats(),
       remoteAudio: client.getRemoteAudioStats()
     }, null, 2)}`, 2 /* performance */);
@@ -1316,6 +1312,231 @@ function rtcOrientedVideoSize(size, environment) {
   return shouldTransposeRtcVideoSize(environment) ? { width: size.height, height: size.width } : size;
 }
 
+// src/Foundation/RTC/Agora/AgoraVideoSender.ts
+var AgoraVideoSender = class {
+  static async apply(track, config, ensureActive2) {
+    ensureActive2();
+    const sender = _optionalChain([track, 'access', _72 => _72.getRTCRtpTransceiver, 'call', _73 => _73(), 'optionalAccess', _74 => _74.sender]);
+    if (!sender) throw new XmaxError("RTC_ERROR" /* rtcError */, "WebRTC video sender is unavailable");
+    const capture = _optionalChain([sender, 'access', _75 => _75.track, 'optionalAccess', _76 => _76.getSettings, 'call', _77 => _77()]);
+    if (!_optionalChain([capture, 'optionalAccess', _78 => _78.width]) || !capture.height) {
+      throw new XmaxError("RTC_ERROR" /* rtcError */, "WebRTC capture dimensions are unavailable");
+    }
+    const scale = Math.max(1, capture.width / config.width, capture.height / config.height);
+    const parameters = sender.getParameters();
+    if (_optionalChain([parameters, 'access', _79 => _79.encodings, 'optionalAccess', _80 => _80.length]) !== 1) {
+      throw new XmaxError("RTC_ERROR" /* rtcError */, "Sender-only configuration requires one video encoding");
+    }
+    const encoding = parameters.encodings[0];
+    const previous = { ...encoding };
+    const previousPreference = parameters.degradationPreference;
+    encoding.scaleResolutionDownBy = scale;
+    encoding.maxFramerate = config.frameRate;
+    encoding.maxBitrate = Math.round(config.maximumBitrate * 1e3);
+    parameters.degradationPreference = config.encoderPreference === "maintainFramerate" /* maintainFramerate */ ? "maintain-framerate" : "maintain-resolution";
+    await sender.setParameters(parameters);
+    ensureActive2();
+    if (_optionalChain([track, 'access', _81 => _81.getRTCRtpTransceiver, 'call', _82 => _82(), 'optionalAccess', _83 => _83.sender]) !== sender) {
+      throw new XmaxError("CANCELLED" /* cancelled */, "WebRTC video sender changed during configuration");
+    }
+    const applied = sender.getParameters();
+    const actual = _optionalChain([applied, 'access', _84 => _84.encodings, 'optionalAccess', _85 => _85[0]]);
+    if (!actual || Math.abs((_nullishCoalesce(actual.scaleResolutionDownBy, () => ( 1))) - scale) > 1e-4 || actual.maxFramerate !== encoding.maxFramerate || actual.maxBitrate !== encoding.maxBitrate) {
+      if (actual && applied.encodings.length === 1) {
+        for (const key of ["scaleResolutionDownBy", "maxFramerate", "maxBitrate"]) {
+          if (previous[key] === void 0) delete actual[key];
+          else actual[key] = previous[key];
+        }
+        if (previousPreference === void 0) delete applied.degradationPreference;
+        else applied.degradationPreference = previousPreference;
+        await sender.setParameters(applied);
+      }
+      throw new XmaxError("RTC_ERROR" /* rtcError */, "Browser did not retain WebRTC video sender parameters");
+    }
+    XmaxLogger.rtc.info(() => `Agora \u53D1\u9001\u53C2\u6570\u5B9E\u9A8C (Agora Sender Parameters)
+${JSON.stringify({
+      capture: { width: capture.width, height: capture.height, frameRate: capture.frameRate },
+      target: { width: config.width, height: config.height, frameRate: config.frameRate },
+      scaleResolutionDownBy: actual.scaleResolutionDownBy,
+      maxFramerate: actual.maxFramerate,
+      maxBitrateKbps: actual.maxBitrate / 1e3,
+      minimumBitrateApplied: false
+    }, null, 2)}`, 2 /* performance */);
+  }
+};
+
+// src/Foundation/Media/Camera/CameraRotation.ts
+function validateCameraRotation(rotation) {
+  if (![0, 90, 180, 270].includes(rotation)) {
+    throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera rotation must be 0, 90, 180 or 270");
+  }
+}
+
+// src/Foundation/Media/Camera/CameraRotationProcessor.ts
+var CameraRotationProcessor = class {
+  constructor(options) {
+    __publicField(this, "options", options);
+    __publicField(this, "video", document.createElement("video"));
+    __publicField(this, "canvas", document.createElement("canvas"));
+    __publicField(this, "context");
+    __publicField(this, "stream");
+    __publicField(this, "source");
+    __publicField(this, "frameCallback");
+    __publicField(this, "timer");
+    __publicField(this, "cancelPending");
+    __publicField(this, "stopped", false);
+    __publicField(this, "version", 0);
+    __publicField(this, "sourceEnded", () => {
+      this.fail(new XmaxError("MEDIA_ERROR" /* mediaError */, "Camera source ended during rotation"));
+    });
+    this.canvas.width = options.width;
+    this.canvas.height = options.height;
+    const context = this.canvas.getContext("2d", { alpha: false });
+    if (!context || typeof this.canvas.captureStream !== "function") {
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Canvas camera rotation is not supported by this browser");
+    }
+    this.context = context;
+    this.video.muted = true;
+    this.video.autoplay = true;
+    this.video.playsInline = true;
+  }
+  /** 等待第一帧实际绘制成功；换摄像头时复用输出轨，不重建 sender。 */
+  async setSource(source) {
+    if (this.stopped) throw new XmaxError("CANCELLED" /* cancelled */, "Camera rotation has stopped");
+    if (source.readyState === "ended") {
+      this.stop();
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Camera rotation requires a live source");
+    }
+    _optionalChain([this, 'access', _86 => _86.cancelPending, 'optionalCall', _87 => _87()]);
+    this.cancelFrame();
+    _optionalChain([this, 'access', _88 => _88.source, 'optionalAccess', _89 => _89.removeEventListener, 'call', _90 => _90("ended", this.sourceEnded)]);
+    const version = ++this.version;
+    this.source = source;
+    source.addEventListener("ended", this.sourceEnded);
+    this.video.srcObject = new MediaStream([source]);
+    try {
+      await new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeout);
+          this.cancelPending = void 0;
+          if (error) reject(error);
+          else resolve();
+        };
+        const timeout = setTimeout(() => finish(new XmaxError("TIMEOUT" /* timeout */, "Timed out waiting for a camera rotation frame")), 1e4);
+        this.cancelPending = () => finish(new XmaxError("CANCELLED" /* cancelled */, "Camera rotation source changed"));
+        void this.video.play().then(() => {
+          if (settled || this.stopped || version !== this.version) return;
+          const firstFrame = () => {
+            if (settled || this.stopped || version !== this.version) return;
+            try {
+              if (!this.draw()) {
+                this.schedule(firstFrame);
+                return;
+              }
+              _nullishCoalesce(this.stream, () => ( (this.stream = this.canvas.captureStream(this.options.frameRate))));
+              if (!this.stream.getVideoTracks()[0]) throw new Error("Canvas did not produce a video track");
+              this.requestFrame();
+              finish();
+              this.schedule(() => this.render(version));
+            } catch (error) {
+              finish(error);
+            }
+          };
+          this.schedule(firstFrame);
+        }, finish);
+      });
+      if (this.stopped || version !== this.version) {
+        throw new XmaxError("CANCELLED" /* cancelled */, "Camera rotation source changed");
+      }
+      return this.stream.getVideoTracks()[0];
+    } catch (error) {
+      if (version === this.version) this.stop();
+      throw XmaxError.from(error);
+    }
+  }
+  /** 换设备前解除旧原始轨监听，保留 Canvas 最后一帧及输出轨。 */
+  pauseSource() {
+    ++this.version;
+    _optionalChain([this, 'access', _91 => _91.cancelPending, 'optionalCall', _92 => _92()]);
+    this.cancelFrame();
+    _optionalChain([this, 'access', _93 => _93.source, 'optionalAccess', _94 => _94.removeEventListener, 'call', _95 => _95("ended", this.sourceEnded)]);
+    this.source = void 0;
+    this.video.pause();
+    this.video.srcObject = null;
+  }
+  stop() {
+    if (this.stopped) return;
+    this.stopped = true;
+    ++this.version;
+    _optionalChain([this, 'access', _96 => _96.cancelPending, 'optionalCall', _97 => _97()]);
+    this.cancelFrame();
+    _optionalChain([this, 'access', _98 => _98.source, 'optionalAccess', _99 => _99.removeEventListener, 'call', _100 => _100("ended", this.sourceEnded)]);
+    this.source = void 0;
+    this.video.pause();
+    this.video.srcObject = null;
+    _optionalChain([this, 'access', _101 => _101.stream, 'optionalAccess', _102 => _102.getTracks, 'call', _103 => _103(), 'access', _104 => _104.forEach, 'call', _105 => _105((track) => track.stop())]);
+    this.stream = void 0;
+    this.canvas.width = this.canvas.height = 0;
+  }
+  draw() {
+    const { videoWidth: width, videoHeight: height } = this.video;
+    if (this.video.readyState < 2 || !width || !height) return false;
+    const { width: outWidth, height: outHeight, rotation } = this.options;
+    const quarterTurn = rotation === 90 || rotation === 270;
+    const targetWidth = quarterTurn ? outHeight : outWidth;
+    const targetHeight = quarterTurn ? outWidth : outHeight;
+    const scale = Math.max(targetWidth / width, targetHeight / height);
+    const cropWidth = targetWidth / scale, cropHeight = targetHeight / scale;
+    this.context.setTransform(1, 0, 0, 1, outWidth / 2, outHeight / 2);
+    this.context.rotate(rotation * Math.PI / 180);
+    this.context.drawImage(
+      this.video,
+      (width - cropWidth) / 2,
+      (height - cropHeight) / 2,
+      cropWidth,
+      cropHeight,
+      -targetWidth / 2,
+      -targetHeight / 2,
+      targetWidth,
+      targetHeight
+    );
+    return true;
+  }
+  render(version) {
+    if (this.stopped || version !== this.version) return;
+    try {
+      if (this.draw()) this.requestFrame();
+      this.schedule(() => this.render(version));
+    } catch (error) {
+      this.fail(XmaxError.from(error));
+    }
+  }
+  requestFrame() {
+    const track = _optionalChain([this, 'access', _106 => _106.stream, 'optionalAccess', _107 => _107.getVideoTracks, 'call', _108 => _108(), 'access', _109 => _109[0]]);
+    _optionalChain([track, 'optionalAccess', _110 => _110.requestFrame, 'optionalCall', _111 => _111()]);
+  }
+  schedule(callback) {
+    if (typeof this.video.requestVideoFrameCallback === "function") {
+      this.frameCallback = this.video.requestVideoFrameCallback(callback);
+    } else {
+      this.timer = setTimeout(callback, 1e3 / this.options.frameRate);
+    }
+  }
+  cancelFrame() {
+    if (this.frameCallback !== void 0) this.video.cancelVideoFrameCallback(this.frameCallback);
+    clearTimeout(this.timer);
+    this.frameCallback = void 0;
+    this.timer = void 0;
+  }
+  fail(error) {
+    this.stop();
+    this.options.onError(error);
+  }
+};
+
 // src/Foundation/RTC/Agora/AgoraRtcManager.ts
 var _AgoraRtcManager = class _AgoraRtcManager {
   /**
@@ -1332,9 +1553,16 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     __publicField(this, "initialization");
     __publicField(this, "lifecycle", 0);
     __publicField(this, "camera");
+    __publicField(this, "cameraSource");
+    __publicField(this, "cameraRotation");
+    __publicField(this, "captureVersion", 0);
     __publicField(this, "microphone");
     __publicField(this, "externalVideo");
     __publicField(this, "externalAudio");
+    __publicField(this, "appliedOptimizationModes", /* @__PURE__ */ new WeakMap());
+    __publicField(this, "cameraSenderConfiguration");
+    __publicField(this, "senderUpdateTail", Promise.resolve());
+    __publicField(this, "cameraTransceiverListener");
     __publicField(this, "connection");
     __publicField(this, "roomVersion", 0);
     /**
@@ -1351,6 +1579,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
      */
     __publicField(this, "listener");
     __publicField(this, "statisticsTimer");
+    __publicField(this, "networkQualitySuspended", false);
     __publicField(this, "audioVolumes", /* @__PURE__ */ new Map());
     __publicField(this, "requestedAudio", /* @__PURE__ */ new Set());
     /**
@@ -1406,7 +1635,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     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: (_nullishCoalesce(_optionalChain([region, 'optionalAccess', _72 => _72.count]), () => ( 0))) + 1 });
+    _AgoraRtcManager.regions.set(sdk, { environment: this.environment, count: (_nullishCoalesce(_optionalChain([region, 'optionalAccess', _112 => _112.count]), () => ( 0))) + 1 });
     this.sdk = sdk;
     this.client = client;
     this.registerEvents(client);
@@ -1419,11 +1648,11 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     const client = this.client;
     this.clearRoom();
     this.client = void 0;
-    _optionalChain([client, 'optionalAccess', _73 => _73.removeAllListeners, 'call', _74 => _74()]);
-    _optionalChain([this, 'access', _75 => _75.camera, 'optionalAccess', _76 => _76.close, 'call', _77 => _77()]);
-    _optionalChain([this, 'access', _78 => _78.microphone, 'optionalAccess', _79 => _79.close, 'call', _80 => _80()]);
-    _optionalChain([this, 'access', _81 => _81.externalVideo, 'optionalAccess', _82 => _82.close, 'call', _83 => _83()]);
-    _optionalChain([this, 'access', _84 => _84.externalAudio, 'optionalAccess', _85 => _85.close, 'call', _86 => _86()]);
+    _optionalChain([client, 'optionalAccess', _113 => _113.removeAllListeners, 'call', _114 => _114()]);
+    this.releaseCameraCapture();
+    _optionalChain([this, 'access', _115 => _115.microphone, 'optionalAccess', _116 => _116.close, 'call', _117 => _117()]);
+    _optionalChain([this, 'access', _118 => _118.externalVideo, 'optionalAccess', _119 => _119.close, 'call', _120 => _120()]);
+    _optionalChain([this, 'access', _121 => _121.externalAudio, 'optionalAccess', _122 => _122.close, 'call', _123 => _123()]);
     this.externalVideo = void 0;
     this.externalAudio = void 0;
     this.camera = void 0;
@@ -1431,7 +1660,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     const sdk = this.sdk;
     this.sdk = void 0;
     try {
-      await _optionalChain([client, 'optionalAccess', _87 => _87.leave, 'call', _88 => _88()]);
+      await _optionalChain([client, 'optionalAccess', _124 => _124.leave, 'call', _125 => _125()]);
     } catch (e9) {
       XmaxLogger.rtc.warning(() => "Agora \u9000\u623F\u5931\u8D25\uFF0C\u5DF2\u91CA\u653E\u672C\u5730\u8D44\u6E90 (Agora Leave Failed)");
     } finally {
@@ -1444,22 +1673,55 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    */
   async startCameraCapture(options) {
     const client = this.requireClient();
-    if (this.camera || this.externalVideo) {
+    if (this.camera || this.cameraSource || this.externalVideo) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "A local video source is already active");
     }
+    const rotation = _nullishCoalesce(options.rotation, () => ( 0));
+    validateCameraRotation(rotation);
+    const version = ++this.captureVersion;
+    let source;
     try {
-      const captureSize = rtcOrientedVideoSize(options);
-      const camera = await this.sdk.createCameraVideoTrack({
+      const captureSize = rtcOrientedVideoSize(rotation === 90 || rotation === 270 ? { width: options.height, height: options.width } : options);
+      source = 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();
+      if (this.client !== client || version !== this.captureVersion) {
+        source.close();
         throw this.cancelled();
       }
+      this.cameraSource = source;
+      let camera = source;
+      if (rotation !== 0) {
+        const processor = new CameraRotationProcessor({
+          ...options,
+          rotation,
+          onError: (error) => _optionalChain([this, 'access', _126 => _126.listener, 'optionalAccess', _127 => _127.onError, 'optionalCall', _128 => _128(error)])
+        });
+        this.cameraRotation = processor;
+        const output = await processor.setSource(source.getMediaStreamTrack());
+        if (this.client !== client || version !== this.captureVersion) throw this.cancelled();
+        camera = this.sdk.createCustomVideoTrack({
+          mediaStreamTrack: output,
+          width: options.width,
+          height: options.height,
+          frameRate: options.frameRate
+        });
+      }
       this.camera = camera;
+      this.cameraTransceiverListener = () => {
+        if (this.client === client && client.localTracks.includes(camera) && this.videoPublishRequested && !this.rejoinTask) {
+          void this.restoreCameraSender(camera).catch(() => {
+            if (this.camera === camera && this.videoPublishRequested) {
+              XmaxLogger.rtc.warning(() => "Agora \u53D1\u9001\u53C2\u6570\u6062\u590D\u5931\u8D25 (Agora Sender Parameters Restore Failed)");
+            }
+          });
+        }
+      };
+      camera.on("transceiver-updated", this.cameraTransceiverListener);
       return camera.getMediaStreamTrack();
     } catch (error) {
+      if (version === this.captureVersion) this.releaseCameraCapture();
       throw this.mapError(error, "CAMERA_PERMISSION_DENIED" /* cameraPermissionDenied */);
     }
   }
@@ -1467,25 +1729,50 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    * 切换声网相机设备并返回切换后的原生轨道。
    */
   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();
+    const source = this.requireCamera();
+    const camera = this.camera;
+    _optionalChain([this, 'access', _129 => _129.cameraRotation, 'optionalAccess', _130 => _130.pauseSource, 'call', _131 => _131()]);
+    try {
+      await this.run(() => source.setDevice({ facingMode: to === "front" /* front */ ? "user" : "environment" }));
+    } catch (error) {
+      if (this.camera === camera && this.cameraRotation) {
+        await this.cameraRotation.setSource(source.getMediaStreamTrack()).catch((restoreError) => {
+          _optionalChain([this, 'access', _132 => _132.listener, 'optionalAccess', _133 => _133.onError, 'optionalCall', _134 => _134(XmaxError.from(restoreError))]);
+        });
+      }
+      throw error;
+    }
+    if (this.camera !== camera || this.cameraSource !== source) throw this.cancelled();
+    if (this.cameraRotation) {
+      await this.cameraRotation.setSource(source.getMediaStreamTrack());
+      if (this.camera !== camera) throw this.cancelled();
+    }
+    if (this.videoPublishRequested) await this.restoreCameraSender(camera);
     return camera.getMediaStreamTrack();
   }
   /**
    * 停止采集并释放摄像头。
    */
   async stopCameraCapture() {
+    this.releaseCameraCapture();
+  }
+  releaseCameraCapture() {
+    ++this.captureVersion;
     const camera = this.camera;
+    this.releaseCameraSender();
     this.camera = void 0;
-    _optionalChain([camera, 'optionalAccess', _89 => _89.close, 'call', _90 => _90()]);
+    _optionalChain([camera, 'optionalAccess', _135 => _135.close, 'call', _136 => _136()]);
+    _optionalChain([this, 'access', _137 => _137.cameraRotation, 'optionalAccess', _138 => _138.stop, 'call', _139 => _139()]);
+    this.cameraRotation = void 0;
+    if (this.cameraSource !== camera) _optionalChain([this, 'access', _140 => _140.cameraSource, 'optionalAccess', _141 => _141.close, 'call', _142 => _142()]);
+    this.cameraSource = void 0;
   }
   /**
    * 将外部原生轨包装为 Agora 本地轨，不申请设备权限；失败时释放本次克隆。
    */
   async setExternalMediaTracks(tracks) {
     this.requireClient();
-    if (this.camera || this.microphone || this.externalVideo) {
+    if (this.camera || this.cameraSource || this.microphone || this.externalVideo) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Release the current local media before attaching external tracks");
     }
     if (tracks.videoTrack.kind !== "video" || tracks.videoTrack.readyState !== "live" || tracks.audioTrack && (tracks.audioTrack.kind !== "audio" || tracks.audioTrack.readyState !== "live")) {
@@ -1496,7 +1783,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     let wrappedVideo;
     let wrappedAudio;
     try {
-      audio = _optionalChain([tracks, 'access', _91 => _91.audioTrack, 'optionalAccess', _92 => _92.clone, 'call', _93 => _93()]);
+      audio = _optionalChain([tracks, 'access', _143 => _143.audioTrack, 'optionalAccess', _144 => _144.clone, 'call', _145 => _145()]);
       wrappedVideo = this.sdk.createCustomVideoTrack({ mediaStreamTrack: video });
       if (audio) {
         wrappedAudio = this.sdk.createCustomAudioTrack({ mediaStreamTrack: audio, encoderConfig: "music_standard" });
@@ -1504,19 +1791,34 @@ var _AgoraRtcManager = class _AgoraRtcManager {
       this.externalVideo = wrappedVideo;
       this.externalAudio = wrappedAudio;
     } catch (error) {
-      _optionalChain([wrappedVideo, 'optionalAccess', _94 => _94.close, 'call', _95 => _95()]);
-      _optionalChain([wrappedAudio, 'optionalAccess', _96 => _96.close, 'call', _97 => _97()]);
+      _optionalChain([wrappedVideo, 'optionalAccess', _146 => _146.close, 'call', _147 => _147()]);
+      _optionalChain([wrappedAudio, 'optionalAccess', _148 => _148.close, 'call', _149 => _149()]);
       video.stop();
-      _optionalChain([audio, 'optionalAccess', _98 => _98.stop, 'call', _99 => _99()]);
+      _optionalChain([audio, 'optionalAccess', _150 => _150.stop, 'call', _151 => _151()]);
       throw this.mapError(error);
     }
   }
   /**
-   * 应用公共编码配置；仅相机源补偿移动端转置，Canvas 外部源使用原始方向。
+   * 摄像头实验走原生 sender（发布前暂存）；外部视频仍走 Agora 编码配置。
    */
   async configureVideoEncoding(config) {
     const camera = this.requireLocalVideo();
-    const encodingSize = this.externalVideo ? config : rtcOrientedVideoSize(config);
+    if (camera === this.camera) {
+      const client = this.requireClient(), version = this.roomVersion;
+      const published = this.videoPublishRequested;
+      await this.run(() => this.queueSenderUpdate(async () => {
+        const ensureActive2 = () => {
+          if (this.camera !== camera || this.client !== client || this.roomVersion !== version || published && !this.videoPublishRequested) throw this.cancelled();
+        };
+        ensureActive2();
+        if (this.videoPublishRequested) {
+          await AgoraVideoSender.apply(camera, this.cameraEncodingConfiguration(config), ensureActive2);
+        }
+        this.cameraSenderConfiguration = { ...config };
+      }));
+      return;
+    }
+    const encodingSize = config;
     await this.run(async () => {
       await camera.setEncoderConfiguration({
         width: encodingSize.width,
@@ -1525,14 +1827,45 @@ var _AgoraRtcManager = class _AgoraRtcManager {
         bitrateMin: config.minimumBitrate,
         bitrateMax: config.maximumBitrate
       });
-      await camera.setOptimizationMode(config.encoderPreference === "maintainFramerate" /* maintainFramerate */ ? "motion" : "detail");
+      if (this.appliedOptimizationModes.get(camera) !== config.encoderPreference) {
+        await camera.setOptimizationMode(config.encoderPreference === "maintainFramerate" /* maintainFramerate */ ? "motion" : "detail");
+        this.appliedOptimizationModes.set(camera, config.encoderPreference);
+      }
     });
   }
+  queueSenderUpdate(operation) {
+    const next = this.senderUpdateTail.then(operation);
+    this.senderUpdateTail = next.catch(() => {
+    });
+    return next;
+  }
+  /** 发布/重建 sender 后恢复最近成功的目标配置；排队时不捕获过期的参数对象。 */
+  restoreCameraSender(camera) {
+    const client = this.client, version = this.roomVersion;
+    return this.queueSenderUpdate(async () => {
+      const ensureActive2 = () => {
+        if (this.camera !== camera || this.client !== client || this.roomVersion !== version || !this.videoPublishRequested) {
+          throw this.cancelled();
+        }
+      };
+      ensureActive2();
+      const config = this.cameraSenderConfiguration;
+      if (config) await AgoraVideoSender.apply(camera, this.cameraEncodingConfiguration(config), ensureActive2);
+    });
+  }
+  cameraEncodingConfiguration(config) {
+    return this.cameraRotation ? config : { ...config, ...rtcOrientedVideoSize(config) };
+  }
+  releaseCameraSender() {
+    if (this.cameraTransceiverListener) _optionalChain([this, 'access', _152 => _152.camera, 'optionalAccess', _153 => _153.off, 'call', _154 => _154("transceiver-updated", this.cameraTransceiverListener)]);
+    this.cameraTransceiverListener = void 0;
+    this.cameraSenderConfiguration = void 0;
+  }
   /**
    * 使用会话下发的字符串频道与 UID 入房；不采信后端区域覆盖。
    */
   async joinRoom(configuration) {
-    await _optionalChain([this, 'access', _100 => _100.rejoinTask, 'optionalAccess', _101 => _101.catch, 'call', _102 => _102(() => {
+    await _optionalChain([this, 'access', _155 => _155.rejoinTask, 'optionalAccess', _156 => _156.catch, 'call', _157 => _157(() => {
     })]);
     const client = this.requireClient();
     if (configuration.provider !== "agora" /* agora */ || this.connection) {
@@ -1546,7 +1879,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     }
     this.connection = configuration;
     for (const user of client.remoteUsers) {
-      if (user.hasVideo) _optionalChain([this, 'access', _103 => _103.listener, 'optionalAccess', _104 => _104.onRemoteVideoPublished, 'call', _105 => _105(String(user.uid), true)]);
+      if (user.hasVideo) _optionalChain([this, 'access', _158 => _158.listener, 'optionalAccess', _159 => _159.onRemoteVideoPublished, 'call', _160 => _160(String(user.uid), true)]);
     }
     this.statisticsTimer = setInterval(() => {
       if (this.client !== client || !this.connection || this.tokenExpired || this.rejoinOperation) return;
@@ -1568,7 +1901,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    * 应用同一频道的新 Token；即将过期时续签，已经过期时重新进房并恢复媒体。
    */
   async updateCredentials(config, signal) {
-    if (_optionalChain([signal, 'optionalAccess', _106 => _106.aborted])) throw this.cancelled();
+    if (_optionalChain([signal, 'optionalAccess', _161 => _161.aborted])) throw this.cancelled();
     const current = this.connection;
     const client = this.requireClient();
     if (!current || config.provider !== "agora" /* agora */ || config.appID !== current.appID || config.roomID !== current.roomID || config.userID !== current.userID) {
@@ -1584,7 +1917,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
       }
     }
     this.ensureRoomCurrent(client, version);
-    if (_optionalChain([signal, 'optionalAccess', _107 => _107.aborted])) throw this.cancelled();
+    if (_optionalChain([signal, 'optionalAccess', _162 => _162.aborted])) throw this.cancelled();
     if (this.tokenExpired) await this.rejoinRoom(client, config, signal);
     else this.connection = config;
   }
@@ -1607,21 +1940,21 @@ var _AgoraRtcManager = class _AgoraRtcManager {
         reject(this.cancelled());
       };
       this.cancelRejoin = cancel;
-      _optionalChain([signal, 'optionalAccess', _108 => _108.addEventListener, 'call', _109 => _109("abort", cancel, { once: true })]);
+      _optionalChain([signal, 'optionalAccess', _163 => _163.addEventListener, 'call', _164 => _164("abort", cancel, { once: true })]);
       task.then(resolve, reject);
-      if (_optionalChain([signal, 'optionalAccess', _110 => _110.aborted])) cancel();
+      if (_optionalChain([signal, 'optionalAccess', _165 => _165.aborted])) cancel();
     });
     this.rejoinOperation = operation;
     try {
       await operation;
     } finally {
-      _optionalChain([signal, 'optionalAccess', _111 => _111.removeEventListener, 'call', _112 => _112("abort", cancel)]);
+      _optionalChain([signal, 'optionalAccess', _166 => _166.removeEventListener, 'call', _167 => _167("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) _optionalChain([this, 'access', _113 => _113.listener, 'optionalAccess', _114 => _114.onRemoteVideoPublished, 'call', _115 => _115(String(user.uid), true)]);
+      if (user.hasVideo) _optionalChain([this, 'access', _168 => _168.listener, 'optionalAccess', _169 => _169.onRemoteVideoPublished, 'call', _170 => _170(String(user.uid), true)]);
     }
   }
   /**
@@ -1629,10 +1962,10 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    */
   async performRejoin(client, config, version) {
     this.ensureRoomCurrent(client, version);
-    _optionalChain([this, 'access', _116 => _116.cancelSendDelay, 'optionalCall', _117 => _117()]);
-    _optionalChain([this, 'access', _118 => _118.cancelActiveSend, 'optionalCall', _119 => _119()]);
-    _optionalChain([this, 'access', _120 => _120.listener, 'optionalAccess', _121 => _121.onRoomRejoining, 'optionalCall', _122 => _122()]);
-    for (const user of client.remoteUsers) _optionalChain([user, 'access', _123 => _123.audioTrack, 'optionalAccess', _124 => _124.stop, 'call', _125 => _125()]);
+    _optionalChain([this, 'access', _171 => _171.cancelSendDelay, 'optionalCall', _172 => _172()]);
+    _optionalChain([this, 'access', _173 => _173.cancelActiveSend, 'optionalCall', _174 => _174()]);
+    _optionalChain([this, 'access', _175 => _175.listener, 'optionalAccess', _176 => _176.onRoomRejoining, 'optionalCall', _177 => _177()]);
+    for (const user of client.remoteUsers) _optionalChain([user, 'access', _178 => _178.audioTrack, 'optionalAccess', _179 => _179.stop, 'call', _180 => _180()]);
     await this.run(() => client.leave());
     this.ensureRoomCurrent(client, version);
     await this.run(() => client.join(config.appID, config.roomID, config.roomToken, config.userID));
@@ -1645,6 +1978,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     if (this.videoPublishRequested && video) {
       await this.run(() => client.publish(video));
       this.ensureRoomCurrent(client, version);
+      if (video === this.camera) await this.restoreCameraSender(this.camera);
     }
     if (this.audioPublishRequested && audio) {
       await this.run(() => client.publish(audio));
@@ -1674,6 +2008,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     if (client !== this.client || !this.videoPublishRequested) throw this.cancelled();
     if (client.localTracks.includes(camera)) return;
     await this.run(() => client.publish(camera));
+    if (camera === this.camera) await this.run(() => this.restoreCameraSender(this.camera));
   }
   /**
    * 停止视频发布但保留采集与预览。
@@ -1754,8 +2089,8 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     const user = client.remoteUsers.find((user2) => String(user2.uid) === userID);
     if (!subscribe) {
       this.requestedAudio.delete(userID);
-      _optionalChain([user, 'optionalAccess', _126 => _126.audioTrack, 'optionalAccess', _127 => _127.stop, 'call', _128 => _128()]);
-      if (_optionalChain([user, 'optionalAccess', _129 => _129.audioTrack]) && !this.rejoinTask) await this.run(() => client.unsubscribe(user, "audio"));
+      _optionalChain([user, 'optionalAccess', _181 => _181.audioTrack, 'optionalAccess', _182 => _182.stop, 'call', _183 => _183()]);
+      if (_optionalChain([user, 'optionalAccess', _184 => _184.audioTrack]) && !this.rejoinTask) await this.run(() => client.unsubscribe(user, "audio"));
       return;
     }
     this.requestedAudio.add(userID);
@@ -1766,7 +2101,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
       if (this.requestedAudio.has(userID)) await this.subscribeRemoteAudio(userID, true);
       return;
     }
-    if (!_optionalChain([user, 'optionalAccess', _130 => _130.hasAudio])) return;
+    if (!_optionalChain([user, 'optionalAccess', _185 => _185.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)) {
@@ -1780,9 +2115,9 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    */
   setRemoteAudioVolume(volume, userID) {
     this.audioVolumes.set(userID, Math.max(0, Math.min(100, Number.isFinite(volume) ? Math.round(volume) : 0)));
-    const user = _optionalChain([this, 'access', _131 => _131.client, 'optionalAccess', _132 => _132.remoteUsers, 'access', _133 => _133.find, 'call', _134 => _134((user2) => String(user2.uid) === userID)]);
+    const user = _optionalChain([this, 'access', _186 => _186.client, 'optionalAccess', _187 => _187.remoteUsers, 'access', _188 => _188.find, 'call', _189 => _189((user2) => String(user2.uid) === userID)]);
     if (this.rejoinTask || this.tokenExpired) {
-      _optionalChain([user, 'optionalAccess', _135 => _135.audioTrack, 'optionalAccess', _136 => _136.stop, 'call', _137 => _137()]);
+      _optionalChain([user, 'optionalAccess', _190 => _190.audioTrack, 'optionalAccess', _191 => _191.stop, 'call', _192 => _192()]);
       return;
     }
     if (user) this.applyAudioVolume(user);
@@ -1871,42 +2206,45 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     const handleExpired = () => {
       if (!active() || this.tokenExpired) return;
       this.tokenExpired = true;
-      _optionalChain([this, 'access', _138 => _138.listener, 'optionalAccess', _139 => _139.onTokenExpired, 'optionalCall', _140 => _140()]);
+      _optionalChain([this, 'access', _193 => _193.listener, 'optionalAccess', _194 => _194.onNetworkStatistics, 'optionalCall', _195 => _195(void 0)]);
+      _optionalChain([this, 'access', _196 => _196.listener, 'optionalAccess', _197 => _197.onTokenExpired, 'optionalCall', _198 => _198()]);
     };
     client.on("user-published", (user, kind) => {
       if (!mediaActive()) return;
-      if (kind === "video") _optionalChain([this, 'access', _141 => _141.listener, 'optionalAccess', _142 => _142.onRemoteVideoPublished, 'call', _143 => _143(String(user.uid), true)]);
+      if (kind === "video") _optionalChain([this, 'access', _199 => _199.listener, 'optionalAccess', _200 => _200.onRemoteVideoPublished, 'call', _201 => _201(String(user.uid), true)]);
       if (kind === "audio" && this.requestedAudio.has(String(user.uid))) {
         void this.subscribeRemoteAudio(String(user.uid), true).catch((error) => {
-          if (active()) _optionalChain([this, 'access', _144 => _144.listener, 'optionalAccess', _145 => _145.onError, 'optionalCall', _146 => _146(this.mapError(error))]);
+          if (active()) _optionalChain([this, 'access', _202 => _202.listener, 'optionalAccess', _203 => _203.onError, 'optionalCall', _204 => _204(this.mapError(error))]);
         });
       }
     });
     client.on("user-unpublished", (user, kind) => {
       if (!mediaActive()) return;
-      if (kind === "video") _optionalChain([this, 'access', _147 => _147.listener, 'optionalAccess', _148 => _148.onRemoteVideoPublished, 'call', _149 => _149(String(user.uid), false)]);
-      if (kind === "audio") _optionalChain([user, 'access', _150 => _150.audioTrack, 'optionalAccess', _151 => _151.stop, 'call', _152 => _152()]);
+      if (kind === "video") _optionalChain([this, 'access', _205 => _205.listener, 'optionalAccess', _206 => _206.onRemoteVideoPublished, 'call', _207 => _207(String(user.uid), false)]);
+      if (kind === "audio") _optionalChain([user, 'access', _208 => _208.audioTrack, 'optionalAccess', _209 => _209.stop, 'call', _210 => _210()]);
     });
     client.on("user-left", (user) => {
-      if (mediaActive()) _optionalChain([this, 'access', _153 => _153.listener, 'optionalAccess', _154 => _154.onRemoteVideoPublished, 'call', _155 => _155(String(user.uid), false)]);
+      if (mediaActive()) _optionalChain([this, 'access', _211 => _211.listener, 'optionalAccess', _212 => _212.onRemoteVideoPublished, 'call', _213 => _213(String(user.uid), false)]);
     });
     client.on("stream-message", (uid, data) => {
-      if (mediaActive()) _optionalChain([this, 'access', _156 => _156.listener, 'optionalAccess', _157 => _157.onCustomMessageReceived, 'call', _158 => _158(String(uid), typeof data === "string" ? data : new TextDecoder().decode(data))]);
+      if (mediaActive()) _optionalChain([this, 'access', _214 => _214.listener, 'optionalAccess', _215 => _215.onCustomMessageReceived, 'call', _216 => _216(String(uid), typeof data === "string" ? data : new TextDecoder().decode(data))]);
     });
     client.on("network-quality", (quality) => {
-      if (mediaActive()) AgoraRtcStatistics.network(quality, this.listener);
+      if (mediaActive() && !this.networkQualitySuspended) AgoraRtcStatistics.network(quality, this.listener);
     });
     client.on("token-privilege-will-expire", () => {
-      if (active() && !this.tokenExpired) _optionalChain([this, 'access', _159 => _159.listener, 'optionalAccess', _160 => _160.onTokenWillExpire, 'optionalCall', _161 => _161()]);
+      if (active() && !this.tokenExpired) _optionalChain([this, 'access', _217 => _217.listener, 'optionalAccess', _218 => _218.onTokenWillExpire, 'optionalCall', _219 => _219()]);
     });
     client.on("token-privilege-did-expire", handleExpired);
     client.on("connection-state-change", (state2, previous, reason) => {
+      if (this.client === client) this.networkQualitySuspended = state2 !== "CONNECTED";
+      if (active() && state2 !== "CONNECTED") _optionalChain([this, 'access', _220 => _220.listener, 'optionalAccess', _221 => _221.onNetworkStatistics, 'optionalCall', _222 => _222(void 0)]);
       if (state2 === "DISCONNECTED" && reason === "TOKEN_EXPIRE") {
         handleExpired();
         return;
       }
       if (active() && !this.tokenExpired && state2 === "DISCONNECTED" && previous !== "DISCONNECTED") {
-        _optionalChain([this, 'access', _162 => _162.listener, 'optionalAccess', _163 => _163.onError, 'optionalCall', _164 => _164(new XmaxError("RTC_ERROR" /* rtcError */, `Agora connection disconnected: ${_nullishCoalesce(reason, () => ( "unknown"))}`))]);
+        _optionalChain([this, 'access', _223 => _223.listener, 'optionalAccess', _224 => _224.onError, 'optionalCall', _225 => _225(new XmaxError("RTC_ERROR" /* rtcError */, `Agora connection disconnected: ${_nullishCoalesce(reason, () => ( "unknown"))}`))]);
       }
     });
   }
@@ -1915,20 +2253,21 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    */
   clearRoom() {
     this.roomVersion++;
-    _optionalChain([this, 'access', _165 => _165.cancelRejoin, 'optionalCall', _166 => _166()]);
+    _optionalChain([this, 'access', _226 => _226.cancelRejoin, 'optionalCall', _227 => _227()]);
     this.connection = void 0;
     this.tokenExpired = false;
+    this.networkQualitySuspended = false;
     this.videoPublishRequested = false;
     this.audioPublishRequested = false;
     clearInterval(this.statisticsTimer);
     this.statisticsTimer = void 0;
-    _optionalChain([this, 'access', _167 => _167.cancelSendDelay, 'optionalCall', _168 => _168()]);
-    _optionalChain([this, 'access', _169 => _169.cancelActiveSend, 'optionalCall', _170 => _170()]);
+    _optionalChain([this, 'access', _228 => _228.cancelSendDelay, 'optionalCall', _229 => _229()]);
+    _optionalChain([this, 'access', _230 => _230.cancelActiveSend, 'optionalCall', _231 => _231()]);
     this.sentPackets = [];
     this.sendTail = Promise.resolve();
     this.requestedAudio.clear();
     this.audioVolumes.clear();
-    for (const user of _nullishCoalesce(_optionalChain([this, 'access', _171 => _171.client, 'optionalAccess', _172 => _172.remoteUsers]), () => ( []))) _optionalChain([user, 'access', _173 => _173.audioTrack, 'optionalAccess', _174 => _174.stop, 'call', _175 => _175()]);
+    for (const user of _nullishCoalesce(_optionalChain([this, 'access', _232 => _232.client, 'optionalAccess', _233 => _233.remoteUsers]), () => ( []))) _optionalChain([user, 'access', _234 => _234.audioTrack, 'optionalAccess', _235 => _235.stop, 'call', _236 => _236()]);
   }
   /**
    * 判断异步恢复工作是否仍属于当前房间生命周期。
@@ -1953,8 +2292,8 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    * 获取已启动的相机采集。
    */
   requireCamera() {
-    if (!this.camera) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera capture is not running");
-    return this.camera;
+    if (!this.cameraSource || !this.camera) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera capture is not running");
+    return this.cameraSource;
   }
   /**
    * 获取当前可编码、发布的视频轨，不要求来源为摄像头。
@@ -2066,7 +2405,7 @@ var _RtcEngineManager = class _RtcEngineManager {
    * 释放有效租约、销毁 Engine，并把独占权交给下一个等待者。
    */
   release(lease) {
-    if (_optionalChain([this, 'access', _176 => _176.activeLease, 'optionalAccess', _177 => _177.id]) !== lease.id) {
+    if (_optionalChain([this, 'access', _237 => _237.activeLease, 'optionalAccess', _238 => _238.id]) !== lease.id) {
       return;
     }
     this.activeLease = void 0;
@@ -2140,10 +2479,10 @@ var RtcStatsLogger = class {
         `${XmaxLogger.localized("\u7D2F\u8BA1\u63A5\u6536\uFF1A", "Bytes Received: ")}${this.value(stats.bytesReceived, "bytes")}`
       ])];
       const local = stats.localStatistics;
-      if (_optionalChain([local, 'optionalAccess', _178 => _178.audio])) {
+      if (_optionalChain([local, 'optionalAccess', _239 => _239.audio])) {
         blocks.push(this.audioBlock("\u672C\u5730\u97F3\u9891\u53D1\u9001 (Local Audio Uplink)", local.audio, false));
       }
-      for (const video of _nullishCoalesce(_optionalChain([local, 'optionalAccess', _179 => _179.video]), () => ( []))) {
+      for (const video of _nullishCoalesce(_optionalChain([local, 'optionalAccess', _240 => _240.video]), () => ( []))) {
         blocks.push(this.videoBlock("\u672C\u5730\u89C6\u9891\u53D1\u9001 (Local Video Uplink)", video, false));
       }
       for (const remote of _nullishCoalesce(stats.remoteStatistics, () => ( []))) {
@@ -2233,8 +2572,8 @@ var RtcStatsLogger = class {
 
 // src/Foundation/RTC/TRTC/TrtcAudioVolumeSupport.ts
 function canControlTrtcRemoteAudioVolume(environment) {
-  const userAgent = _nullishCoalesce(_optionalChain([environment, 'optionalAccess', _180 => _180.userAgent]), () => ( (typeof navigator === "undefined" ? "" : navigator.userAgent)));
-  const maxTouchPoints = _nullishCoalesce(_optionalChain([environment, 'optionalAccess', _181 => _181.maxTouchPoints]), () => ( (typeof navigator === "undefined" ? 0 : _nullishCoalesce(navigator.maxTouchPoints, () => ( 0)))));
+  const userAgent = _nullishCoalesce(_optionalChain([environment, 'optionalAccess', _241 => _241.userAgent]), () => ( (typeof navigator === "undefined" ? "" : navigator.userAgent)));
+  const maxTouchPoints = _nullishCoalesce(_optionalChain([environment, 'optionalAccess', _242 => _242.maxTouchPoints]), () => ( (typeof navigator === "undefined" ? 0 : _nullishCoalesce(navigator.maxTouchPoints, () => ( 0)))));
   const ios = /iPhone|iPad|iPod/i.test(userAgent) || /Macintosh/i.test(userAgent) && maxTouchPoints > 1;
   return !ios;
 }
@@ -2321,11 +2660,11 @@ var TrtcRtcManager = class {
     this.isCapturing = false;
     this.isAudioCapturing = false;
     this.isInRoom = false;
-    _optionalChain([this, 'access', _182 => _182.removeStatsListeners, 'optionalCall', _183 => _183()]);
+    _optionalChain([this, 'access', _243 => _243.removeStatsListeners, 'optionalCall', _244 => _244()]);
     this.removeStatsListeners = void 0;
     if (!lease) {
-      _optionalChain([externalVideo, 'optionalAccess', _184 => _184.stop, 'call', _185 => _185()]);
-      _optionalChain([externalAudio, 'optionalAccess', _186 => _186.stop, 'call', _187 => _187()]);
+      _optionalChain([externalVideo, 'optionalAccess', _245 => _245.stop, 'call', _246 => _246()]);
+      _optionalChain([externalAudio, 'optionalAccess', _247 => _247.stop, 'call', _248 => _248()]);
       return;
     }
     try {
@@ -2336,8 +2675,8 @@ var TrtcRtcManager = class {
       await lease.engine.stopLocalVideo();
     } catch (e13) {
     }
-    _optionalChain([externalVideo, 'optionalAccess', _188 => _188.stop, 'call', _189 => _189()]);
-    _optionalChain([externalAudio, 'optionalAccess', _190 => _190.stop, 'call', _191 => _191()]);
+    _optionalChain([externalVideo, 'optionalAccess', _249 => _249.stop, 'call', _250 => _250()]);
+    _optionalChain([externalAudio, 'optionalAccess', _251 => _251.stop, 'call', _252 => _252()]);
     this.engineManager.release(lease);
   }
   /**
@@ -2355,10 +2694,10 @@ var TrtcRtcManager = class {
     this.externalVideo = video;
     let audio;
     try {
-      audio = _optionalChain([tracks, 'access', _192 => _192.audioTrack, 'optionalAccess', _193 => _193.clone, 'call', _194 => _194()]);
+      audio = _optionalChain([tracks, 'access', _253 => _253.audioTrack, 'optionalAccess', _254 => _254.clone, 'call', _255 => _255()]);
       this.externalAudio = audio;
       await engine.startLocalVideo({ publish: false, option: { videoTrack: video } });
-      if (_optionalChain([this, 'access', _195 => _195.lease, 'optionalAccess', _196 => _196.engine]) !== engine) {
+      if (_optionalChain([this, 'access', _256 => _256.lease, 'optionalAccess', _257 => _257.engine]) !== engine) {
         throw new XmaxError("CANCELLED" /* cancelled */, "External media preparation was cancelled");
       }
       if (audio) {
@@ -2366,12 +2705,12 @@ var TrtcRtcManager = class {
           publish: false,
           option: { audioTrack: audio, echoCancellation: false, autoGainControl: false, noiseSuppression: false }
         });
-        if (_optionalChain([this, 'access', _197 => _197.lease, 'optionalAccess', _198 => _198.engine]) !== engine) {
+        if (_optionalChain([this, 'access', _258 => _258.lease, 'optionalAccess', _259 => _259.engine]) !== engine) {
           throw new XmaxError("CANCELLED" /* cancelled */, "External media preparation was cancelled");
         }
       }
     } catch (error) {
-      if (_optionalChain([this, 'access', _199 => _199.lease, 'optionalAccess', _200 => _200.engine]) === engine) {
+      if (_optionalChain([this, 'access', _260 => _260.lease, 'optionalAccess', _261 => _261.engine]) === engine) {
         await engine.stopLocalAudio().catch(() => {
         });
         await engine.stopLocalVideo().catch(() => {
@@ -2382,7 +2721,7 @@ var TrtcRtcManager = class {
         this.externalAudio = void 0;
       }
       video.stop();
-      _optionalChain([audio, 'optionalAccess', _201 => _201.stop, 'call', _202 => _202()]);
+      _optionalChain([audio, 'optionalAccess', _262 => _262.stop, 'call', _263 => _263()]);
       throw this.mapError(error);
     }
   }
@@ -2393,6 +2732,9 @@ var TrtcRtcManager = class {
    * @throws 引擎未初始化、已在采集、设备不可用或权限被拒绝时抛出错误。
    */
   async startCameraCapture(options) {
+    if (options.rotation !== void 0 && options.rotation !== 0) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera rotation currently requires Agora");
+    }
     const engine = this.requireEngine();
     if (this.isCapturing || this.externalVideo) {
       throw new XmaxError(
@@ -2467,7 +2809,7 @@ var TrtcRtcManager = class {
     if (this.externalVideo) {
       return;
     }
-    const engine = _optionalChain([this, 'access', _203 => _203.lease, 'optionalAccess', _204 => _204.engine]);
+    const engine = _optionalChain([this, 'access', _264 => _264.lease, 'optionalAccess', _265 => _265.engine]);
     this.isCapturing = false;
     if (!engine) {
       return;
@@ -2520,7 +2862,7 @@ var TrtcRtcManager = class {
    * 离开当前 RTC 房间；未在房间中或引擎未初始化时不产生效果，退房失败仅记录日志。
    */
   async leaveRoom() {
-    const engine = _optionalChain([this, 'access', _205 => _205.lease, 'optionalAccess', _206 => _206.engine]);
+    const engine = _optionalChain([this, 'access', _266 => _266.lease, 'optionalAccess', _267 => _267.engine]);
     if (!engine || !this.isInRoom) {
       return;
     }
@@ -2593,7 +2935,7 @@ var TrtcRtcManager = class {
    * 停止发布本地视频流；采集保持运行，本地预览不受影响。
    */
   async unpublishLocalVideo() {
-    const engine = _optionalChain([this, 'access', _207 => _207.lease, 'optionalAccess', _208 => _208.engine]);
+    const engine = _optionalChain([this, 'access', _268 => _268.lease, 'optionalAccess', _269 => _269.engine]);
     if (!engine || !this.isCapturing && !this.externalVideo) {
       return;
     }
@@ -2629,7 +2971,7 @@ var TrtcRtcManager = class {
    * 停止发布本地音频流；麦克风采集保持运行。
    */
   async unpublishLocalAudio() {
-    const engine = _optionalChain([this, 'access', _209 => _209.lease, 'optionalAccess', _210 => _210.engine]);
+    const engine = _optionalChain([this, 'access', _270 => _270.lease, 'optionalAccess', _271 => _271.engine]);
     if (!engine || !this.isAudioCapturing && !this.externalAudio) {
       return;
     }
@@ -2755,19 +3097,19 @@ var TrtcRtcManager = class {
   registerEventBridge(engine) {
     const source = engine;
     const onStatistics = (stats) => {
-      if (this.isInRoom && _optionalChain([this, 'access', _211 => _211.lease, 'optionalAccess', _212 => _212.engine]) === engine) {
+      if (this.isInRoom && _optionalChain([this, 'access', _272 => _272.lease, 'optionalAccess', _273 => _273.engine]) === engine) {
         RtcStatsLogger.logStatistics(stats);
-        const video = _optionalChain([stats, 'access', _213 => _213.localStatistics, 'optionalAccess', _214 => _214.video, 'optionalAccess', _215 => _215.find, 'call', _216 => _216((item) => item.videoType === "big")]);
+        const video = _optionalChain([stats, 'access', _274 => _274.localStatistics, 'optionalAccess', _275 => _275.video, 'optionalAccess', _276 => _276.find, 'call', _277 => _277((item) => item.videoType === "big")]);
         const valid = (value, minimum) => typeof value === "number" && Number.isFinite(value) && value >= minimum ? value : void 0;
-        _optionalChain([this, 'access', _217 => _217.eventListener, 'optionalAccess', _218 => _218.onLocalVideoStatistics, 'optionalCall', _219 => _219(video ? Object.freeze({
+        _optionalChain([this, 'access', _278 => _278.eventListener, 'optionalAccess', _279 => _279.onLocalVideoStatistics, 'optionalCall', _280 => _280(video ? Object.freeze({
           width: valid(video.width, 1),
           height: valid(video.height, 1),
           frameRate: valid(video.frameRate, 0),
           bitrateKbps: valid(video.bitrate, 0)
         }) : void 0)]);
-        _optionalChain([this, 'access', _220 => _220.eventListener, 'optionalAccess', _221 => _221.onRemoteVideoStatistics, 'optionalCall', _222 => _222(Object.freeze(
+        _optionalChain([this, 'access', _281 => _281.eventListener, 'optionalAccess', _282 => _282.onRemoteVideoStatistics, 'optionalCall', _283 => _283(Object.freeze(
           (_nullishCoalesce(stats.remoteStatistics, () => ( []))).flatMap((remote) => {
-            const video2 = _optionalChain([remote, 'access', _223 => _223.video, 'optionalAccess', _224 => _224.find, 'call', _225 => _225((item) => item.videoType === "big")]);
+            const video2 = _optionalChain([remote, 'access', _284 => _284.video, 'optionalAccess', _285 => _285.find, 'call', _286 => _286((item) => item.videoType === "big")]);
             if (!video2) {
               return [];
             }
@@ -2789,11 +3131,11 @@ var TrtcRtcManager = class {
       }
     };
     const onNetworkQuality = (stats) => {
-      if (this.isInRoom && _optionalChain([this, 'access', _226 => _226.lease, 'optionalAccess', _227 => _227.engine]) === engine) {
+      if (this.isInRoom && _optionalChain([this, 'access', _287 => _287.lease, 'optionalAccess', _288 => _288.engine]) === engine) {
         RtcStatsLogger.logNetworkQuality(stats);
         const quality = (value) => Number.isInteger(value) && value >= 0 && value <= 6 ? value : void 0;
         const rtt = (value) => Number.isFinite(value) && value >= 0 ? value : void 0;
-        _optionalChain([this, 'access', _228 => _228.eventListener, 'optionalAccess', _229 => _229.onNetworkStatistics, 'optionalCall', _230 => _230(Object.freeze({
+        _optionalChain([this, 'access', _289 => _289.eventListener, 'optionalAccess', _290 => _290.onNetworkStatistics, 'optionalCall', _291 => _291(Object.freeze({
           uplinkQuality: quality(stats.uplinkNetworkQuality),
           downlinkQuality: quality(stats.downlinkNetworkQuality),
           uplinkRttMs: rtt(stats.uplinkRTT),
@@ -2808,19 +3150,19 @@ var TrtcRtcManager = class {
       source.off(RTC_EVENT.networkQuality, onNetworkQuality);
     };
     source.on(RTC_EVENT.remoteVideoAvailable, (event) => {
-      if (_optionalChain([this, 'access', _231 => _231.lease, 'optionalAccess', _232 => _232.engine]) !== engine || event.streamType !== STREAM_TYPE_MAIN) {
+      if (_optionalChain([this, 'access', _292 => _292.lease, 'optionalAccess', _293 => _293.engine]) !== engine || event.streamType !== STREAM_TYPE_MAIN) {
         return;
       }
-      _optionalChain([this, 'access', _233 => _233.eventListener, 'optionalAccess', _234 => _234.onRemoteVideoPublished, 'call', _235 => _235(event.userId, true)]);
+      _optionalChain([this, 'access', _294 => _294.eventListener, 'optionalAccess', _295 => _295.onRemoteVideoPublished, 'call', _296 => _296(event.userId, true)]);
     });
     source.on(RTC_EVENT.remoteVideoUnavailable, (event) => {
-      if (_optionalChain([this, 'access', _236 => _236.lease, 'optionalAccess', _237 => _237.engine]) !== engine || event.streamType !== STREAM_TYPE_MAIN) {
+      if (_optionalChain([this, 'access', _297 => _297.lease, 'optionalAccess', _298 => _298.engine]) !== engine || event.streamType !== STREAM_TYPE_MAIN) {
         return;
       }
-      _optionalChain([this, 'access', _238 => _238.eventListener, 'optionalAccess', _239 => _239.onRemoteVideoPublished, 'call', _240 => _240(event.userId, false)]);
+      _optionalChain([this, 'access', _299 => _299.eventListener, 'optionalAccess', _300 => _300.onRemoteVideoPublished, 'call', _301 => _301(event.userId, false)]);
     });
     source.on(RTC_EVENT.customMessage, (event) => {
-      if (_optionalChain([this, 'access', _241 => _241.lease, 'optionalAccess', _242 => _242.engine]) !== engine || event.cmdId !== CUSTOM_MESSAGE_CMD_ID) {
+      if (_optionalChain([this, 'access', _302 => _302.lease, 'optionalAccess', _303 => _303.engine]) !== engine || event.cmdId !== CUSTOM_MESSAGE_CMD_ID) {
         return;
       }
       let message;
@@ -2830,14 +3172,14 @@ var TrtcRtcManager = class {
         XmaxLogger.rtc.warning(() => "\u81EA\u5B9A\u4E49\u6D88\u606F\u89E3\u7801\u5931\u8D25 (Failed to Decode Custom Message)");
         return;
       }
-      _optionalChain([this, 'access', _243 => _243.eventListener, 'optionalAccess', _244 => _244.onCustomMessageReceived, 'call', _245 => _245(event.userId, message)]);
+      _optionalChain([this, 'access', _304 => _304.eventListener, 'optionalAccess', _305 => _305.onCustomMessageReceived, 'call', _306 => _306(event.userId, message)]);
     });
   }
   /**
    * 返回当前引擎实例；未初始化时抛出错误。
    */
   requireEngine() {
-    const engine = _optionalChain([this, 'access', _246 => _246.lease, 'optionalAccess', _247 => _247.engine]);
+    const engine = _optionalChain([this, 'access', _307 => _307.lease, 'optionalAccess', _308 => _308.engine]);
     if (!engine) {
       throw new XmaxError(
         "RTC_ERROR" /* rtcError */,
@@ -2854,8 +3196,8 @@ var TrtcRtcManager = class {
       return error;
     }
     const rtcError = error;
-    const originName = _nullishCoalesce(_optionalChain([rtcError, 'optionalAccess', _248 => _248.originError, 'optionalAccess', _249 => _249.name]), () => ( ""));
-    const message = typeof _optionalChain([rtcError, 'optionalAccess', _250 => _250.message]) === "string" && rtcError.message.trim().length > 0 ? rtcError.message.trim() : String(error);
+    const originName = _nullishCoalesce(_optionalChain([rtcError, 'optionalAccess', _309 => _309.originError, 'optionalAccess', _310 => _310.name]), () => ( ""));
+    const message = typeof _optionalChain([rtcError, 'optionalAccess', _311 => _311.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);
     }
@@ -2978,12 +3320,12 @@ var VeRtcManager = class {
     this.sdk = void 0;
     this.camera = void 0;
     this.microphone = false;
-    _optionalChain([engine, 'optionalAccess', _251 => _251.removeAllListeners, 'call', _252 => _252()]);
+    _optionalChain([engine, 'optionalAccess', _312 => _312.removeAllListeners, 'call', _313 => _313()]);
     try {
       if (engine && sdk) sdk.default.destroyEngine(engine);
     } finally {
-      _optionalChain([this, 'access', _253 => _253.externalVideo, 'optionalAccess', _254 => _254.stop, 'call', _255 => _255()]);
-      _optionalChain([this, 'access', _256 => _256.externalAudio, 'optionalAccess', _257 => _257.stop, 'call', _258 => _258()]);
+      _optionalChain([this, 'access', _314 => _314.externalVideo, 'optionalAccess', _315 => _315.stop, 'call', _316 => _316()]);
+      _optionalChain([this, 'access', _317 => _317.externalAudio, 'optionalAccess', _318 => _318.stop, 'call', _319 => _319()]);
       this.externalVideo = void 0;
       this.externalAudio = void 0;
     }
@@ -3010,7 +3352,7 @@ var VeRtcManager = class {
       }
     };
     try {
-      audio = _optionalChain([tracks, 'access', _259 => _259.audioTrack, 'optionalAccess', _260 => _260.clone, 'call', _261 => _261()]);
+      audio = _optionalChain([tracks, 'access', _320 => _320.audioTrack, 'optionalAccess', _321 => _321.clone, 'call', _322 => _322()]);
       this.externalAudio = audio;
       await engine.setVideoSourceType(index, sdk.VideoSourceType.VIDEO_SOURCE_TYPE_EXTERNAL);
       ensureCurrent();
@@ -3034,11 +3376,14 @@ var VeRtcManager = class {
         this.externalAudio = void 0;
       }
       video.stop();
-      _optionalChain([audio, 'optionalAccess', _262 => _262.stop, 'call', _263 => _263()]);
+      _optionalChain([audio, 'optionalAccess', _323 => _323.stop, 'call', _324 => _324()]);
       throw this.mapError(error);
     }
   }
   async startCameraCapture(options) {
+    if (options.rotation !== void 0 && options.rotation !== 0) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera rotation currently requires Agora");
+    }
     const engine = this.requireEngine();
     if (this.camera || this.externalVideo) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local video is already prepared");
@@ -3103,9 +3448,9 @@ var VeRtcManager = class {
     }));
   }
   async joinRoom(config) {
-    await _optionalChain([this, 'access', _264 => _264.joining, 'optionalAccess', _265 => _265.catch, 'call', _266 => _266(() => {
+    await _optionalChain([this, 'access', _325 => _325.joining, 'optionalAccess', _326 => _326.catch, 'call', _327 => _327(() => {
     })]);
-    await _optionalChain([this, 'access', _267 => _267.recovery, 'optionalAccess', _268 => _268.catch, 'call', _269 => _269(() => {
+    await _optionalChain([this, 'access', _328 => _328.recovery, 'optionalAccess', _329 => _329.catch, 'call', _330 => _330(() => {
     })]);
     const engine = this.requireEngine();
     if (config.provider !== "vertc" /* vertc */ || config.appID !== VERTC_APP_ID || this.connection) {
@@ -3154,7 +3499,7 @@ var VeRtcManager = class {
   async updateCredentials(config, signal) {
     const engine = this.requireEngine();
     const current = this.connection;
-    if (_optionalChain([signal, 'optionalAccess', _270 => _270.aborted])) throw this.cancelled();
+    if (_optionalChain([signal, 'optionalAccess', _331 => _331.aborted])) throw this.cancelled();
     if (!current || config.provider !== "vertc" /* vertc */ || config.appID !== current.appID || config.roomID !== current.roomID || config.userID !== current.userID) {
       throw new XmaxError("SESSION_ERROR" /* sessionError */, "VeRTC session binding changed");
     }
@@ -3182,7 +3527,7 @@ var VeRtcManager = class {
     const restore = this.tokenExpired || this.publishPrivilegeExpired || this.subscribePrivilegeExpired;
     if (restore) {
       this.joined = false;
-      _optionalChain([this, 'access', _271 => _271.listener, 'optionalAccess', _272 => _272.onRoomRejoining, 'optionalCall', _273 => _273()]);
+      _optionalChain([this, 'access', _332 => _332.listener, 'optionalAccess', _333 => _333.onRoomRejoining, 'optionalCall', _334 => _334()]);
       this.clearPlayers();
       this.clearStatistics();
       if (this.tokenExpired) {
@@ -3353,13 +3698,13 @@ var VeRtcManager = class {
       if (!active()) return;
       if (video(mediaType)) {
         this.publishedVideo.add(userId);
-        if (mediaActive()) _optionalChain([this, 'access', _274 => _274.listener, 'optionalAccess', _275 => _275.onRemoteVideoPublished, 'call', _276 => _276(userId, true)]);
+        if (mediaActive()) _optionalChain([this, 'access', _335 => _335.listener, 'optionalAccess', _336 => _336.onRemoteVideoPublished, 'call', _337 => _337(userId, true)]);
       }
       if (audio(mediaType)) {
         this.publishedAudio.add(userId);
         if (mediaActive() && this.requestedAudio.has(userId)) {
           void this.subscribeRemoteAudio(userId, true).catch((error) => {
-            if (mediaActive()) _optionalChain([this, 'access', _277 => _277.listener, 'optionalAccess', _278 => _278.onError, 'optionalCall', _279 => _279(this.mapError(error))]);
+            if (mediaActive()) _optionalChain([this, 'access', _338 => _338.listener, 'optionalAccess', _339 => _339.onError, 'optionalCall', _340 => _340(this.mapError(error))]);
           });
         }
       }
@@ -3379,10 +3724,10 @@ var VeRtcManager = class {
       this.clearPlayer(userInfo.userId);
     });
     engine.on(events.onRoomMessageReceived, ({ userId, message }) => {
-      if (mediaActive() && typeof message === "string") _optionalChain([this, 'access', _280 => _280.listener, 'optionalAccess', _281 => _281.onCustomMessageReceived, 'call', _282 => _282(userId, message)]);
+      if (mediaActive() && typeof message === "string") _optionalChain([this, 'access', _341 => _341.listener, 'optionalAccess', _342 => _342.onCustomMessageReceived, 'call', _343 => _343(userId, message)]);
     });
     const willExpire = () => {
-      if (active()) _optionalChain([this, 'access', _283 => _283.listener, 'optionalAccess', _284 => _284.onTokenWillExpire, 'optionalCall', _285 => _285()]);
+      if (active()) _optionalChain([this, 'access', _344 => _344.listener, 'optionalAccess', _345 => _345.onTokenWillExpire, 'optionalCall', _346 => _346()]);
     };
     engine.on(events.onTokenWillExpire, willExpire);
     engine.on(events.onTokenPublishPrivilegeWillExpire, willExpire);
@@ -3390,13 +3735,13 @@ var VeRtcManager = class {
     engine.on(events.onTokenPublishPrivilegeDidExpired, () => {
       if (!active() || this.publishPrivilegeExpired) return;
       this.publishPrivilegeExpired = true;
-      _optionalChain([this, 'access', _286 => _286.listener, 'optionalAccess', _287 => _287.onTokenExpired, 'optionalCall', _288 => _288()]);
+      _optionalChain([this, 'access', _347 => _347.listener, 'optionalAccess', _348 => _348.onTokenExpired, 'optionalCall', _349 => _349()]);
     });
     engine.on(events.onTokenSubscribePrivilegeDidExpired, () => {
       if (!active() || this.subscribePrivilegeExpired) return;
       this.subscribePrivilegeExpired = true;
       this.clearPlayers();
-      _optionalChain([this, 'access', _289 => _289.listener, 'optionalAccess', _290 => _290.onTokenExpired, 'optionalCall', _291 => _291()]);
+      _optionalChain([this, 'access', _350 => _350.listener, 'optionalAccess', _351 => _351.onTokenExpired, 'optionalCall', _352 => _352()]);
     });
     engine.on(events.onError, ({ errorCode }) => {
       if (!active()) return;
@@ -3404,23 +3749,23 @@ var VeRtcManager = class {
         if (this.tokenExpired) return;
         this.tokenExpired = true;
         this.clearPlayers();
-        _optionalChain([this, 'access', _292 => _292.listener, 'optionalAccess', _293 => _293.onTokenExpired, 'optionalCall', _294 => _294()]);
-      } else _optionalChain([this, 'access', _295 => _295.listener, 'optionalAccess', _296 => _296.onError, 'optionalCall', _297 => _297(this.mapError({ code: errorCode }))]);
+        _optionalChain([this, 'access', _353 => _353.listener, 'optionalAccess', _354 => _354.onTokenExpired, 'optionalCall', _355 => _355()]);
+      } else _optionalChain([this, 'access', _356 => _356.listener, 'optionalAccess', _357 => _357.onError, 'optionalCall', _358 => _358(this.mapError({ code: errorCode }))]);
     });
     engine.on(events.onConnectionStateChanged, ({ state: state2 }) => {
       if (!mediaActive() || state2 !== this.sdk.ConnectionState.CONNECTION_STATE_RECONNECTED) return;
-      _optionalChain([this, 'access', _298 => _298.listener, 'optionalAccess', _299 => _299.onRoomRejoining, 'optionalCall', _300 => _300()]);
+      _optionalChain([this, 'access', _359 => _359.listener, 'optionalAccess', _360 => _360.onRoomRejoining, 'optionalCall', _361 => _361()]);
       this.clearPlayers();
       this.clearStatistics();
       this.replayVideo();
       for (const userID of this.requestedAudio) {
         void this.subscribeRemoteAudio(userID, true).catch((error) => {
-          if (mediaActive()) _optionalChain([this, 'access', _301 => _301.listener, 'optionalAccess', _302 => _302.onError, 'optionalCall', _303 => _303(this.mapError(error))]);
+          if (mediaActive()) _optionalChain([this, 'access', _362 => _362.listener, 'optionalAccess', _363 => _363.onError, 'optionalCall', _364 => _364(this.mapError(error))]);
         });
       }
     });
     engine.on(events.onNetworkQuality, (up, down) => {
-      if (mediaActive()) _optionalChain([this, 'access', _304 => _304.listener, 'optionalAccess', _305 => _305.onNetworkStatistics, 'optionalCall', _306 => _306(Object.freeze({
+      if (mediaActive()) _optionalChain([this, 'access', _365 => _365.listener, 'optionalAccess', _366 => _366.onNetworkStatistics, 'optionalCall', _367 => _367(Object.freeze({
         uplinkQuality: VeRtcStatistics.quality(up),
         downlinkQuality: VeRtcStatistics.quality(down)
       }))]);
@@ -3429,7 +3774,7 @@ var VeRtcManager = class {
       if (!mediaActive() || stats.isScreen || !this.videoRequested) return;
       const result = VeRtcStatistics.local(stats.videoStats);
       this.uplinkLossPercent = result.uplinkLossPercent;
-      _optionalChain([this, 'access', _307 => _307.listener, 'optionalAccess', _308 => _308.onLocalVideoStatistics, 'optionalCall', _309 => _309(result)]);
+      _optionalChain([this, 'access', _368 => _368.listener, 'optionalAccess', _369 => _369.onLocalVideoStatistics, 'optionalCall', _370 => _370(result)]);
       XmaxLogger.rtc.info(() => `VeRTC local video statistics: ${JSON.stringify(result)}`, 2 /* performance */);
     });
     engine.on(events.onRemoteStreamStats, (stats) => {
@@ -3439,21 +3784,21 @@ var VeRtcManager = class {
     });
   }
   replayVideo() {
-    for (const userID of this.publishedVideo) _optionalChain([this, 'access', _310 => _310.listener, 'optionalAccess', _311 => _311.onRemoteVideoPublished, 'call', _312 => _312(userID, true)]);
+    for (const userID of this.publishedVideo) _optionalChain([this, 'access', _371 => _371.listener, 'optionalAccess', _372 => _372.onRemoteVideoPublished, 'call', _373 => _373(userID, true)]);
   }
   removeVideo(userID) {
     this.publishedVideo.delete(userID);
     this.remoteStatistics.delete(userID);
     this.emitRemoteStatistics();
-    if (this.joined && !this.tokenExpired) _optionalChain([this, 'access', _313 => _313.listener, 'optionalAccess', _314 => _314.onRemoteVideoPublished, 'call', _315 => _315(userID, false)]);
+    if (this.joined && !this.tokenExpired) _optionalChain([this, 'access', _374 => _374.listener, 'optionalAccess', _375 => _375.onRemoteVideoPublished, 'call', _376 => _376(userID, false)]);
   }
   emitRemoteStatistics() {
-    _optionalChain([this, 'access', _316 => _316.listener, 'optionalAccess', _317 => _317.onRemoteVideoStatistics, 'optionalCall', _318 => _318(Object.freeze([...this.remoteStatistics.values()]))]);
+    _optionalChain([this, 'access', _377 => _377.listener, 'optionalAccess', _378 => _378.onRemoteVideoStatistics, 'optionalCall', _379 => _379(Object.freeze([...this.remoteStatistics.values()]))]);
   }
   clearStatistics() {
     this.remoteStatistics.clear();
     this.uplinkLossPercent = void 0;
-    _optionalChain([this, 'access', _319 => _319.listener, 'optionalAccess', _320 => _320.onLocalVideoStatistics, 'optionalCall', _321 => _321(void 0)]);
+    _optionalChain([this, 'access', _380 => _380.listener, 'optionalAccess', _381 => _381.onLocalVideoStatistics, 'optionalCall', _382 => _382(void 0)]);
     this.emitRemoteStatistics();
   }
   clearPlayer(userID) {
@@ -3499,15 +3844,15 @@ var VeRtcManager = class {
       const cleanup = () => {
         clearTimeout(timer);
         roomSignal.removeEventListener("abort", cancel);
-        _optionalChain([signal, 'optionalAccess', _322 => _322.removeEventListener, 'call', _323 => _323("abort", cancel)]);
+        _optionalChain([signal, 'optionalAccess', _383 => _383.removeEventListener, 'call', _384 => _384("abort", cancel)]);
       };
       const cancel = () => {
-        if (_optionalChain([signal, 'optionalAccess', _324 => _324.aborted]) && !roomSignal.aborted) this.roomVersion++;
+        if (_optionalChain([signal, 'optionalAccess', _385 => _385.aborted]) && !roomSignal.aborted) this.roomVersion++;
         cleanup();
         reject(this.cancelled());
       };
       roomSignal.addEventListener("abort", cancel, { once: true });
-      _optionalChain([signal, 'optionalAccess', _325 => _325.addEventListener, 'call', _326 => _326("abort", cancel, { once: true })]);
+      _optionalChain([signal, 'optionalAccess', _386 => _386.addEventListener, 'call', _387 => _387("abort", cancel, { once: true })]);
       task.then((value) => {
         cleanup();
         resolve(value);
@@ -3515,7 +3860,7 @@ var VeRtcManager = class {
         cleanup();
         reject(error);
       });
-      if (roomSignal.aborted || _optionalChain([signal, 'optionalAccess', _327 => _327.aborted])) cancel();
+      if (roomSignal.aborted || _optionalChain([signal, 'optionalAccess', _388 => _388.aborted])) cancel();
     });
   }
   isCurrent(engine, version) {
@@ -3551,8 +3896,8 @@ var VeRtcManager = class {
   mapError(error, permissionCode) {
     if (error instanceof XmaxError) return error;
     const value = error;
-    const code = typeof _optionalChain([value, 'optionalAccess', _328 => _328.code]) === "string" && /^[A-Z_0-9-]{1,64}$/.test(value.code) ? value.code : "UNKNOWN";
-    const denied = _optionalChain([value, 'optionalAccess', _329 => _329.name]) === "NotAllowedError" || code === "PERMISSION_DENIED" || code === "DEVICE_PERMISSION_DENIED";
+    const code = typeof _optionalChain([value, 'optionalAccess', _389 => _389.code]) === "string" && /^[A-Z_0-9-]{1,64}$/.test(value.code) ? value.code : "UNKNOWN";
+    const denied = _optionalChain([value, 'optionalAccess', _390 => _390.name]) === "NotAllowedError" || code === "PERMISSION_DENIED" || code === "DEVICE_PERMISSION_DENIED";
     return new XmaxError(permissionCode && denied ? permissionCode : "RTC_ERROR" /* rtcError */, `VeRTC operation failed (${code})`);
   }
   cancelled() {
@@ -3634,7 +3979,7 @@ var PermissionManager = class {
    * @param deniedCode 权限被拒绝时抛出的错误码。
    */
   async ensurePermission(name, deniedCode) {
-    if (typeof navigator === "undefined" || !_optionalChain([navigator, 'access', _330 => _330.mediaDevices, 'optionalAccess', _331 => _331.getUserMedia])) {
+    if (typeof navigator === "undefined" || !_optionalChain([navigator, 'access', _391 => _391.mediaDevices, 'optionalAccess', _392 => _392.getUserMedia])) {
       throw new XmaxError(
         deniedCode,
         "This browser does not support media capture (getUserMedia)"
@@ -3642,7 +3987,7 @@ var PermissionManager = class {
     }
     try {
       const permissions = navigator.permissions;
-      if (!_optionalChain([permissions, 'optionalAccess', _332 => _332.query])) {
+      if (!_optionalChain([permissions, 'optionalAccess', _393 => _393.query])) {
         return;
       }
       const status = await permissions.query({
@@ -3822,10 +4167,10 @@ var _CameraController = class _CameraController {
      */
     __publicField(this, "storedUseMicrophone", false);
     __publicField(this, "storedFrameValidationEnabled", true);
-    this.permissionManager = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _333 => _333.permissionManager]), () => ( new PermissionManager()));
-    this.rtcManager = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _334 => _334.rtcManager]), () => ( new TrtcRtcManager()));
-    this.mediaService = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _335 => _335.mediaService]), () => ( new MediaService()));
-    this.errorListener = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _336 => _336.errorListener]), () => ( (() => {
+    this.permissionManager = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _394 => _394.permissionManager]), () => ( new PermissionManager()));
+    this.rtcManager = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _395 => _395.rtcManager]), () => ( new TrtcRtcManager()));
+    this.mediaService = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _396 => _396.mediaService]), () => ( new MediaService()));
+    this.errorListener = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _397 => _397.errorListener]), () => ( (() => {
     })));
   }
   /**
@@ -3851,7 +4196,7 @@ var _CameraController = class _CameraController {
    */
   async waitForValidCameraFrame(signal) {
     const track = this.activeTrack;
-    const mediaTrack = _optionalChain([track, 'optionalAccess', _337 => _337.mediaStreamTrack]);
+    const mediaTrack = _optionalChain([track, 'optionalAccess', _398 => _398.mediaStreamTrack]);
     if (!mediaTrack) throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Camera capture is not running");
     if (signal.aborted) throw new XmaxError("CANCELLED" /* cancelled */, "Camera frame validation cancelled");
     if (!this.isFrameValidationEnabled) return;
@@ -3875,6 +4220,7 @@ var _CameraController = class _CameraController {
    *
    * @param options.videoFormat 期望的输出尺寸、帧率和编码配置；尺寸按模型规则调整。
    * @param options.position 首次启动时使用的摄像头位置。
+   * @param options.rotation 输入帧顺时针旋转角度，默认 0；videoFormat 为旋转后的规格，目前仅 Agora 支持非零角度。
    * @param options.useMicrophone 是否申请麦克风权限并允许实时连接时启动音频采集。
    * @param options.enableFrameValidation 是否在发布前等待相机预热（固定 200ms），默认 true；false 跳过等待。
    * @returns 包含本地相机视频轨道的媒体流。
@@ -3887,6 +4233,7 @@ var _CameraController = class _CameraController {
         "Stop the current local camera stream before creating another one"
       );
     }
+    validateCameraRotation(_nullishCoalesce(options.rotation, () => ( 0)));
     const resolvedFormat = this.resolveVideoFormat(options.videoFormat);
     const track = new RealtimeVideoTrack({
       id: _CameraController.localVideoTrackID,
@@ -3909,7 +4256,8 @@ var _CameraController = class _CameraController {
         width: resolvedFormat.width,
         height: resolvedFormat.height,
         frameRate: resolvedFormat.fps,
-        position: options.position
+        position: options.position,
+        ...options.rotation !== void 0 ? { rotation: options.rotation } : {}
       });
       track.mediaStreamTrack = mediaTrack;
       this.previewStream = new MediaStream([mediaTrack]);
@@ -3951,7 +4299,7 @@ var _CameraController = class _CameraController {
    */
   async switchCamera() {
     const track = this.activeTrack;
-    const position = _optionalChain([track, 'optionalAccess', _338 => _338.position]);
+    const position = _optionalChain([track, 'optionalAccess', _399 => _399.position]);
     if (!track || !position) {
       throw new XmaxError(
         "RTC_ERROR" /* rtcError */,
@@ -3969,7 +4317,7 @@ var _CameraController = class _CameraController {
       }
       this.previewStream.addTrack(mediaTrack);
     }
-    _optionalChain([this, 'access', _339 => _339.previewMirrorApplier, 'optionalCall', _340 => _340(nextPosition === "front" /* front */)]);
+    _optionalChain([this, 'access', _400 => _400.previewMirrorApplier, 'optionalCall', _401 => _401(nextPosition === "front" /* front */)]);
     this.observeMediaTrack(track, mediaTrack);
     return new RealtimeMediaStream({ id: "stream0" /* local */, videoTrack: track });
   }
@@ -4167,7 +4515,7 @@ var NetworkVideoController = class {
       this.ended = video.ended || this.ended;
       video.removeEventListener("loadedmetadata", restore);
       video.removeEventListener("error", fail);
-      _optionalChain([view, 'access', _341 => _341.setVideoURL, 'optionalCall', _342 => _342(null)]);
+      _optionalChain([view, 'access', _402 => _402.setVideoURL, 'optionalCall', _403 => _403(null)]);
     });
     view.isMirrored = false;
     view.setVideoURL(this.reference.path);
@@ -4176,7 +4524,7 @@ var NetworkVideoController = class {
    * 保存预览进度并释放该视图的地址和事件监听。
    */
   detach(view) {
-    _optionalChain([this, 'access', _343 => _343.bindings, 'access', _344 => _344.get, 'call', _345 => _345(view), 'optionalCall', _346 => _346()]);
+    _optionalChain([this, 'access', _404 => _404.bindings, 'access', _405 => _405.get, 'call', _406 => _406(view), 'optionalCall', _407 => _407()]);
     this.bindings.delete(view);
   }
 };
@@ -4205,13 +4553,13 @@ var LocalVideoController = class {
    * 准备完成的本地视频轨。
    */
   get currentTrack() {
-    return _optionalChain([this, 'access', _347 => _347.source, 'optionalAccess', _348 => _348.track]);
+    return _optionalChain([this, 'access', _408 => _408.source, 'optionalAccess', _409 => _409.track]);
   }
   /**
    * 文件音频输出；禁用音频时为空，无音轨文件的 Web Audio 输出为静音。
    */
   get audioTrack() {
-    return _optionalChain([this, 'access', _349 => _349.source, 'optionalAccess', _350 => _350.audioDestination, 'optionalAccess', _351 => _351.stream, 'access', _352 => _352.getAudioTracks, 'call', _353 => _353(), 'access', _354 => _354[0]]);
+    return _optionalChain([this, 'access', _410 => _410.source, 'optionalAccess', _411 => _411.audioDestination, 'optionalAccess', _412 => _412.stream, 'access', _413 => _413.getAudioTracks, 'call', _414 => _414(), 'access', _415 => _415[0]]);
   }
   /**
    * 校验文件和格式，准备首帧与音频输出；应从用户点击事件直接调用以解锁播放。
@@ -4264,7 +4612,7 @@ var LocalVideoController = class {
         source.audioSource.connect(source.audioDestination);
       }
       video.src = source.url;
-      const resume = _optionalChain([source, 'access', _355 => _355.audioContext, 'optionalAccess', _356 => _356.resume, 'call', _357 => _357()]);
+      const resume = _optionalChain([source, 'access', _416 => _416.audioContext, 'optionalAccess', _417 => _417.resume, 'call', _418 => _418()]);
       const playing = this.play(source, signal);
       await this.wait(source, Promise.all([resume, playing]), signal);
       video.pause();
@@ -4316,7 +4664,7 @@ var LocalVideoController = class {
    */
   async start(signal) {
     const source = this.source;
-    if (!_optionalChain([source, 'optionalAccess', _358 => _358.track])) {
+    if (!_optionalChain([source, 'optionalAccess', _419 => _419.track])) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local video is not prepared");
     }
     if (signal.aborted) {
@@ -4324,7 +4672,7 @@ var LocalVideoController = class {
     }
     try {
       await this.rewind(source, signal);
-      await this.wait(source, Promise.all([_optionalChain([source, 'access', _359 => _359.audioContext, 'optionalAccess', _360 => _360.resume, 'call', _361 => _361()]), this.play(source, signal)]), signal);
+      await this.wait(source, Promise.all([_optionalChain([source, 'access', _420 => _420.audioContext, 'optionalAccess', _421 => _421.resume, 'call', _422 => _422()]), this.play(source, signal)]), signal);
     } catch (error) {
       source.video.pause();
       throw error;
@@ -4334,7 +4682,7 @@ var LocalVideoController = class {
    * 暂停文件音视频，保留当前预览；重新开始生成时回到文件开头。
    */
   pause() {
-    _optionalChain([this, 'access', _362 => _362.source, 'optionalAccess', _363 => _363.video, 'access', _364 => _364.pause, 'call', _365 => _365()]);
+    _optionalChain([this, 'access', _423 => _423.source, 'optionalAccess', _424 => _424.video, 'access', _425 => _425.pause, 'call', _426 => _426()]);
   }
   /**
    * 释放播放器、预览、定时器、轨道、音频上下文和对象 URL。
@@ -4364,12 +4712,12 @@ var LocalVideoController = class {
     source.video.pause();
     source.video.removeAttribute("src");
     source.video.load();
-    _optionalChain([source, 'access', _366 => _366.stream, 'optionalAccess', _367 => _367.getTracks, 'call', _368 => _368(), 'access', _369 => _369.forEach, 'call', _370 => _370((track) => track.stop())]);
-    _optionalChain([source, 'access', _371 => _371.audioDestination, 'optionalAccess', _372 => _372.stream, 'access', _373 => _373.getTracks, 'call', _374 => _374(), 'access', _375 => _375.forEach, 'call', _376 => _376((track) => track.stop())]);
-    _optionalChain([source, 'access', _377 => _377.audioSource, 'optionalAccess', _378 => _378.disconnect, 'call', _379 => _379()]);
-    _optionalChain([source, 'access', _380 => _380.audioDestination, 'optionalAccess', _381 => _381.disconnect, 'call', _382 => _382()]);
+    _optionalChain([source, 'access', _427 => _427.stream, 'optionalAccess', _428 => _428.getTracks, 'call', _429 => _429(), 'access', _430 => _430.forEach, 'call', _431 => _431((track) => track.stop())]);
+    _optionalChain([source, 'access', _432 => _432.audioDestination, 'optionalAccess', _433 => _433.stream, 'access', _434 => _434.getTracks, 'call', _435 => _435(), 'access', _436 => _436.forEach, 'call', _437 => _437((track) => track.stop())]);
+    _optionalChain([source, 'access', _438 => _438.audioSource, 'optionalAccess', _439 => _439.disconnect, 'call', _440 => _440()]);
+    _optionalChain([source, 'access', _441 => _441.audioDestination, 'optionalAccess', _442 => _442.disconnect, 'call', _443 => _443()]);
     URL.revokeObjectURL(source.url);
-    await _optionalChain([source, 'access', _383 => _383.audioContext, 'optionalAccess', _384 => _384.close, 'call', _385 => _385(), 'access', _386 => _386.catch, 'call', _387 => _387(() => {
+    await _optionalChain([source, 'access', _444 => _444.audioContext, 'optionalAccess', _445 => _445.close, 'call', _446 => _446(), 'access', _447 => _447.catch, 'call', _448 => _448(() => {
     })]);
   }
   /**
@@ -4517,7 +4865,7 @@ var RealtimeContext = class {
     __publicField(this, "referencePath");
     this.referenceVideo = init.referenceVideo && Object.freeze({ ...init.referenceVideo });
     this.prompt = init.prompt.trim();
-    const normalizedReferencePath = _optionalChain([init, 'access', _388 => _388.referencePath, 'optionalAccess', _389 => _389.trim, 'call', _390 => _390()]);
+    const normalizedReferencePath = _optionalChain([init, 'access', _449 => _449.referencePath, 'optionalAccess', _450 => _450.trim, 'call', _451 => _451()]);
     this.referencePath = normalizedReferencePath || void 0;
   }
 };
@@ -4785,7 +5133,7 @@ var RealtimeSessionService = class _RealtimeSessionService {
           return;
         }
         _RealtimeSessionService.ensureSessionActive(session);
-        await _optionalChain([handlers, 'access', _391 => _391.onRefresh, 'optionalCall', _392 => _392(session)]);
+        await _optionalChain([handlers, 'access', _452 => _452.onRefresh, 'optionalCall', _453 => _453(session)]);
       } catch (error) {
         if (this.heartbeatVersion !== version) {
           return;
@@ -4998,7 +5346,7 @@ var RealtimeState = class {
    * @param other 待比较的状态。
    */
   equals(other) {
-    return this.connectionState === other.connectionState && this.sessionID === other.sessionID && this.taskID === other.taskID && _optionalChain([this, 'access', _393 => _393.reason, 'optionalAccess', _394 => _394.kind]) === _optionalChain([other, 'access', _395 => _395.reason, 'optionalAccess', _396 => _396.kind]);
+    return this.connectionState === other.connectionState && this.sessionID === other.sessionID && this.taskID === other.taskID && _optionalChain([this, 'access', _454 => _454.reason, 'optionalAccess', _455 => _455.kind]) === _optionalChain([other, 'access', _456 => _456.reason, 'optionalAccess', _457 => _457.kind]);
   }
 };
 
@@ -5043,12 +5391,13 @@ var RoomEvent = class _RoomEvent {
       event: "start",
       params: {
         ..._RoomEvent.generationParameters(options),
+        mirror: _nullishCoalesce(options.mirror, () => ( false)),
         ...options.context.referenceVideo && {
           ref_video_path: options.context.referenceVideo.path,
           sample_method: options.context.referenceVideo.sampleMethod,
           target_size: [
-            _nullishCoalesce(_optionalChain([options, 'access', _397 => _397.targetSize, 'optionalAccess', _398 => _398.width]), () => ( options.videoFormat.width)),
-            _nullishCoalesce(_optionalChain([options, 'access', _399 => _399.targetSize, 'optionalAccess', _400 => _400.height]), () => ( options.videoFormat.height))
+            _nullishCoalesce(_optionalChain([options, 'access', _458 => _458.targetSize, 'optionalAccess', _459 => _459.width]), () => ( options.videoFormat.width)),
+            _nullishCoalesce(_optionalChain([options, 'access', _460 => _460.targetSize, 'optionalAccess', _461 => _461.height]), () => ( options.videoFormat.height))
           ]
         }
       },
@@ -5495,6 +5844,7 @@ var RoomController = class {
   startGeneration(options) {
     return this.send(
       RoomEvent.start({
+        mirror: _nullishCoalesce(options.mirror, () => ( false)),
         userID: this.requireUserID(),
         taskID: options.taskID,
         videoFormat: options.videoFormat,
@@ -5592,7 +5942,7 @@ var RoomController = class {
     if (targetUserID && ownUserID && targetUserID !== ownUserID) {
       return;
     }
-    _optionalChain([this, 'access', _401 => _401.listener, 'optionalAccess', _402 => _402.onRoomMessage, 'call', _403 => _403(senderUserID, message)]);
+    _optionalChain([this, 'access', _462 => _462.listener, 'optionalAccess', _463 => _463.onRoomMessage, 'call', _464 => _464(senderUserID, message)]);
   }
   /**
    * 发送房间信令并输出日志。
@@ -5646,6 +5996,7 @@ var _EncodingController = class _EncodingController {
      * 基础层组件
      */
     __publicField(this, "rtcManager");
+    __publicField(this, "lastAppliedConfiguration");
     this.rtcManager = options.rtcManager;
   }
   /**
@@ -5681,14 +6032,38 @@ var _EncodingController = class _EncodingController {
         "Minimum bitrate must not exceed maximum bitrate after applying SDK defaults"
       );
     }
-    await this.rtcManager.configureVideoEncoding({
+    const configuration = {
       width: videoFormat.width,
       height: videoFormat.height,
       frameRate: videoFormat.fps,
       minimumBitrate: minimum,
       maximumBitrate: maximum,
       encoderPreference: ENCODER_PREFERENCE_MAP[videoFormat.encoderPreference]
+    };
+    await this.rtcManager.configureVideoEncoding(configuration);
+    this.lastAppliedConfiguration = { ...configuration };
+  }
+  /** 只替换目标帧率，保留最近成功应用的尺寸、已解析码率区间和偏好。 */
+  async updateFrameRate(fps) {
+    const previous = this.lastAppliedConfiguration;
+    if (!previous) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Apply an encoder configuration before updating frame rate");
+    }
+    const format = new RealtimeVideoFormat({
+      width: previous.width,
+      height: previous.height,
+      fps,
+      minimumBitrate: previous.minimumBitrate,
+      maximumBitrate: previous.maximumBitrate,
+      encoderPreference: previous.encoderPreference === "maintainFramerate" /* maintainFramerate */ ? "maintainFramerate" /* maintainFramerate */ : "maintainQuality" /* maintainQuality */
     });
+    format.validate();
+    if (fps !== previous.frameRate) {
+      const next = { ...previous, frameRate: fps };
+      await this.rtcManager.configureVideoEncoding(next);
+      this.lastAppliedConfiguration = next;
+    }
+    return format;
   }
   /**
    * 按像素面积与帧率计算码率区间（kbps）：流畅优先为最低，画质优先为最高。
@@ -5849,7 +6224,7 @@ var StreamController = class {
     this.roomController.setListener({
       onRoomMessage: (sender, message) => {
         this.handleNetworkVideoCompletion(sender, message);
-        _optionalChain([this, 'access', _404 => _404.roomListener, 'optionalAccess', _405 => _405.onRoomMessage, 'call', _406 => _406(sender, message)]);
+        _optionalChain([this, 'access', _465 => _465.roomListener, 'optionalAccess', _466 => _466.onRoomMessage, 'call', _467 => _467(sender, message)]);
       }
     });
     this.rtcManager.setEventListener({
@@ -5859,18 +6234,18 @@ var StreamController = class {
       onError: (error) => this.errorListener(error),
       onNetworkStatistics: (statistics) => {
         if (this.state.roomID) {
-          _optionalChain([this, 'access', _407 => _407.networkStatisticsListener, 'optionalCall', _408 => _408(statistics)]);
+          _optionalChain([this, 'access', _468 => _468.networkStatisticsListener, 'optionalCall', _469 => _469(statistics)]);
         }
       },
       onRemoteVideoStatistics: (statistics) => {
-        const userID = _optionalChain([this, 'access', _409 => _409.state, 'access', _410 => _410.activeRemoteStream, 'optionalAccess', _411 => _411.userID]);
-        _optionalChain([this, 'access', _412 => _412.remoteVideoStatisticsListener, 'optionalCall', _413 => _413(
+        const userID = _optionalChain([this, 'access', _470 => _470.state, 'access', _471 => _471.activeRemoteStream, 'optionalAccess', _472 => _472.userID]);
+        _optionalChain([this, 'access', _473 => _473.remoteVideoStatisticsListener, 'optionalCall', _474 => _474(
           userID ? statistics.find((item) => item.userID === userID) : void 0
         )]);
       },
       onLocalVideoStatistics: (statistics) => {
         if (this.state.localVideoPublished) {
-          _optionalChain([this, 'access', _414 => _414.localVideoStatisticsListener, 'optionalCall', _415 => _415(statistics)]);
+          _optionalChain([this, 'access', _475 => _475.localVideoStatisticsListener, 'optionalCall', _476 => _476(statistics)]);
         }
       },
       onCustomMessageReceived: (senderUserID, message) => {
@@ -5926,9 +6301,13 @@ var StreamController = class {
    *
    * @throws 格式无效、码率区间无效或 RTC 配置失败时抛出错误。
    */
-  async setVideoEncoderConfig(videoFormat) {
+  async updateUplinkVideoFormat(videoFormat) {
     await this.encodingController.configure(videoFormat);
   }
+  /** 不根据新帧率重新推算码率区间。 */
+  async updateUplinkFrameRate(fps) {
+    return this.encodingController.updateFrameRate(fps);
+  }
   /**
    * 加入 RTC 房间并发布本地媒体流。
    *
@@ -5943,7 +6322,7 @@ var StreamController = class {
 \u2514\u2500 roomID: ${connection.roomID}, botID: ${_nullishCoalesce(connection.botID, () => ( "(\u672A\u8BBE\u7F6E)"))}`
     );
     if (publishLocalMedia) {
-      await _optionalChain([beforePublish, 'optionalCall', _416 => _416()]);
+      await _optionalChain([beforePublish, 'optionalCall', _477 => _477()]);
       ensureActive2();
       await this.publishLocalStream(includeLocalAudio);
     }
@@ -6014,6 +6393,7 @@ var StreamController = class {
     try {
       const sending = this.roomController.startGeneration({
         taskID,
+        mirror: _nullishCoalesce(options.mirror, () => ( false)),
         videoFormat: options.videoFormat,
         targetSize: options.targetSize,
         context: options.context
@@ -6021,7 +6401,7 @@ var StreamController = class {
       const state2 = this.state;
       const sent = Promise.resolve(sending).then(async () => {
         if (this.state !== state2 || state2.generationTaskID !== taskID) return;
-        await _optionalChain([options, 'access', _417 => _417.onStartSent, 'optionalCall', _418 => _418()]);
+        await _optionalChain([options, 'access', _478 => _478.onStartSent, 'optionalCall', _479 => _479()]);
         if (this.state !== state2 || state2.generationTaskID !== taskID) return;
         for (const userID of state2.publishedRemoteUserIDs) {
           void this.handleRemoteVideoPublished(userID, true);
@@ -6087,7 +6467,7 @@ var StreamController = class {
    *
    * @throws 操作已取消、房间未就绪或信令发送失败时抛出错误。
    */
-  async changeTargetSize(taskID, targetSize, ensureActive2) {
+  async updateDownlinkVideoResolution(taskID, targetSize, ensureActive2) {
     try {
       await this.roomController.changeTargetSize({ taskID, targetSize, ensureActive: ensureActive2 });
     } catch (error) {
@@ -6156,7 +6536,7 @@ var StreamController = class {
   deliverNetworkVideoCompletion() {
     const state2 = this.state;
     const completion = state2.networkVideoCompletion;
-    if (!_optionalChain([completion, 'optionalAccess', _419 => _419.finished]) || !completion.onFinish || completion.scheduled) {
+    if (!_optionalChain([completion, 'optionalAccess', _480 => _480.finished]) || !completion.onFinish || completion.scheduled) {
       return;
     }
     completion.scheduled = true;
@@ -6165,7 +6545,7 @@ var StreamController = class {
         return;
       }
       try {
-        void Promise.resolve(_optionalChain([completion, 'access', _420 => _420.onFinish, 'optionalCall', _421 => _421()])).catch(() => {
+        void Promise.resolve(_optionalChain([completion, 'access', _481 => _481.onFinish, 'optionalCall', _482 => _482()])).catch(() => {
         });
       } catch (e23) {
       }
@@ -6176,7 +6556,7 @@ var StreamController = class {
    */
   configureRoom(options) {
     const roomID = options.roomID.trim();
-    const botID = _nullishCoalesce(_optionalChain([options, 'access', _422 => _422.botID, 'optionalAccess', _423 => _423.trim, 'call', _424 => _424()]), () => ( ""));
+    const botID = _nullishCoalesce(_optionalChain([options, 'access', _483 => _483.botID, 'optionalAccess', _484 => _484.trim, 'call', _485 => _485()]), () => ( ""));
     if (!roomID) {
       throw new XmaxError(
         "INVALID_CONFIGURATION" /* invalidConfiguration */,
@@ -6259,7 +6639,7 @@ var StreamController = class {
       return;
     }
     this.state.subscribedRemoteUserIDs.delete(trimmedUserID);
-    if (_optionalChain([this, 'access', _425 => _425.state, 'access', _426 => _426.activeRemoteStream, 'optionalAccess', _427 => _427.userID]) === trimmedUserID) {
+    if (_optionalChain([this, 'access', _486 => _486.state, 'access', _487 => _487.activeRemoteStream, 'optionalAccess', _488 => _488.userID]) === trimmedUserID) {
       await this.unsubscribeRemoteAudio(trimmedUserID);
       this.state.activeRemoteStream = void 0;
       this.clearRemoteStream();
@@ -6449,7 +6829,7 @@ var StreamController = class {
    */
   resolveGenerationStart(taskID) {
     const waiter = this.state.generationWaiter;
-    if (this.state.generationTaskID !== taskID || _optionalChain([waiter, 'optionalAccess', _428 => _428.taskID]) !== taskID) {
+    if (this.state.generationTaskID !== taskID || _optionalChain([waiter, 'optionalAccess', _489 => _489.taskID]) !== taskID) {
       return;
     }
     this.state.generationWaiter = void 0;
@@ -6461,7 +6841,7 @@ var StreamController = class {
    */
   rejectGenerationStart(taskID, error) {
     const waiter = this.state.generationWaiter;
-    if (this.state.generationTaskID !== taskID || _optionalChain([waiter, 'optionalAccess', _429 => _429.taskID]) !== taskID) {
+    if (this.state.generationTaskID !== taskID || _optionalChain([waiter, 'optionalAccess', _490 => _490.taskID]) !== taskID) {
       return;
     }
     this.state.generationWaiter = void 0;
@@ -6472,7 +6852,7 @@ var StreamController = class {
    * 通知渲染层清理远端生成流；失败仅记录日志。
    */
   clearRemoteStream() {
-    _optionalChain([this, 'access', _430 => _430.remoteVideoStatisticsListener, 'optionalCall', _431 => _431(void 0)]);
+    _optionalChain([this, 'access', _491 => _491.remoteVideoStatisticsListener, 'optionalCall', _492 => _492(void 0)]);
     try {
       this.remoteStreamListener(null);
     } catch (error) {
@@ -6509,6 +6889,195 @@ var StreamController = class {
   }
 };
 
+// src/Stream/Quality/QualityTiers.ts
+var INITIAL_QUALITY_LEVEL = 2;
+var QUALITY_TIERS = {
+  L1: { width: 1024, height: 1920, frameRate: 30 },
+  L2: { width: 768, height: 1440, frameRate: 24 },
+  L3: { width: 640, height: 1200, frameRate: 24 },
+  L4: { width: 512, height: 960, frameRate: 20 },
+  L5: { width: 384, height: 720, frameRate: 16 }
+};
+
+// src/Stream/Quality/QualityPolicy.ts
+var DEFAULT_POLICY = {
+  poorSamples: 3,
+  goodSamples: 5,
+  stabilizationMs: 4e3,
+  probeMs: 2e4,
+  upgradeCooldownMs: 6e4,
+  sampleTimeoutMs: 5e3
+};
+
+// src/Stream/Quality/QualityController.ts
+var ORDERED_QUALITY_TIERS = Object.values(QUALITY_TIERS);
+var QualityController = class {
+  constructor(apply, now = () => performance.now(), policy = {}) {
+    __publicField(this, "apply", apply);
+    __publicField(this, "now", now);
+    __publicField(this, "policy");
+    __publicField(this, "active", false);
+    __publicField(this, "index", 0);
+    __publicField(this, "good", 0);
+    __publicField(this, "poor", 0);
+    __publicField(this, "lastSampleAt");
+    __publicField(this, "stableUntil", 0);
+    __publicField(this, "upgradeAfter", 0);
+    __publicField(this, "probeUntil", 0);
+    __publicField(this, "switching", false);
+    __publicField(this, "lifecycle", new AbortController());
+    this.policy = { ...DEFAULT_POLICY, ...policy };
+    for (const value of Object.values(this.policy)) {
+      if (!Number.isFinite(value) || value < 0) throw new Error("Invalid quality policy");
+    }
+    for (const value of [this.policy.poorSamples, this.policy.goodSamples]) {
+      if (!Number.isInteger(value) || value < 1) throw new Error("Sample counts must be positive integers");
+    }
+  }
+  get snapshot() {
+    return Object.freeze({
+      active: this.active,
+      level: this.index + 1,
+      ...ORDERED_QUALITY_TIERS[this.index],
+      switching: this.switching,
+      upgradeAfter: this.upgradeAfter
+    });
+  }
+  /** 传入调用方保存的档位，不在 start 中擅自改写编码配置。 */
+  start(level = 1) {
+    if (!Number.isInteger(level) || level < 1 || level > ORDERED_QUALITY_TIERS.length) {
+      throw new Error("Unsupported quality level");
+    }
+    this.stop();
+    this.lifecycle = new AbortController();
+    this.index = level - 1;
+    this.active = true;
+    this.stableUntil = this.upgradeAfter = this.probeUntil = 0;
+  }
+  /** 取消旧会话的迟到结果；底层尚未完成时仍保持串行限制。 */
+  stop() {
+    this.active = false;
+    this.lifecycle.abort();
+    this.resetSamples();
+  }
+  /** 前台操作期间丢弃累计样本，但保留试升失败后的冷却时间。 */
+  resetSamples() {
+    this.resetCounts();
+    this.lastSampleAt = void 0;
+  }
+  /** 只接收质量事件，不得用定时器重复提交同一份缓存统计。异常由调用方记录。 */
+  async observe(quality, sampleAt = this.now()) {
+    if (!this.active || this.switching || !Number.isFinite(sampleAt)) return;
+    const now = this.now();
+    if (sampleAt > now) return;
+    if (this.lastSampleAt !== void 0) {
+      if (sampleAt <= this.lastSampleAt) return;
+      if (sampleAt - this.lastSampleAt > this.policy.sampleTimeoutMs) this.resetCounts();
+    }
+    this.lastSampleAt = sampleAt;
+    if (now - sampleAt > this.policy.sampleTimeoutMs || sampleAt < this.stableUntil) {
+      this.resetCounts();
+      return;
+    }
+    if (quality === 4 || quality === 5) {
+      this.good = 0;
+      this.poor++;
+      if (this.poor >= this.policy.poorSamples && this.index < ORDERED_QUALITY_TIERS.length - 1) {
+        return this.change(this.index + 1, now < this.probeUntil ? "failedProbe" : "poorNetwork");
+      }
+    } else if (quality === 1 || quality === 2) {
+      this.poor = 0;
+      if (sampleAt < this.upgradeAfter) {
+        this.good = 0;
+        return;
+      }
+      this.good++;
+      if (this.good >= this.policy.goodSamples && this.index > 0) {
+        return this.change(this.index - 1, "probeUpgrade");
+      }
+    } else {
+      this.resetCounts();
+    }
+    return;
+  }
+  resetCounts() {
+    this.good = this.poor = 0;
+  }
+  async change(index, reason) {
+    const lifecycle = this.lifecycle;
+    const change = { from: this.index + 1, to: index + 1, ...ORDERED_QUALITY_TIERS[index], reason };
+    this.switching = true;
+    this.resetCounts();
+    try {
+      await this.apply(change, lifecycle.signal);
+      if (lifecycle.signal.aborted) return;
+      this.index = index;
+      const now = this.now();
+      this.stableUntil = now + this.policy.stabilizationMs;
+      this.probeUntil = reason === "probeUpgrade" ? now + this.policy.probeMs : 0;
+      if (reason === "failedProbe") this.upgradeAfter = now + this.policy.upgradeCooldownMs;
+      return change;
+    } catch (error) {
+      if (!lifecycle.signal.aborted) {
+        this.stableUntil = this.now() + this.policy.stabilizationMs;
+        throw error;
+      }
+      return;
+    } finally {
+      this.switching = false;
+    }
+  }
+};
+
+// src/Stream/Quality/QualityVideoFormat.ts
+function qualityVideoSize(baseline, level) {
+  const tier = Object.values(QUALITY_TIERS)[level - 1];
+  if (!Number.isInteger(level) || !tier) throw new Error("Unsupported quality level");
+  baseline.validate();
+  const scale = tier.width / QUALITY_TIERS.L1.width;
+  const even = (value) => Math.max(2, Math.floor(value / 2) * 2);
+  return { width: even(baseline.width * scale), height: even(baseline.height * scale) };
+}
+function qualityVideoFormat(baseline, level) {
+  const size = qualityVideoSize(baseline, level);
+  const tier = Object.values(QUALITY_TIERS)[level - 1];
+  return new RealtimeVideoFormat({
+    ...baseline,
+    ...size,
+    fps: Math.min(baseline.fps, tier.frameRate)
+  });
+}
+
+// src/Stream/Quality/QualityHistory.ts
+var QualityHistory = class {
+  constructor(model) {
+    __publicField(this, "model", model);
+  }
+  /** 无记录、损坏、SSR 或浏览器禁止存储时使用默认 L2。 */
+  read(direction) {
+    try {
+      const level = Number(globalThis.localStorage.getItem(this.key(direction)));
+      if (this.isValid(level)) return level;
+    } catch (e24) {
+    }
+    return INITIAL_QUALITY_LEVEL;
+  }
+  /** 仅在应用成功后调用；下行成功表示信令已发送，不代表服务端已确认生效。 */
+  write(direction, level) {
+    if (!this.isValid(level)) return;
+    try {
+      globalThis.localStorage.setItem(this.key(direction), String(level));
+    } catch (e25) {
+    }
+  }
+  key(direction) {
+    return `xmax:quality:v1:agora:${encodeURIComponent(this.model)}:${direction}`;
+  }
+  isValid(level) {
+    return Number.isInteger(level) && level >= 1 && level <= Object.keys(QUALITY_TIERS).length;
+  }
+};
+
 // src/Core/Realtime/RealtimeCoordinator.ts
 function scopeAffects(scope, kind) {
   if (scope === 1 /* all */) {
@@ -6611,6 +7180,10 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
   get currentState() {
     return this.state;
   }
+  /** 后台自动调档仅在没有前台操作或清理时申请操作租约。 */
+  get isBusy() {
+    return this.activeOperation !== void 0 || this.termination !== void 0;
+  }
   /**
    * 设置实时状态监听器；设置后立即回放当前状态。
    *
@@ -6743,7 +7316,7 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
         }
         throw _RealtimeCoordinator.cancelledError();
       }
-      const terminationTask = await _asyncNullishCoalesce(await _asyncNullishCoalesce(operation.terminationTask, async () => ( _optionalChain([this, 'access', _432 => _432.termination, 'optionalAccess', _433 => _433.task]))), async () => ( await this.requestTermination(
+      const terminationTask = await _asyncNullishCoalesce(await _asyncNullishCoalesce(operation.terminationTask, async () => ( _optionalChain([this, 'access', _493 => _493.termination, 'optionalAccess', _494 => _494.task]))), async () => ( await this.requestTermination(
         _nullishCoalesce(operation.lease.failureScope, () => ( 0)) /* connection */,
         void 0,
         RealtimeReason.normal,
@@ -6872,7 +7445,7 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
    * 结束指定操作，释放操作准入场。
    */
   finish(operation) {
-    if (_optionalChain([this, 'access', _434 => _434.activeOperation, 'optionalAccess', _435 => _435.id]) === operation.id) {
+    if (_optionalChain([this, 'access', _495 => _495.activeOperation, 'optionalAccess', _496 => _496.id]) === operation.id) {
       this.activeOperation = void 0;
     }
   }
@@ -6884,7 +7457,7 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
       return;
     }
     this.state = nextState;
-    _optionalChain([this, 'access', _436 => _436.stateListener, 'optionalCall', _437 => _437(nextState)]);
+    _optionalChain([this, 'access', _497 => _497.stateListener, 'optionalCall', _498 => _498(nextState)]);
   }
   /**
    * 构造统一的操作取消错误。
@@ -7021,9 +7594,9 @@ var RealtimeLaunchTimer = class {
    */
   notify() {
     try {
-      void Promise.resolve(_optionalChain([this, 'access', _438 => _438.listener, 'optionalCall', _439 => _439(this.snapshot)])).catch(() => {
+      void Promise.resolve(_optionalChain([this, 'access', _499 => _499.listener, 'optionalCall', _500 => _500(this.snapshot)])).catch(() => {
       });
-    } catch (e24) {
+    } catch (e26) {
     }
   }
 };
@@ -7053,7 +7626,7 @@ var XmaxRealtimeConnectionManager = class {
    * 当前活动会话标识；尚未连接或清理完成后为空。
    */
   get currentSessionID() {
-    return _optionalChain([this, 'access', _440 => _440.activeSession, 'optionalAccess', _441 => _441.id]);
+    return _optionalChain([this, 'access', _501 => _501.activeSession, 'optionalAccess', _502 => _502.id]);
   }
   /**
    * 未配置 API 服务时在连接操作开始前报错，不影响本地预览。
@@ -7087,7 +7660,7 @@ var XmaxRealtimeConnectionManager = class {
     }
     const refreshVersion = ++this.refreshVersion;
     this.credentialController = new AbortController();
-    const videoFormat = options.localTrack.videoFormat;
+    const videoFormat = _nullishCoalesce(options.localVideoFormat, () => ( options.localTrack.videoFormat));
     if (!videoFormat) {
       throw new XmaxError(
         "INTERNAL_ERROR" /* internalError */,
@@ -7096,7 +7669,9 @@ var XmaxRealtimeConnectionManager = class {
     }
     const publishLocalMedia = _nullishCoalesce(options.publishLocalMedia, () => ( true));
     if (publishLocalMedia) {
-      await streamController.setVideoEncoderConfig(videoFormat);
+      await streamController.updateUplinkVideoFormat(videoFormat);
+      options.ensureCurrent();
+      _optionalChain([options, 'access', _503 => _503.onVideoEncoderConfigured, 'optionalCall', _504 => _504()]);
     }
     options.ensureCurrent();
     let completePublish;
@@ -7104,13 +7679,13 @@ var XmaxRealtimeConnectionManager = class {
       options.ensureCurrent();
     }, async () => {
       options.ensureCurrent();
-      await _optionalChain([options, 'access', _442 => _442.beforePublish, 'optionalCall', _443 => _443()]);
+      await _optionalChain([options, 'access', _505 => _505.beforePublish, 'optionalCall', _506 => _506()]);
       completeConnection();
       completePublish = this.dependencies.timing.startPublish();
     }, publishLocalMedia);
     options.ensureCurrent();
     completeConnection();
-    _optionalChain([completePublish, 'optionalCall', _444 => _444()]);
+    _optionalChain([completePublish, 'optionalCall', _507 => _507()]);
     options.onPublished();
     sessionService.startHeartbeat(session.id, {
       onFailure: (sessionID, error) => {
@@ -7133,24 +7708,24 @@ var XmaxRealtimeConnectionManager = class {
    * 更新已绑定远端视图的插帧配置；传 undefined 停用插帧。
    */
   setFrameInterpolation(options) {
-    _optionalChain([this, 'access', _445 => _445.remoteTarget, 'optionalAccess', _446 => _446.setFrameInterpolation, 'optionalCall', _447 => _447(options)]);
+    _optionalChain([this, 'access', _508 => _508.remoteTarget, 'optionalAccess', _509 => _509.setFrameInterpolation, 'optionalCall', _510 => _510(options)]);
   }
   /**
    * 清空远端视图的媒体流，保留轨道与视图绑定以供统一清理。
    */
   clearRemoteMedia() {
-    _optionalChain([this, 'access', _448 => _448.remoteTarget, 'optionalAccess', _449 => _449.setMediaStream, 'call', _450 => _450(null)]);
+    _optionalChain([this, 'access', _511 => _511.remoteTarget, 'optionalAccess', _512 => _512.setMediaStream, 'call', _513 => _513(null)]);
   }
   /**
    * 停止会话心跳；未配置会话服务时不执行操作。
    */
   stopHeartbeat() {
     this.refreshVersion++;
-    _optionalChain([this, 'access', _451 => _451.credentialController, 'optionalAccess', _452 => _452.abort, 'call', _453 => _453()]);
+    _optionalChain([this, 'access', _514 => _514.credentialController, 'optionalAccess', _515 => _515.abort, 'call', _516 => _516()]);
     this.credentialController = void 0;
     this.credentialRefresh = void 0;
     this.credentialApplication = Promise.resolve();
-    _optionalChain([this, 'access', _454 => _454.dependencies, 'access', _455 => _455.sessionService, 'optionalAccess', _456 => _456.stopHeartbeat, 'call', _457 => _457()]);
+    _optionalChain([this, 'access', _517 => _517.dependencies, 'access', _518 => _518.sessionService, 'optionalAccess', _519 => _519.stopHeartbeat, 'call', _520 => _520()]);
   }
   /**
    * RTC Token 过期时复用会话心跳获取新凭据，并合并同一实例的并发请求。
@@ -7158,14 +7733,14 @@ var XmaxRealtimeConnectionManager = class {
   async refreshCredentials() {
     if (this.credentialRefresh) return this.credentialRefresh;
     const current = this.activeSession;
-    if (!_optionalChain([current, 'optionalAccess', _458 => _458.connection]) || current.connection.provider === "trtc" /* trtc */) return;
+    if (!_optionalChain([current, 'optionalAccess', _521 => _521.connection]) || current.connection.provider === "trtc" /* 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 && _optionalChain([this, 'access', _459 => _459.activeSession, 'optionalAccess', _460 => _460.id]) === current.id) {
+        if (version === this.refreshVersion && _optionalChain([this, 'access', _522 => _522.activeSession, 'optionalAccess', _523 => _523.id]) === current.id) {
           this.dependencies.onHeartbeatFailure(current.id, XmaxError.from(error));
         }
       }
@@ -7182,7 +7757,7 @@ var XmaxRealtimeConnectionManager = class {
    */
   async waitUntilRemoteTrackReady(timeoutMs, signal) {
     if (signal.aborted) throw RealtimeCoordinator.cancelledError();
-    const mediaTrack = _optionalChain([this, 'access', _461 => _461.activeRemoteTrack, 'optionalAccess', _462 => _462.mediaStreamTrack]);
+    const mediaTrack = _optionalChain([this, 'access', _524 => _524.activeRemoteTrack, 'optionalAccess', _525 => _525.mediaStreamTrack]);
     if (!mediaTrack || !mediaTrack.muted) return;
     await new Promise((resolve, reject) => {
       const cleanup = () => {
@@ -7219,7 +7794,7 @@ var XmaxRealtimeConnectionManager = class {
       if (track) {
         track.mediaStreamTrack = void 0;
       }
-      _optionalChain([this, 'access', _463 => _463.remoteTarget, 'optionalAccess', _464 => _464.setMediaStream, 'call', _465 => _465(null)]);
+      _optionalChain([this, 'access', _526 => _526.remoteTarget, 'optionalAccess', _527 => _527.setMediaStream, 'call', _528 => _528(null)]);
       return;
     }
     if (!track) {
@@ -7229,7 +7804,7 @@ var XmaxRealtimeConnectionManager = class {
       );
     }
     track.mediaStreamTrack = binding.videoTrack;
-    _optionalChain([this, 'access', _466 => _466.remoteTarget, 'optionalAccess', _467 => _467.setMediaStream, 'call', _468 => _468(new MediaStream([binding.videoTrack]))]);
+    _optionalChain([this, 'access', _529 => _529.remoteTarget, 'optionalAccess', _530 => _530.setMediaStream, 'call', _531 => _531(new MediaStream([binding.videoTrack]))]);
   }
   /**
    * 为远端轨道注册渲染绑定：attach 时挂流占位，媒体轨到达后送入画面。
@@ -7242,8 +7817,8 @@ var XmaxRealtimeConnectionManager = class {
         }
       },
       attachHandler: (view) => {
-        _optionalChain([this, 'access', _469 => _469.remoteTarget, 'optionalAccess', _470 => _470.setFrameInterpolation, 'optionalCall', _471 => _471(void 0)]);
-        view.isMirrored = this.dependencies.isMirrored();
+        _optionalChain([this, 'access', _532 => _532.remoteTarget, 'optionalAccess', _533 => _533.setFrameInterpolation, 'optionalCall', _534 => _534(void 0)]);
+        view.isMirrored = false;
         this.remoteTarget = view;
         this.dependencies.onRenderAttached();
         const mediaTrack = track.mediaStreamTrack;
@@ -7254,19 +7829,11 @@ var XmaxRealtimeConnectionManager = class {
           this.dependencies.onRenderDetached();
           this.remoteTarget = void 0;
         }
-        _optionalChain([view, 'access', _472 => _472.setFrameInterpolation, 'optionalCall', _473 => _473(void 0)]);
+        _optionalChain([view, 'access', _535 => _535.setFrameInterpolation, 'optionalCall', _536 => _536(void 0)]);
         view.setMediaStream(null);
       }
     });
   }
-  /**
-   * 同步远端结果画面的镜像状态：与当前本地摄像头位置保持一致。
-   */
-  updateRemoteMirror() {
-    if (this.remoteTarget) {
-      this.remoteTarget.isMirrored = this.dependencies.isMirrored();
-    }
-  }
   /**
    * 构造当前远端生成结果媒体流。
    */
@@ -7312,7 +7879,7 @@ var XmaxRealtimeConnectionManager = class {
       return;
     }
     if (next.provider !== "trtc" /* trtc */ && (force || !previous || previous.provider === "trtc" /* trtc */ || next.roomToken !== previous.roomToken)) {
-      await this.dependencies.streamController.updateCredentials(next, _optionalChain([this, 'access', _474 => _474.credentialController, 'optionalAccess', _475 => _475.signal]));
+      await this.dependencies.streamController.updateCredentials(next, _optionalChain([this, 'access', _537 => _537.credentialController, 'optionalAccess', _538 => _538.signal]));
       if (version !== this.refreshVersion || this.activeSession !== current) return;
     }
     this.activeSession = new RealtimeSession({
@@ -7327,7 +7894,7 @@ var XmaxRealtimeConnectionManager = class {
    * 尽力清理全部连接资源，即使退房失败也关闭服务端会话。
    */
   async disconnect() {
-    const sessionID = _optionalChain([this, 'access', _476 => _476.activeSession, 'optionalAccess', _477 => _477.id]);
+    const sessionID = _optionalChain([this, 'access', _539 => _539.activeSession, 'optionalAccess', _540 => _540.id]);
     this.stopHeartbeat();
     this.clearRemoteMedia();
     try {
@@ -7410,6 +7977,8 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
         taskID,
         videoFormat: options.videoFormat,
         context,
+        ...options.targetSize && { targetSize: options.targetSize },
+        mirror: _nullishCoalesce(options.mirror, () => ( false)),
         ...options.onStartSent && { onStartSent: options.onStartSent }
       });
       await this.awaitConfirmation(confirmation, options.signal);
@@ -7436,7 +8005,8 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
     await this.streamController.updateGeneration({
       taskID,
       videoFormat: options.videoFormat,
-      context
+      context,
+      ...options.targetSize && { targetSize: options.targetSize }
     });
     if (this.activeTaskID !== taskID) throw RealtimeCoordinator.cancelledError();
     this.currentContext = context;
@@ -7462,7 +8032,7 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
     try {
       await completion;
     } finally {
-      if (_optionalChain([this, 'access', _478 => _478.pendingStop, 'optionalAccess', _479 => _479.completion]) === completion) this.pendingStop = void 0;
+      if (_optionalChain([this, 'access', _541 => _541.pendingStop, 'optionalAccess', _542 => _542.completion]) === completion) this.pendingStop = void 0;
     }
   }
   /**
@@ -7573,6 +8143,14 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     __publicField(this, "connectionManager");
     __publicField(this, "generationManager");
     __publicField(this, "streamController");
+    __publicField(this, "qualityController");
+    __publicField(this, "qualityHistory");
+    __publicField(this, "qualityStates", /* @__PURE__ */ new WeakMap());
+    __publicField(this, "downlinkQualityController");
+    /** 无服务端生效 ACK；level/size 表示最后成功发送的目标，而非实际接收规格。 */
+    __publicField(this, "downlinkQualityState");
+    __publicField(this, "adaptiveQualityPending", false);
+    __publicField(this, "adaptiveQualityRevision", 0);
     /**
      * 音量配置
      */
@@ -7581,19 +8159,19 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     this.options = options;
     this.mediaService = new MediaService(options.model);
     this.interpolationRequested = options.isFrameInterpolationEnabled;
-    this.supportsInterpolation = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _480 => _480.supportsFrameInterpolation]), () => ( (async (size) => await frameInterpolationAdapter(size) !== null)));
+    this.supportsInterpolation = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _543 => _543.supportsFrameInterpolation]), () => ( (async (size) => await frameInterpolationAdapter(size) !== null)));
     this.errorHandler = new RealtimeErrorHandler();
-    const rtcManager = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _481 => _481.rtcManager]), () => ( createRtcManager(options.provider, _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _482 => _482.environment]), () => ( "china")) /* china */)));
+    const rtcManager = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _544 => _544.rtcManager]), () => ( createRtcManager(options.provider, _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _545 => _545.environment]), () => ( "china")) /* china */)));
     this.rtcManager = rtcManager;
-    this.cameraController = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _483 => _483.cameraController]), () => ( new CameraController({
+    this.cameraController = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _546 => _546.cameraController]), () => ( new CameraController({
       rtcManager,
       mediaService: this.mediaService,
       errorListener: (error) => {
         void this.errorHandler.report(error);
       }
     })));
-    const sessionService = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _484 => _484.sessionService]), () => ( (_optionalChain([dependencies, 'optionalAccess', _485 => _485.apiService]) ? new RealtimeSessionService({ apiService: dependencies.apiService, provider: options.provider }) : void 0)));
-    this.streamController = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _486 => _486.streamController]), () => ( new StreamController({
+    const sessionService = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _547 => _547.sessionService]), () => ( (_optionalChain([dependencies, 'optionalAccess', _548 => _548.apiService]) ? new RealtimeSessionService({ apiService: dependencies.apiService, provider: options.provider }) : void 0)));
+    this.streamController = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _549 => _549.streamController]), () => ( new StreamController({
       rtcManager,
       onCredentialsRequired: () => {
         void this.connectionManager.refreshCredentials();
@@ -7611,12 +8189,11 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       sessionService,
       streamController: this.streamController,
       timing: this.launchTimer,
-      isMirrored: () => _optionalChain([this, 'access', _487 => _487.cameraController, 'access', _488 => _488.currentTrack, 'optionalAccess', _489 => _489.position]) === "front" /* front */,
       remoteAudioVolume: () => this.storedRemoteAudioVolume,
       onHeartbeatFailure: (sessionID, error) => {
         void this.handleHeartbeatFailure(sessionID, error);
       },
-      onFrameDisplayed: () => _optionalChain([this, 'access', _490 => _490.remoteFrameDisplayHandler, 'optionalCall', _491 => _491()]),
+      onFrameDisplayed: () => _optionalChain([this, 'access', _550 => _550.remoteFrameDisplayHandler, 'optionalCall', _551 => _551()]),
       onRenderAttached: () => this.applyRemoteInterpolation(),
       onRenderDetached: () => {
         this.interpolationRevision++;
@@ -7627,6 +8204,31 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       errorHandler: this.errorHandler,
       cleanup: (scope, taskID) => this.performCleanup(scope, taskID)
     });
+    if (options.provider === "agora" /* agora */) {
+      this.qualityHistory = new QualityHistory(options.model);
+      this.qualityController = new QualityController(async (change, signal) => {
+        if (signal.aborted || this.currentState.connectionState !== "Generating" /* generating */) {
+          throw new XmaxError("CANCELLED" /* cancelled */, "Adaptive video format update was cancelled");
+        }
+        await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
+          const track = _nullishCoalesce(this.localVideoController.currentTrack, () => ( this.cameraController.currentTrack));
+          const state2 = track && this.qualityStates.get(track);
+          if (!track || !state2) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Adaptive video baseline is unavailable");
+          const format = qualityVideoFormat(state2.baseline, change.to);
+          await this.streamController.updateUplinkVideoFormat(format);
+          token.ensureCurrent();
+          _nullishCoalesce(this.generationVideoFormat, () => ( (this.generationVideoFormat = state2.baseline)));
+          track.updateVideoFormat(format);
+          state2.level = change.to;
+          _optionalChain([this, 'access', _552 => _552.qualityHistory, 'optionalAccess', _553 => _553.write, 'call', _554 => _554("uplink", change.to)]);
+        });
+      });
+      this.downlinkQualityController = new QualityController(async (change, signal) => {
+        await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
+          await this.applyDownlinkQuality(change.to, token, signal);
+        });
+      });
+    }
     this.streamController.setLocalVideoStatisticsListener((statistics) => {
       if (this.acceptsVideoStatistics) {
         this.localVideoStatistics = statistics ? Object.freeze({ ...statistics }) : void 0;
@@ -7636,6 +8238,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     this.streamController.setNetworkStatisticsListener((statistics) => {
       if (this.acceptsVideoStatistics) {
         this.networkStatistics = statistics ? Object.freeze({ ...statistics }) : void 0;
+        this.handleAdaptiveQuality(statistics);
         this.notifyNetworkStatistics();
       }
     });
@@ -7663,7 +8266,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   async setFrameInterpolationEnabled(enabled) {
     await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
-      const format = _nullishCoalesce(this.generationVideoFormat, () => ( _optionalChain([this, 'access', _492 => _492.currentLocalTrack, 'optionalAccess', _493 => _493.videoFormat])));
+      const format = _nullishCoalesce(_nullishCoalesce(_optionalChain([this, 'access', _555 => _555.downlinkQualityState, 'optionalAccess', _556 => _556.size]), () => ( this.generationVideoFormat)), () => ( _optionalChain([this, 'access', _557 => _557.currentLocalTrack, 'optionalAccess', _558 => _558.videoFormat])));
       const size = format && enabled ? this.mediaService.resolveFrameInterpolationSize(format) : void 0;
       if (enabled && !await this.checkInterpolationSupport(size, token)) {
         token.ensureCurrent();
@@ -7675,6 +8278,43 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       this.applyRemoteInterpolation();
     });
   }
+  /** 手动调试与自动调档使用同一尺寸信令路径，不修改生成或上行配置。 */
+  async adjustDownlinkQuality(direction) {
+    await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
+      const controller = this.downlinkQualityController;
+      const state2 = this.downlinkQualityState;
+      if (!controller || !state2 || this.currentState.connectionState !== "Generating" /* generating */ || direction !== "upgrade" && direction !== "downgrade") {
+        throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Downlink quality adjustment requires an active Agora generation and a valid direction");
+      }
+      const level = Math.max(1, Math.min(Object.keys(QUALITY_TIERS).length, state2.level + (direction === "upgrade" ? -1 : 1)));
+      if (level === state2.level) return;
+      this.adaptiveQualityRevision++;
+      controller.resetSamples();
+      await this.applyDownlinkQuality(level, token);
+      controller.start(level);
+    });
+  }
+  async applyDownlinkQuality(level, token, signal) {
+    const state2 = this.downlinkQualityState;
+    const ensureActive2 = () => {
+      token.ensureCurrent();
+      if (_optionalChain([signal, 'optionalAccess', _559 => _559.aborted]) || !state2 || state2 !== this.downlinkQualityState || this.currentState.connectionState !== "Generating" /* generating */ || this.currentState.taskID !== state2.taskID) {
+        throw new XmaxError("CANCELLED" /* cancelled */, "Target size update was cancelled");
+      }
+    };
+    ensureActive2();
+    if (!state2) return;
+    const size = qualityVideoSize(state2.baseline, level);
+    await this.streamController.updateDownlinkVideoResolution(state2.taskID, size, ensureActive2);
+    ensureActive2();
+    state2.level = level;
+    state2.size = size;
+    _optionalChain([this, 'access', _560 => _560.qualityHistory, 'optionalAccess', _561 => _561.write, 'call', _562 => _562("downlink", level)]);
+    if (this.interpolationRequested) {
+      this.interpolationSize = size;
+      this.applyRemoteInterpolation();
+    }
+  }
   /**
    * 根据当前视频尺寸准备插帧，能力不可用时降级为原视频，并在应用前校验租约。
    */
@@ -7788,9 +8428,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   notifyRemoteVideoStatistics() {
     try {
-      void Promise.resolve(_optionalChain([this, 'access', _494 => _494.remoteVideoStatisticsListener, 'optionalCall', _495 => _495(this.remoteVideoStatistics)])).catch(() => {
+      void Promise.resolve(_optionalChain([this, 'access', _563 => _563.remoteVideoStatisticsListener, 'optionalCall', _564 => _564(this.remoteVideoStatistics)])).catch(() => {
       });
-    } catch (e25) {
+    } catch (e27) {
     }
   }
   /**
@@ -7805,9 +8445,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   notifyNetworkStatistics() {
     try {
-      void Promise.resolve(_optionalChain([this, 'access', _496 => _496.networkStatisticsListener, 'optionalCall', _497 => _497(this.networkStatistics)])).catch(() => {
+      void Promise.resolve(_optionalChain([this, 'access', _565 => _565.networkStatisticsListener, 'optionalCall', _566 => _566(this.networkStatistics)])).catch(() => {
       });
-    } catch (e26) {
+    } catch (e28) {
     }
   }
   /**
@@ -7825,15 +8465,19 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   notifyLocalVideoStatistics() {
     try {
-      void Promise.resolve(_optionalChain([this, 'access', _498 => _498.localVideoStatisticsListener, 'optionalCall', _499 => _499(this.localVideoStatistics)])).catch(() => {
+      void Promise.resolve(_optionalChain([this, 'access', _567 => _567.localVideoStatisticsListener, 'optionalCall', _568 => _568(this.localVideoStatistics)])).catch(() => {
       });
-    } catch (e27) {
+    } catch (e29) {
     }
   }
   /**
    * 停止接收媒体统计并清空各类快照，仅对曾有数据的统计发出清空通知。
    */
   clearVideoStatistics() {
+    _optionalChain([this, 'access', _569 => _569.qualityController, 'optionalAccess', _570 => _570.stop, 'call', _571 => _571()]);
+    _optionalChain([this, 'access', _572 => _572.downlinkQualityController, 'optionalAccess', _573 => _573.stop, 'call', _574 => _574()]);
+    this.downlinkQualityState = void 0;
+    this.adaptiveQualityRevision++;
     this.acceptsVideoStatistics = false;
     const hadNetworkStatistics = this.networkStatistics !== void 0;
     this.networkStatistics = void 0;
@@ -7880,6 +8524,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 将返回的轨道绑定到预览视图；收到有效帧且视图已绑定后进入 `ready`。
    *
    * @param options.enableFrameValidation 是否在发布前等待相机预热（固定 200ms），默认 true；false 跳过等待。
+   * @param options.rotation 输入帧顺时针旋转角度，默认 0；videoFormat 为旋转后的规格，目前仅 Agora 支持非零角度。
    * @returns 包含本地相机视频轨道的媒体流。
    * @throws 模型不支持相机输入、配置无效、权限或采集启动失败时抛出错误。
    */
@@ -7899,7 +8544,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         const completeCamera = this.launchTimer.startCamera();
         this.clearVideoStatistics();
         this.disposePermissionWatch();
-        const permissionWatch = await watchMediaPermissionPrompt(_nullishCoalesce(_optionalChain([options, 'optionalAccess', _500 => _500.useMicrophone]), () => ( false)));
+        const permissionWatch = await watchMediaPermissionPrompt(_nullishCoalesce(_optionalChain([options, 'optionalAccess', _575 => _575.useMicrophone]), () => ( false)));
         if (permissionWatch) {
           const completePermission = this.launchTimer.startPermission();
           void permissionWatch.decided.then(() => completePermission()).catch(() => {
@@ -7916,7 +8561,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
           throw error;
         }
         token.ensureCurrent();
-        this.generationVideoFormat = _optionalChain([stream, 'access', _501 => _501.videoTrack, 'optionalAccess', _502 => _502.videoFormat]);
+        this.generationVideoFormat = _optionalChain([stream, 'access', _576 => _576.videoTrack, 'optionalAccess', _577 => _577.videoFormat]);
         completeCamera();
         this.cameraController.setPreviewReadyHandler((isCurrent) => {
           void this.coordinator.localPreviewDidBecomeReady(isCurrent);
@@ -7937,7 +8582,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       this.clearVideoStatistics();
       await this.rtcManager.initialize();
       token.ensureCurrent();
-      this.generationVideoFormat = _optionalChain([stream, 'access', _503 => _503.videoTrack, 'optionalAccess', _504 => _504.videoFormat]);
+      this.generationVideoFormat = _optionalChain([stream, 'access', _578 => _578.videoTrack, 'optionalAccess', _579 => _579.videoFormat]);
       await this.coordinator.commit(new RealtimeState({ connectionState: "Ready" /* ready */ }), token);
       return stream;
     });
@@ -7963,7 +8608,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         audioTrack: this.localVideoController.audioTrack
       });
       token.ensureCurrent();
-      this.generationVideoFormat = _optionalChain([stream, 'access', _505 => _505.videoTrack, 'optionalAccess', _506 => _506.videoFormat]);
+      this.generationVideoFormat = _optionalChain([stream, 'access', _580 => _580.videoTrack, 'optionalAccess', _581 => _581.videoFormat]);
       await this.coordinator.commit(new RealtimeState({ connectionState: "Ready" /* ready */ }), token);
       return stream;
     });
@@ -7986,7 +8631,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 移除媒体权限弹窗观察；授权决定已记录或不再需要观察时调用。
    */
   disposePermissionWatch() {
-    _optionalChain([this, 'access', _507 => _507.permissionWatchDispose, 'optionalCall', _508 => _508()]);
+    _optionalChain([this, 'access', _582 => _582.permissionWatchDispose, 'optionalCall', _583 => _583()]);
     this.permissionWatchDispose = void 0;
   }
   /**
@@ -7995,18 +8640,94 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    *
    * @throws 无本地相机或文件视频流、参数无效、操作冲突或底层编码更新失败时抛错。
    */
-  async updateVideoFormat(videoFormat) {
+  async updateUplinkVideoFormat(videoFormat) {
     await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
       const track = _nullishCoalesce(this.localVideoController.currentTrack, () => ( this.cameraController.currentTrack));
-      const previousFormat = _optionalChain([track, 'optionalAccess', _509 => _509.videoFormat]);
+      const previousFormat = _optionalChain([track, 'optionalAccess', _584 => _584.videoFormat]);
       if (!track || !previousFormat) {
         throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local camera or file video stream is not started");
       }
       videoFormat.validate();
-      await this.streamController.setVideoEncoderConfig(videoFormat);
+      _optionalChain([this, 'access', _585 => _585.qualityController, 'optionalAccess', _586 => _586.stop, 'call', _587 => _587()]);
+      await this.streamController.updateUplinkVideoFormat(videoFormat);
       token.ensureCurrent();
       _nullishCoalesce(this.generationVideoFormat, () => ( (this.generationVideoFormat = previousFormat)));
       track.updateVideoFormat(videoFormat);
+      this.qualityStates.set(track, { baseline: videoFormat, level: 1 });
+      _optionalChain([this, 'access', _588 => _588.qualityHistory, 'optionalAccess', _589 => _589.write, 'call', _590 => _590("uplink", 1)]);
+    });
+  }
+  /** 已连接时仅替换帧率；与其他配置及生命周期操作共享同一操作租约。 */
+  async updateUplinkFrameRate(fps) {
+    await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
+      _optionalChain([this, 'access', _591 => _591.qualityController, 'optionalAccess', _592 => _592.stop, 'call', _593 => _593()]);
+      await this.applyUplinkFrameRate(fps, token);
+      const track = this.currentLocalTrack;
+      if (_optionalChain([track, 'optionalAccess', _594 => _594.videoFormat])) {
+        this.qualityStates.set(track, { baseline: track.videoFormat, level: 1 });
+        _optionalChain([this, 'access', _595 => _595.qualityHistory, 'optionalAccess', _596 => _596.write, 'call', _597 => _597("uplink", 1)]);
+      }
+    });
+  }
+  /** 手动仅调帧接口，成功后的当前格式将成为新的自适应 L1 基准。 */
+  async applyUplinkFrameRate(fps, token) {
+    const track = _nullishCoalesce(this.localVideoController.currentTrack, () => ( this.cameraController.currentTrack));
+    const previous = _optionalChain([track, 'optionalAccess', _598 => _598.videoFormat]);
+    const state2 = this.currentState.connectionState;
+    if (!track || !previous || state2 !== "Connected" /* connected */ && state2 !== "Generating" /* generating */) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Frame rate updates require a connected local camera or file stream");
+    }
+    if (!Number.isFinite(fps) || fps <= 0) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Video frame rate must be greater than zero");
+    }
+    const format = await this.streamController.updateUplinkFrameRate(fps);
+    token.ensureCurrent();
+    _nullishCoalesce(this.generationVideoFormat, () => ( (this.generationVideoFormat = previous)));
+    track.updateVideoFormat(format);
+  }
+  /** 上下行独立判断；串行应用同一原始事件，避免同时降档争抢配置租约。 */
+  handleAdaptiveQuality(statistics) {
+    const revision = ++this.adaptiveQualityRevision;
+    const controller = this.qualityController;
+    const downlink = this.downlinkQualityController;
+    if (!controller || !downlink) return;
+    const taskID = this.currentState.taskID;
+    if (this.currentState.connectionState !== "Generating" /* generating */ || !taskID) {
+      controller.stop();
+      downlink.stop();
+      return;
+    }
+    if (!statistics || this.coordinator.isBusy || this.adaptiveQualityPending) {
+      controller.resetSamples();
+      downlink.resetSamples();
+      return;
+    }
+    const track = _nullishCoalesce(this.localVideoController.currentTrack, () => ( this.cameraController.currentTrack));
+    if (!track) {
+      controller.stop();
+    } else if (!controller.snapshot.active) {
+      const format = track.videoFormat;
+      if (format) {
+        const state3 = _nullishCoalesce(this.qualityStates.get(track), () => ( { baseline: format, level: 1 }));
+        this.qualityStates.set(track, state3);
+        controller.start(state3.level);
+      }
+    }
+    const state2 = this.downlinkQualityState;
+    if (state2 && !downlink.snapshot.active) downlink.start(state2.level);
+    const sampleAt = performance.now();
+    this.adaptiveQualityPending = true;
+    void (async () => {
+      await controller.observe(statistics.uplinkQuality, sampleAt).catch(() => {
+      });
+      if (revision !== this.adaptiveQualityRevision || this.currentState.taskID !== taskID || state2 !== this.downlinkQualityState || this.currentState.connectionState !== "Generating" /* generating */ || this.coordinator.isBusy) {
+        downlink.resetSamples();
+        return;
+      }
+      await downlink.observe(statistics.downlinkQuality, sampleAt).catch(() => {
+      });
+    })().finally(() => {
+      this.adaptiveQualityPending = false;
     });
   }
   /**
@@ -8046,9 +8767,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       "cameraSwitch" /* cameraSwitch */,
       void 0,
       async (token) => {
+        _optionalChain([this, 'access', _599 => _599.qualityController, 'optionalAccess', _600 => _600.stop, 'call', _601 => _601()]);
         const stream = await this.cameraController.switchCamera();
         token.ensureCurrent();
-        this.connectionManager.updateRemoteMirror();
         return stream;
       }
     );
@@ -8116,6 +8837,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         if (currentState.connectionState === "Generating" /* generating */) {
           await this.generationManager.update(currentState.taskID, {
             videoFormat,
+            targetSize: this.downlinkQualityController ? _optionalChain([this, 'access', _602 => _602.downlinkQualityState, 'optionalAccess', _603 => _603.size]) : void 0,
             context: options.context
           });
           token.ensureCurrent();
@@ -8153,6 +8875,15 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     this.clearVideoStatistics();
     await this.coordinator.terminate(1 /* all */);
   }
+  /** 仅为尚无档位记录的本地上行选择初始档位；不应用配置或覆盖重连状态。 */
+  resolveInitialUplinkQuality(track) {
+    if (!this.qualityController) return void 0;
+    if (this.networkVideoController.currentTrack) return void 0;
+    if (this.qualityStates.has(track)) return void 0;
+    const baseline = track.videoFormat;
+    if (!baseline) return void 0;
+    return { baseline, level: this.qualityHistory.read("uplink") };
+  }
   /**
    * 建立实时连接：创建会话、进房发布、启动心跳并准备远端渲染轨道。
    *
@@ -8188,9 +8919,19 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         });
         beforePublish = () => cameraReady;
       }
+      const initialQuality = this.resolveInitialUplinkQuality(localTrack);
+      const initialFormat = initialQuality ? qualityVideoFormat(initialQuality.baseline, initialQuality.level) : void 0;
       const remote = await this.connectionManager.connect({
         localTrack,
-        remoteVideoFormat: this.generationVideoFormat,
+        remoteVideoFormat: _nullishCoalesce(this.generationVideoFormat, () => ( localTrack.videoFormat)),
+        localVideoFormat: initialFormat,
+        onVideoEncoderConfigured: () => {
+          if (!initialQuality || !initialFormat) return;
+          _nullishCoalesce(this.generationVideoFormat, () => ( (this.generationVideoFormat = initialQuality.baseline)));
+          localTrack.updateVideoFormat(initialFormat);
+          this.qualityStates.set(localTrack, initialQuality);
+          _optionalChain([this, 'access', _604 => _604.qualityHistory, 'optionalAccess', _605 => _605.write, 'call', _606 => _606("uplink", initialQuality.level)]);
+        },
         model: this.options.model,
         includeLocalAudio: this.localVideoController.isActive ? this.localVideoController.audioTrack !== void 0 : !this.networkVideoController.currentTrack && this.cameraController.useMicrophone,
         publishLocalMedia: !this.networkVideoController.currentTrack,
@@ -8218,14 +8959,18 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   async performStartGeneration(token, videoFormat, context) {
     token.setFailureScope(0 /* connection */);
-    await this.prepareFrameInterpolation(videoFormat, token);
+    const initialLevel = _nullishCoalesce(_optionalChain([this, 'access', _607 => _607.qualityHistory, 'optionalAccess', _608 => _608.read, 'call', _609 => _609("downlink")]), () => ( 1));
+    const targetSize = this.downlinkQualityController ? qualityVideoSize(videoFormat, initialLevel) : void 0;
+    await this.prepareFrameInterpolation(_nullishCoalesce(targetSize, () => ( videoFormat)), token);
     const completeFirstFrame = this.launchTimer.startFirstFrame();
     this.remoteFrameDisplayHandler = () => {
       if (!token.signal.aborted) completeFirstFrame();
     };
     const taskID = await this.generationManager.start({
       videoFormat,
+      targetSize,
       context,
+      mirror: this.currentLocalTrack === this.cameraController.currentTrack && _optionalChain([this, 'access', _610 => _610.cameraController, 'access', _611 => _611.currentTrack, 'optionalAccess', _612 => _612.position]) === "front" /* front */,
       signal: token.signal,
       ensureCurrent: () => token.ensureCurrent(),
       onStartSent: this.localVideoController.isActive ? async () => {
@@ -8242,10 +8987,18 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     if (!sessionID) {
       throw new XmaxError("SESSION_ERROR" /* sessionError */, "Realtime session is unavailable");
     }
+    _optionalChain([this, 'access', _613 => _613.downlinkQualityController, 'optionalAccess', _614 => _614.stop, 'call', _615 => _615()]);
+    this.downlinkQualityState = {
+      taskID,
+      baseline: videoFormat,
+      level: initialLevel,
+      size: _nullishCoalesce(targetSize, () => ( { width: videoFormat.width, height: videoFormat.height }))
+    };
     await this.coordinator.commit(
       new RealtimeState({ connectionState: "Generating" /* generating */, sessionID, taskID }),
       token
     );
+    _optionalChain([this, 'access', _616 => _616.qualityHistory, 'optionalAccess', _617 => _617.write, 'call', _618 => _618("downlink", initialLevel)]);
     const onFinish = this.networkVideoController.onFinish;
     if (this.networkVideoController.currentTrack) {
       this.streamController.activateNetworkVideoCompletion(onFinish && (() => {
@@ -8397,7 +9150,7 @@ var NonRealtimeTaskService = class {
    * 提交一次任务；请求结果不确定时也不自动重试，以免重复扣费。
    */
   async submitTask(options) {
-    const model = _optionalChain([options, 'access', _510 => _510.model, 'optionalAccess', _511 => _511.trim, 'call', _512 => _512()]);
+    const model = _optionalChain([options, 'access', _619 => _619.model, 'optionalAccess', _620 => _620.trim, 'call', _621 => _621()]);
     if (!model) {
       invalid("Model must not be empty");
     }
@@ -8490,7 +9243,7 @@ function validateURL(value) {
   let url;
   try {
     url = new URL(value.trim());
-  } catch (e28) {
+  } catch (e30) {
     return invalid("Resource must be an uploaded HTTP(S) URL");
   }
   if (!["https:", "http:"].includes(url.protocol) || url.username || url.password) {
@@ -8537,7 +9290,7 @@ function parseTask(value) {
   const uid = field(data, "uid", "string");
   const status = field(data, "status", "string");
   const quality = field(data, "quality", "string");
-  if (!_optionalChain([uid, 'optionalAccess', _513 => _513.trim, 'call', _514 => _514()]) || !Object.values(NonRealtimeTaskStatus).includes(status)) {
+  if (!_optionalChain([uid, 'optionalAccess', _622 => _622.trim, 'call', _623 => _623()]) || !Object.values(NonRealtimeTaskStatus).includes(status)) {
     malformed("Missing task UID or invalid status");
   }
   if (quality !== void 0 && !Object.values(NonRealtimeQuality).includes(quality)) {
@@ -8619,7 +9372,7 @@ var XmaxNonRealtimeManager = class {
    * 取得任务快照，不把服务端失败终态当成查询失败。
    */
   getTask(taskUid, options) {
-    return this.tasks.getTask(taskUid, _optionalChain([options, 'optionalAccess', _515 => _515.signal]));
+    return this.tasks.getTask(taskUid, _optionalChain([options, 'optionalAccess', _624 => _624.signal]));
   }
   /**
    * 批量取得任务快照。
@@ -8653,8 +9406,8 @@ var XmaxNonRealtimeManager = class {
     const controller = new AbortController();
     let timedOut = false;
     const abort = () => controller.abort();
-    _optionalChain([options, 'access', _516 => _516.signal, 'optionalAccess', _517 => _517.addEventListener, 'call', _518 => _518("abort", abort, { once: true })]);
-    if (_optionalChain([options, 'access', _519 => _519.signal, 'optionalAccess', _520 => _520.aborted])) {
+    _optionalChain([options, 'access', _625 => _625.signal, 'optionalAccess', _626 => _626.addEventListener, 'call', _627 => _627("abort", abort, { once: true })]);
+    if (_optionalChain([options, 'access', _628 => _628.signal, 'optionalAccess', _629 => _629.aborted])) {
       abort();
     }
     const timer = options.timeoutMs === void 0 ? void 0 : setTimeout(() => {
@@ -8680,9 +9433,9 @@ var XmaxNonRealtimeManager = class {
         ensureActive(controller.signal);
         failures = 0;
         try {
-          void Promise.resolve(_optionalChain([options, 'access', _521 => _521.onTaskUpdated, 'optionalCall', _522 => _522(task)])).catch(() => {
+          void Promise.resolve(_optionalChain([options, 'access', _630 => _630.onTaskUpdated, 'optionalCall', _631 => _631(task)])).catch(() => {
           });
-        } catch (e29) {
+        } catch (e31) {
         }
         ensureActive(controller.signal);
         if (task.status === "error" /* error */) {
@@ -8710,7 +9463,7 @@ var XmaxNonRealtimeManager = class {
       throw error;
     } finally {
       clearTimeout(timer);
-      _optionalChain([options, 'access', _523 => _523.signal, 'optionalAccess', _524 => _524.removeEventListener, 'call', _525 => _525("abort", abort)]);
+      _optionalChain([options, 'access', _632 => _632.signal, 'optionalAccess', _633 => _633.removeEventListener, 'call', _634 => _634("abort", abort)]);
     }
   }
 };
@@ -8754,13 +9507,13 @@ function isTransient(error) {
 }
 function isResultAvailable(task) {
   const result = task.result;
-  if (!_optionalChain([result, 'optionalAccess', _526 => _526.url, 'optionalAccess', _527 => _527.trim, 'call', _528 => _528()]) || _optionalChain([result, 'access', _529 => _529.uploadError, 'optionalAccess', _530 => _530.trim, 'call', _531 => _531()]) || result.uploadStatus !== void 0 && result.uploadStatus !== "success") {
+  if (!_optionalChain([result, 'optionalAccess', _635 => _635.url, 'optionalAccess', _636 => _636.trim, 'call', _637 => _637()]) || _optionalChain([result, 'access', _638 => _638.uploadError, 'optionalAccess', _639 => _639.trim, 'call', _640 => _640()]) || result.uploadStatus !== void 0 && result.uploadStatus !== "success") {
     return false;
   }
   try {
     const url = new URL(result.url);
     return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password;
-  } catch (e30) {
+  } catch (e32) {
     return false;
   }
 }
@@ -8884,6 +9637,146 @@ var VideoContentMode = /* @__PURE__ */ ((VideoContentMode2) => {
   return VideoContentMode2;
 })(VideoContentMode || {});
 
+// src/Render/Video/RenderStatisticsController.ts
+var RenderStatisticsController = class {
+  /**
+   * 绑定用于观察原视频帧的元素，调用 start 后才开始采集。
+   */
+  constructor(video) {
+    __publicField(this, "video", video);
+    /**
+     * 统计回调
+     */
+    __publicField(this, "handler");
+    /**
+     * 帧观察与采样生命周期
+     */
+    __publicField(this, "timer");
+    __publicField(this, "callbackID");
+    __publicField(this, "sequence", 0);
+    /**
+     * 采样窗口与输出方式
+     */
+    __publicField(this, "startedAt", 0);
+    __publicField(this, "originalFrames", 0);
+    __publicField(this, "interpolatedFrames", 0);
+    __publicField(this, "interpolationActive", false);
+    __publicField(this, "previousPresentedFrames");
+  }
+  /**
+   * 独立于统计面板可见性采集；没有监听者时不占用定时器。
+   */
+  start() {
+    if (this.timer !== void 0 || !this.video.srcObject && !this.video.getAttribute("src") || !this.handler || typeof this.video.requestVideoFrameCallback !== "function") {
+      return;
+    }
+    this.reset();
+    const sequence = this.sequence;
+    const observe = () => {
+      this.callbackID = this.video.requestVideoFrameCallback((_now, metadata) => {
+        if (sequence !== this.sequence) {
+          return;
+        }
+        this.callbackID = void 0;
+        if (!this.interpolationActive && !document.hidden) {
+          this.recordVideoFrames(metadata.presentedFrames);
+        } else {
+          this.previousPresentedFrames = void 0;
+        }
+        observe();
+      });
+    };
+    observe();
+    this.timer = setInterval(() => this.sample(), 1e3);
+  }
+  /**
+   * 切换输出方式并清空采样窗口，避免原视频和画布重复计数。
+   */
+  setInterpolationActive(active) {
+    this.interpolationActive = active;
+    this.reset();
+  }
+  /**
+   * 记录实际提交到画布的原帧或插值帧，不统计未呈现的计算结果。
+   */
+  recordCanvasFrame(interpolated) {
+    if (interpolated) {
+      this.interpolatedFrames++;
+    } else {
+      this.originalFrames++;
+    }
+  }
+  /**
+   * 按浏览器累计呈现帧数的增量统计，包含两次回调之间已呈现但未回调的帧。
+   */
+  recordVideoFrames(presentedFrames) {
+    if (!Number.isSafeInteger(presentedFrames) || presentedFrames < 0) {
+      this.previousPresentedFrames = void 0;
+      return;
+    }
+    const previous = this.previousPresentedFrames;
+    this.previousPresentedFrames = presentedFrames;
+    if (previous === void 0 || presentedFrames < previous) {
+      this.originalFrames += presentedFrames > 0 ? 1 : 0;
+      return;
+    }
+    this.originalFrames += presentedFrames - previous;
+  }
+  /**
+   * 取消采样及帧观察，忽略已排队的旧回调并清空对外统计。
+   */
+  stop() {
+    this.sequence++;
+    clearInterval(this.timer);
+    this.timer = void 0;
+    if (this.callbackID !== void 0) {
+      this.video.cancelVideoFrameCallback(this.callbackID);
+    }
+    this.callbackID = void 0;
+    this.reset();
+  }
+  /**
+   * 清空采样计数，避免换流或切换输出方式时混入旧数据。
+   */
+  reset() {
+    this.startedAt = performance.now();
+    this.originalFrames = 0;
+    this.interpolatedFrames = 0;
+    this.previousPresentedFrames = void 0;
+    this.notify(void 0);
+  }
+  /**
+   * 按实际经过的时间计算帧率；没有新呈现时输出 0，后台页面不报告帧率。
+   */
+  sample() {
+    const now = performance.now();
+    const seconds = (now - this.startedAt) / 1e3;
+    if (document.hidden || seconds <= 0) {
+      this.reset();
+      return;
+    }
+    const statistics = Object.freeze({
+      source: this.interpolationActive ? "canvas" : "video",
+      frameRate: (this.originalFrames + this.interpolatedFrames) / seconds,
+      originalFrameRate: this.originalFrames / seconds,
+      interpolatedFrameRate: this.interpolatedFrames / seconds
+    });
+    this.startedAt = now;
+    this.originalFrames = 0;
+    this.interpolatedFrames = 0;
+    this.notify(statistics);
+  }
+  /**
+   * 隔离接入方回调异常，避免影响播放和后续采样。
+   */
+  notify(statistics) {
+    try {
+      _optionalChain([this, 'access', _641 => _641.handler, 'optionalCall', _642 => _642(statistics)]);
+    } catch (e33) {
+    }
+  }
+};
+
 // ../../node_modules/.pnpm/framegen@1.4.0/node_modules/framegen/rt.js
 var WG = 8;
 var texBgSeq = 0;
@@ -11006,11 +11899,11 @@ var _FrameInterpolationManager = class _FrameInterpolationManager {
     if (this.destroyed) return;
     this.destroyed = true;
     this.device.removeEventListener("uncapturederror", this.onGPUError);
-    _optionalChain([this, 'access', _532 => _532.runtime, 'optionalAccess', _533 => _533.destroy, 'call', _534 => _534()]);
+    _optionalChain([this, 'access', _643 => _643.runtime, 'optionalAccess', _644 => _644.destroy, 'call', _645 => _645()]);
     this.runtime = void 0;
     this.textures.forEach((texture) => texture.destroy());
     this.textures = [];
-    _optionalChain([this, 'access', _535 => _535.context, 'optionalAccess', _536 => _536.unconfigure, 'call', _537 => _537()]);
+    _optionalChain([this, 'access', _646 => _646.context, 'optionalAccess', _647 => _647.unconfigure, 'call', _648 => _648()]);
     this.device.destroy();
   }
 };
@@ -11047,6 +11940,10 @@ var RemoteVideoFramePipeline = class {
     __publicField(this, "previousPresented");
     __publicField(this, "slowPairs", 0);
     __publicField(this, "active", false);
+    /**
+     * 帧时间基准：媒体时间异常后，本管线持续使用回调时钟，避免反复切换。
+     */
+    __publicField(this, "timeSource", "mediaTime");
     /** vsync 显示节拍：弹出到点的帧并显示最新的一张。 */
     __publicField(this, "tick", (now) => {
       if (this.stopped) return;
@@ -11093,8 +11990,8 @@ var RemoteVideoFramePipeline = class {
       if (!this.loading) void this.initialize();
       return;
     }
-    const time = metadata.mediaTime * 1e3;
-    if (!Number.isFinite(time) || this.previousTime !== void 0 && time <= this.previousTime) return;
+    const time = this.resolveFrameTime(now, metadata);
+    if (time === void 0) return;
     const previous = this.previousTime;
     const interval = previous === void 0 ? 0 : time - previous;
     const consecutive = this.previousPresented === void 0 || metadata.presentedFrames === this.previousPresented + 1;
@@ -11119,6 +12016,22 @@ var RemoteVideoFramePipeline = class {
     }
     this.interpolate(previousSlot, slot, previous, time, interval);
   }
+  /**
+   * 优先使用媒体时间；新帧的媒体时间异常时切换到单调回调时钟。
+   */
+  resolveFrameTime(now, metadata) {
+    if (this.previousPresented !== void 0 && metadata.presentedFrames <= this.previousPresented) {
+      return void 0;
+    }
+    let time = this.timeSource === "mediaTime" ? metadata.mediaTime * 1e3 : now;
+    if (!Number.isFinite(time) || this.previousTime !== void 0 && time <= this.previousTime) {
+      if (this.timeSource === "callback" || !Number.isFinite(now)) return void 0;
+      this.timeSource = "callback";
+      this.resetTimeline(true);
+      time = now;
+    }
+    return time;
+  }
   /** 帧按显示时间升序入队；同一时间的内容后到先出。 */
   enqueue(frame) {
     const index = this.queue.findIndex((queued) => queued.time >= frame.time);
@@ -11145,8 +12058,10 @@ var RemoteVideoFramePipeline = class {
         this.fail(new Error("Interpolation exceeded the GPU frame budget for 5 consecutive pairs"));
         return;
       }
-      if (this.position(performance.now()) >= midpoint) return;
-      this.enqueue({ slot, time: midpoint });
+      if (this.position(performance.now()) >= midpoint) {
+        return;
+      }
+      this.enqueue({ slot, time: midpoint, interpolated: true });
     }).catch((error) => {
       if (!this.stopped) this.fail(error);
     });
@@ -11165,6 +12080,7 @@ var RemoteVideoFramePipeline = class {
     this.displayedTime = frame.time;
     this.canvas.style.visibility = "visible";
     this.setActive(true);
+    _optionalChain([this, 'access', _649 => _649.options, 'access', _650 => _650.onFramePresented, 'optionalCall', _651 => _651(_nullishCoalesce(frame.interpolated, () => ( false)))]);
   }
   async initialize() {
     this.loading = true;
@@ -11192,13 +12108,15 @@ var RemoteVideoFramePipeline = class {
   setActive(active) {
     if (active === this.active) return;
     this.active = active;
-    _optionalChain([this, 'access', _538 => _538.options, 'access', _539 => _539.onActiveChange, 'optionalCall', _540 => _540(active)]);
+    _optionalChain([this, 'access', _652 => _652.options, 'access', _653 => _653.onActiveChange, 'optionalCall', _654 => _654(active)]);
   }
-  resetTimeline() {
+  resetTimeline(preserveGpuTimeout = false) {
     this.generation++;
     this.queue = [];
-    clearTimeout(this.stallTimer);
-    this.stallTimer = void 0;
+    if (!preserveGpuTimeout) {
+      clearTimeout(this.stallTimer);
+      this.stallTimer = void 0;
+    }
     if (this.raf !== void 0) cancelAnimationFrame(this.raf);
     this.raf = void 0;
     this.anchor = void 0;
@@ -11223,7 +12141,7 @@ var RemoteVideoFramePipeline = class {
     this.callback = void 0;
     clearTimeout(this.initializationTimer);
     this.resetTimeline();
-    _optionalChain([this, 'access', _541 => _541.processor, 'optionalAccess', _542 => _542.destroy, 'call', _543 => _543()]);
+    _optionalChain([this, 'access', _655 => _655.processor, 'optionalAccess', _656 => _656.destroy, 'call', _657 => _657()]);
     this.processor = void 0;
   }
 };
@@ -11277,16 +12195,21 @@ var XmaxVideoView = class {
     __publicField(this, "interpolationOptions");
     __publicField(this, "interpolationPipeline");
     __publicField(this, "interpolationCanvas");
+    /**
+     * 呈现统计组件
+     */
+    __publicField(this, "statisticsController");
     /**
      * DOM 挂载状态
      */
     __publicField(this, "detached", false);
-    this.contentMode = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _544 => _544.videoContentMode]), () => ( "fill")) /* fill */;
+    this.contentMode = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _658 => _658.videoContentMode]), () => ( "fill")) /* fill */;
     this.element = document.createElement("div");
     this.element.style.position = "relative";
     this.element.style.overflow = "hidden";
     this.element.style.backgroundColor = "black";
     this.videoElement = document.createElement("video");
+    this.statisticsController = new RenderStatisticsController(this.videoElement);
     this.videoElement.autoplay = true;
     this.videoElement.playsInline = true;
     this.videoElement.muted = true;
@@ -11303,6 +12226,20 @@ var XmaxVideoView = class {
   get track() {
     return this.currentTrack;
   }
+  /**
+   * 每秒接收当前视图的呈现统计；换流、卸载或不可统计时返回 undefined。
+   */
+  get renderStatisticsHandler() {
+    return this.statisticsController.handler;
+  }
+  /**
+   * 更新统计回调，不影响播放；移除回调时停止采集。
+   */
+  set renderStatisticsHandler(handler) {
+    this.statisticsController.handler = handler;
+    this.statisticsController.stop();
+    this.startRenderStatistics();
+  }
   /**
    * 解绑旧轨道后接入新轨道，并为新内容重新启用一次性首帧通知。
    */
@@ -11362,6 +12299,7 @@ var XmaxVideoView = class {
       });
     }
     this.startInterpolation();
+    this.startRenderStatistics();
     if ((this.videoElement.srcObject || this.videoElement.getAttribute("src")) && !this.hasNotifiedFrameDisplay) {
       this.armFrameDisplayNotification();
     }
@@ -11371,6 +12309,7 @@ var XmaxVideoView = class {
    */
   detach() {
     this.detached = true;
+    this.statisticsController.stop();
     this.stopInterpolation();
     this.cancelFrameDisplayNotification();
     if (this.videoElement.getAttribute("src")) {
@@ -11382,6 +12321,7 @@ var XmaxVideoView = class {
    * 设置网络视频预览；静音播放一次，不捕获或发布媒体轨道。 @internal
    */
   setVideoURL(url) {
+    this.statisticsController.stop();
     this.stopInterpolation();
     this.cancelFrameDisplayNotification();
     this.hasNotifiedFrameDisplay = false;
@@ -11395,6 +12335,7 @@ var XmaxVideoView = class {
       this.armFrameDisplayNotification();
     }
     this.videoElement.load();
+    this.startRenderStatistics();
   }
   /**
    * 直接设置渲染用的媒体流（绑定管线和直接渲染共用）。 @internal
@@ -11403,6 +12344,7 @@ var XmaxVideoView = class {
     if (this.videoElement.srcObject === stream) {
       return;
     }
+    this.statisticsController.stop();
     this.stopInterpolation();
     this.cancelFrameDisplayNotification();
     this.hasNotifiedFrameDisplay = false;
@@ -11411,6 +12353,7 @@ var XmaxVideoView = class {
       this.videoElement.autoplay = true;
       this.armFrameDisplayNotification();
       this.startInterpolation();
+      this.startRenderStatistics();
     }
   }
   /**
@@ -11440,7 +12383,18 @@ var XmaxVideoView = class {
     this.interpolationCanvas = canvas;
     this.applyContentMode();
     this.element.appendChild(canvas);
-    const pipeline = new RemoteVideoFramePipeline(this.videoElement, canvas, this.interpolationOptions);
+    const options = this.interpolationOptions;
+    const pipeline = new RemoteVideoFramePipeline(this.videoElement, canvas, {
+      ...options,
+      onActiveChange: (active) => {
+        this.statisticsController.setInterpolationActive(active);
+        _optionalChain([options, 'access', _659 => _659.onActiveChange, 'optionalCall', _660 => _660(active)]);
+      },
+      onFramePresented: (interpolated) => {
+        this.statisticsController.recordCanvasFrame(interpolated);
+        _optionalChain([options, 'access', _661 => _661.onFramePresented, 'optionalCall', _662 => _662(interpolated)]);
+      }
+    });
     this.interpolationPipeline = pipeline;
     pipeline.start();
   }
@@ -11450,8 +12404,8 @@ var XmaxVideoView = class {
   stopInterpolation() {
     const pipeline = this.interpolationPipeline;
     this.interpolationPipeline = void 0;
-    _optionalChain([pipeline, 'optionalAccess', _545 => _545.stop, 'call', _546 => _546()]);
-    _optionalChain([this, 'access', _547 => _547.interpolationCanvas, 'optionalAccess', _548 => _548.remove, 'call', _549 => _549()]);
+    _optionalChain([pipeline, 'optionalAccess', _663 => _663.stop, 'call', _664 => _664()]);
+    _optionalChain([this, 'access', _665 => _665.interpolationCanvas, 'optionalAccess', _666 => _666.remove, 'call', _667 => _667()]);
     this.interpolationCanvas = void 0;
   }
   /**
@@ -11475,9 +12429,10 @@ var XmaxVideoView = class {
    * 解绑当前轨道并清空渲染内容。
    */
   detachCurrentTrack() {
+    this.statisticsController.stop();
     const track = this.currentTrack;
     if (track) {
-      _optionalChain([VideoRenderRegistry, 'access', _550 => _550.binding, 'call', _551 => _551(track), 'optionalAccess', _552 => _552.detachHandler, 'call', _553 => _553(this)]);
+      _optionalChain([VideoRenderRegistry, 'access', _668 => _668.binding, 'call', _669 => _669(track), 'optionalAccess', _670 => _670.detachHandler, 'call', _671 => _671(this)]);
     }
     this.setFrameInterpolation(void 0);
     this.cancelFrameDisplayNotification();
@@ -11500,8 +12455,8 @@ var XmaxVideoView = class {
       }
       this.hasNotifiedFrameDisplay = true;
       this.cancelFrameDisplayNotification();
-      _optionalChain([binding, 'optionalAccess', _554 => _554.frameDisplayHandler, 'optionalCall', _555 => _555()]);
-      _optionalChain([this, 'access', _556 => _556.frameDisplayHandler, 'optionalCall', _557 => _557()]);
+      _optionalChain([binding, 'optionalAccess', _672 => _672.frameDisplayHandler, 'optionalCall', _673 => _673()]);
+      _optionalChain([this, 'access', _674 => _674.frameDisplayHandler, 'optionalCall', _675 => _675()]);
     };
     if (typeof this.videoElement.requestVideoFrameCallback === "function") {
       this.videoFrameCallbackID = this.videoElement.requestVideoFrameCallback(notify);
@@ -11540,6 +12495,12 @@ var XmaxVideoView = class {
       this.interpolationCanvas.style.transform = this.mirrored ? "scaleX(-1)" : "";
     }
   }
+  /**
+   * 视图未卸载时启动呈现统计，采样及媒体就绪检查由统计组件负责。
+   */
+  startRenderStatistics() {
+    if (!this.detached) this.statisticsController.start();
+  }
 };
 
 // src/Render/Video/XmaxRealtimeVideoView.ts
@@ -11571,9 +12532,9 @@ var XmaxRealtimeVideoView = class {
     __publicField(this, "currentLocalTrack");
     __publicField(this, "currentRemoteTrack");
     __publicField(this, "contentMode");
-    this.contentMode = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _558 => _558.videoContentMode]), () => ( "fill")) /* fill */;
-    this.currentLocalTrack = _optionalChain([options, 'optionalAccess', _559 => _559.localTrack]);
-    this.currentRemoteTrack = _optionalChain([options, 'optionalAccess', _560 => _560.remoteTrack]);
+    this.contentMode = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _676 => _676.videoContentMode]), () => ( "fill")) /* fill */;
+    this.currentLocalTrack = _optionalChain([options, 'optionalAccess', _677 => _677.localTrack]);
+    this.currentRemoteTrack = _optionalChain([options, 'optionalAccess', _678 => _678.remoteTrack]);
     this.element = document.createElement("div");
     this.element.style.position = "relative";
     this.element.style.overflow = "hidden";
@@ -11739,4 +12700,4 @@ var XmaxRealtimeVideoView = class {
 
 
 exports.XmaxEnvironment = XmaxEnvironment; exports.apiBaseURL = apiBaseURL; exports.XmaxLoggerOption = XmaxLoggerOption; exports.XmaxLogger = XmaxLogger; exports.XmaxErrorCode = XmaxErrorCode; exports.XmaxError = XmaxError; exports.RealtimeVideoEncoderPreference = RealtimeVideoEncoderPreference; exports.RealtimeVideoFormat = RealtimeVideoFormat; exports.RtcProvider = RtcProvider; exports.RealtimeModel = RealtimeModel; exports.modelDisplayName = modelDisplayName; exports.defaultFrameRate = defaultFrameRate; exports.defaultCameraVideoFormat = defaultCameraVideoFormat; exports.supportedRtcProviders = supportedRtcProviders; exports.MediaService = MediaService; exports.StoredFile = StoredFile; exports.StorageService = StorageService; exports.CameraPosition = CameraPosition; exports.RealtimeVideoTrack = RealtimeVideoTrack; exports.RealtimeMediaStream = RealtimeMediaStream; exports.RealtimeVideoSampleMethod = RealtimeVideoSampleMethod; exports.RealtimeContext = RealtimeContext; exports.RealtimeConnectionState = RealtimeConnectionState; exports.RealtimeReason = RealtimeReason; exports.RealtimeState = RealtimeState; exports.XmaxConfiguration = XmaxConfiguration; exports.NonRealtimeQuality = NonRealtimeQuality; exports.NonRealtimeTaskStatus = NonRealtimeTaskStatus; exports.NonRealtimeTaskError = NonRealtimeTaskError; exports.XmaxClient = XmaxClient; exports.RealtimeConfiguration = RealtimeConfiguration; exports.VideoContentMode = VideoContentMode; exports.XmaxVideoView = XmaxVideoView; exports.XmaxRealtimeVideoView = XmaxRealtimeVideoView;
-//# sourceMappingURL=chunk-JN6HURTT.cjs.map
+//# sourceMappingURL=chunk-EKOYOFES.cjs.map