@xmaxai/web-sdk 1.0.9 → 1.0.10

package/dist/{chunk-ILZL4W2G.js → chunk-LOYJFYQT.js}

@@ -205,7 +205,7 @@ var XmaxError = class _XmaxError extends Error {
 };
 
 // src/Foundation/Runtime/RuntimeInfo.ts
-var XMAX_SDK_VERSION = "1.0.9";
+var XMAX_SDK_VERSION = "1.0.10";
 var _RuntimeInfo = class _RuntimeInfo {
   /**
    * 序列化为接口传输使用的 snake_case 字段。
@@ -501,7 +501,7 @@ var RealtimeVideoFormat = class _RealtimeVideoFormat {
    * @param init.width 视频宽度，单位为像素。
    * @param init.height 视频高度，单位为像素。
    * @param init.fps 视频帧率，必须大于 0。
-   * @param init.minimumBitrate 最低上传码率，单位为 kbps；缺省按最终上传尺寸和帧率计算。
+   * @param init.minimumBitrate 最低上传码率，单位为 kbps；缺省为 100，仅支持该参数的 RTC 链路生效。
    * @param init.maximumBitrate 最高上传码率，单位为 kbps；缺省按最终上传尺寸和帧率计算。
    * @param init.encoderPreference 上传编码策略偏好，默认值为 maintainFramerate。
    */
@@ -525,7 +525,7 @@ var RealtimeVideoFormat = class _RealtimeVideoFormat {
      * 上传编码配置
      */
     /**
-     * 最低上传码率，单位为 kbps；未指定时由 SDK 计算，0 表示不设最低码率。
+     * 最低上传码率，单位为 kbps；缺省为 100，0 表示不设最低码率；仅支持该参数的 RTC 链路生效。
      */
     __publicField(this, "minimumBitrate");
     /**
@@ -598,10 +598,6 @@ var RtcProvider = /* @__PURE__ */ ((RtcProvider2) => {
 
 // src/Service/Realtime/RealtimeModel.ts
 var RealtimeModel = /* @__PURE__ */ ((RealtimeModel2) => {
-  RealtimeModel2["x2_0"] = "x2.0";
-  RealtimeModel2["x2_0_trtc"] = "x2.0-trtc";
-  RealtimeModel2["x2_1_preview"] = "x2.1-preview";
-  RealtimeModel2["x2_1_preview_1014"] = "x2.1-preview-1014";
   RealtimeModel2["x2_1_1_preview_cn"] = "x2.1.1-preview-cn";
   RealtimeModel2["x2_1_1_preview_us"] = "x2.1.1-preview-us";
   return RealtimeModel2;
@@ -613,36 +609,17 @@ function isKnownModel(model) {
   return Object.values(RealtimeModel).includes(model);
 }
 function modelDefaults(model) {
-  return isKnownModel(model) ? model : "x2.1-preview" /* x2_1_preview */;
+  return isKnownModel(model) ? model : "x2.1.1-preview-cn" /* x2_1_1_preview_cn */;
 }
 var MODEL_DISPLAY_NAMES = {
-  ["x2.0" /* x2_0 */]: "X2.0",
-  ["x2.0-trtc" /* x2_0_trtc */]: "X2.1-preview-trtc",
-  ["x2.1-preview" /* x2_1_preview */]: "X2.1-preview-agora",
-  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: "X2.1-preview-1014",
   ["x2.1.1-preview-cn" /* x2_1_1_preview_cn */]: "X2.1.1-preview-cn",
   ["x2.1.1-preview-us" /* x2_1_1_preview_us */]: "X2.1.1-preview-us"
 };
 var MODEL_BASE_URLS = {
-  ["x2.1-preview" /* x2_1_preview */]: "https://cloud.xmax.22duck.cn/open/api/v1",
-  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: "https://dev.xmaxai.com/open/api/v1",
   ["x2.1.1-preview-cn" /* x2_1_1_preview_cn */]: "https://cloud.xmax.22duck.cn/open/api/v1",
   ["x2.1.1-preview-us" /* x2_1_1_preview_us */]: "https://api.xmax.ai/open/api/v1"
 };
 var RESOLUTION_BUCKETS = {
-  ["x2.0" /* x2_0 */]: [],
-  ["x2.0-trtc" /* x2_0_trtc */]: [
-    { width: 1024, height: 1920 },
-    { width: 1920, height: 1024 }
-  ],
-  ["x2.1-preview" /* x2_1_preview */]: [
-    { width: 1024, height: 1920 },
-    { width: 1920, height: 1024 }
-  ],
-  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: [
-    { width: 1024, height: 1920 },
-    { width: 1920, height: 1024 }
-  ],
   ["x2.1.1-preview-cn" /* x2_1_1_preview_cn */]: [
     { width: 1024, height: 1920 },
     { width: 1920, height: 1024 }
@@ -653,10 +630,6 @@ var RESOLUTION_BUCKETS = {
   ]
 };
 var MAXIMUM_INPUT_PIXELS = {
-  ["x2.0" /* x2_0 */]: 128e4,
-  ["x2.0-trtc" /* x2_0_trtc */]: 21e5,
-  ["x2.1-preview" /* x2_1_preview */]: 21e5,
-  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: 21e5,
   ["x2.1.1-preview-cn" /* x2_1_1_preview_cn */]: 21e5,
   ["x2.1.1-preview-us" /* x2_1_1_preview_us */]: 21e5
 };
@@ -682,16 +655,10 @@ function defaultFrameRate(_model) {
   return 30;
 }
 function defaultCameraVideoFormat(model) {
-  if (modelDefaults(model) === "x2.0" /* x2_0 */) {
-    return new RealtimeVideoFormat({ width: 832, height: 1472, fps: 30 });
-  }
+  modelDefaults(model);
   return new RealtimeVideoFormat({ width: 1024, height: 1920, fps: 30 });
 }
 var MODEL_RTC_PROVIDERS = {
-  ["x2.0" /* x2_0 */]: Object.freeze(["vertc" /* vertc */]),
-  ["x2.0-trtc" /* x2_0_trtc */]: Object.freeze(["trtc" /* trtc */]),
-  ["x2.1-preview" /* x2_1_preview */]: Object.freeze(["agora" /* agora */]),
-  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: Object.freeze(["agora" /* agora */]),
   ["x2.1.1-preview-cn" /* x2_1_1_preview_cn */]: Object.freeze(["agora" /* agora */]),
   ["x2.1.1-preview-us" /* x2_1_1_preview_us */]: Object.freeze(["agora" /* agora */])
 };
@@ -699,8 +666,8 @@ function supportedRtcProviders(model) {
   return isKnownModel(model) ? MODEL_RTC_PROVIDERS[model] : CUSTOM_MODEL_RTC_PROVIDERS;
 }
 var CUSTOM_MODEL_RTC_PROVIDERS = Object.freeze([
-  ...MODEL_RTC_PROVIDERS["x2.1-preview" /* x2_1_preview */],
-  ...Object.values(RtcProvider).filter((provider) => !MODEL_RTC_PROVIDERS["x2.1-preview" /* x2_1_preview */].includes(provider))
+  ...MODEL_RTC_PROVIDERS["x2.1.1-preview-cn" /* x2_1_1_preview_cn */],
+  ...Object.values(RtcProvider).filter((provider) => !MODEL_RTC_PROVIDERS["x2.1.1-preview-cn" /* x2_1_1_preview_cn */].includes(provider))
 ]);
 
 // src/Foundation/Media/Video/FrameInterpolationSupport.ts
@@ -722,9 +689,9 @@ var MediaService = class {
   /**
    * 创建媒体服务。
    *
-   * @param model 媒体输入规则使用的模型，默认为 `x2.0-trtc`。
+   * @param model 媒体输入规则使用的模型，默认为 `x2.1.1-preview-cn`。
    */
-  constructor(model = "x2.0-trtc" /* x2_0_trtc */) {
+  constructor(model = "x2.1.1-preview-cn" /* x2_1_1_preview_cn */) {
     /**
      * 模型约束
      */
@@ -3968,7 +3935,9 @@ var RESERVED_PARAMS = /* @__PURE__ */ new Set([
   "ref_image_path",
   "mirror",
   "ref_video_path",
-  "sample_method"
+  "sample_method",
+  "min_bitrate",
+  "max_bitrate"
 ]);
 function snapshotExtraParams(params) {
   if (params === void 0) return void 0;
@@ -5980,6 +5949,20 @@ var RenderController = class {
     __publicField(this, "track");
     __publicField(this, "target");
     __publicField(this, "interactionEnabled", false);
+    __publicField(this, "ready", false);
+  }
+  /**
+   * 当前远端视图是否已完成渲染预热。
+   */
+  get isReady() {
+    return this.ready;
+  }
+  /**
+   * 新任务重新等待首帧和预热，避免复用上一次任务的展示就绪状态。
+   */
+  prepareForGeneration() {
+    this.ready = false;
+    this.target?.prepareForGeneration?.();
   }
   /**
    * 注册新轨道并使旧绑定失效；本地轨道不经过该入口。
@@ -5991,6 +5974,14 @@ var RenderController = class {
       TrajectoryRegistry.register(track, new TrajectoryBinding(listener, track.videoFormat));
     }
     VideoRenderRegistry.register(track, {
+      // 临时缓解生成开头卡顿：首帧后继续播放 1000 ms，再渐入。
+      renderWarmupMs: 1e3,
+      renderWarmupCompletedHandler: () => {
+        if (this.track === track) {
+          this.ready = true;
+          this.callbacks.onRenderWarmupCompleted?.();
+        }
+      },
       frameDisplayHandler: () => {
         if (this.track === track) {
           this.callbacks.onFrameDisplayed?.();
@@ -6001,6 +5992,7 @@ var RenderController = class {
           return;
         }
         this.target?.setFrameInterpolation?.(void 0);
+        this.ready = false;
         view.isMirrored = false;
         this.target = view;
         this.callbacks.onAttached?.();
@@ -6008,6 +6000,7 @@ var RenderController = class {
       },
       detachHandler: (view) => {
         if (this.target === view) {
+          this.ready = false;
           this.callbacks.onDetached?.();
           this.target = void 0;
         }
@@ -6020,6 +6013,7 @@ var RenderController = class {
    * 更新媒体画面；暂停显示时同时禁用交互。
    */
   setRemoteMedia(track) {
+    this.ready = false;
     if (this.track) {
       TrajectoryRegistry.binding(this.track)?.update(!!track && this.interactionEnabled);
     }
@@ -6044,6 +6038,7 @@ var RenderController = class {
    * 先使能力失效再清空画面，迟到首帧和旧手势不能恢复已结束任务。
    */
   resetRemoteTrack() {
+    this.ready = false;
     const track = this.track;
     this.track = void 0;
     this.interactionEnabled = false;
@@ -6501,6 +6496,7 @@ var RealtimeConnectionState = /* @__PURE__ */ ((RealtimeConnectionState2) => {
   RealtimeConnectionState2["ready"] = "Ready";
   RealtimeConnectionState2["connecting"] = "Connecting";
   RealtimeConnectionState2["connected"] = "Connected";
+  RealtimeConnectionState2["starting"] = "Starting";
   RealtimeConnectionState2["generating"] = "Generating";
   RealtimeConnectionState2["disconnecting"] = "Disconnecting";
   return RealtimeConnectionState2;
@@ -6606,6 +6602,8 @@ var RoomEvent = class _RoomEvent {
    * @param options.videoFormat 模型生成使用的视频规格。
    * @param options.context 本次生成条件。
    * @param options.targetSize 回传尺寸，缺省时不发送；网络视频默认使用生成尺寸。
+   * @param options.minimumBitrate 服务端回传的最低码率，单位为 kbps。
+   * @param options.maximumBitrate 服务端回传的最高码率，单位为 kbps。
    * @param options.mirror 是否由后端镜像输入画面，默认 false。
    * @param options.faceRestoration 是否回贴原始人脸，默认 false。
    * @param options.extraParams 已校验的本次扩展参数，合并到 params。
@@ -6616,6 +6614,8 @@ var RoomEvent = class _RoomEvent {
       event: "start",
       params: {
         ..._RoomEvent.generationParameters(options),
+        min_bitrate: options.minimumBitrate,
+        max_bitrate: options.maximumBitrate,
         mirror: options.mirror ?? false,
         ...options.context.referenceVideo && {
           ref_video_path: options.context.referenceVideo.path,
@@ -6652,12 +6652,14 @@ var RoomEvent = class _RoomEvent {
     });
   }
   /**
-   * 回传尺寸调整信令。
+   * 回传尺寸和码率范围调整信令，码率单位为 kbps。
    */
   static changeTargetSize(options) {
     return _RoomEvent.encode({
       event: "change_target_size",
       params: {
+        min_bitrate: options.minimumBitrate,
+        max_bitrate: options.maximumBitrate,
         target_size: [
           Math.round(options.targetSize.width),
           Math.round(options.targetSize.height)
@@ -6732,6 +6734,114 @@ var RoomEvent = class _RoomEvent {
   }
 };
 
+// src/Stream/Encoding/EncodingBitratePolicy.ts
+var _EncodingBitratePolicy = class _EncodingBitratePolicy {
+  /**
+   * 最低码率固定为 100 kbps，最高码率按尺寸和帧率计算并应用预算系数。
+   */
+  static resolve(width, height, fps) {
+    new RealtimeVideoFormat({ width, height, fps }).validate();
+    const maximum = Math.round(
+      this.resolveMaximumBitrate(width * height, fps) * this.bitrateScale
+    );
+    if (!Number.isSafeInteger(maximum)) {
+      throw new XmaxError(
+        "INVALID_CONFIGURATION" /* invalidConfiguration */,
+        "Realtime video format exceeds the supported bitrate range"
+      );
+    }
+    return { minimum: 100, maximum: Math.max(100, maximum) };
+  }
+  /**
+   * 按像素面积和帧率插值计算最高码率参考值。
+   */
+  static resolveMaximumBitrate(pixels, fps) {
+    const bitrate15 = _EncodingBitratePolicy.interpolate(
+      pixels,
+      _EncodingBitratePolicy.referenceBitratesAt15FPS
+    );
+    const first30 = _EncodingBitratePolicy.referenceBitratesAt30FPS[0];
+    let bitrate30;
+    if (pixels < first30.value) {
+      const reference15 = _EncodingBitratePolicy.interpolate(
+        first30.value,
+        _EncodingBitratePolicy.referenceBitratesAt15FPS
+      );
+      bitrate30 = bitrate15 * (first30.bitrate / reference15);
+    } else {
+      bitrate30 = _EncodingBitratePolicy.interpolate(
+        pixels,
+        _EncodingBitratePolicy.referenceBitratesAt30FPS
+      );
+    }
+    const bitrate10 = bitrate15 * (400 / 500);
+    const maximum60 = bitrate30 * (6500 / 3150);
+    return _EncodingBitratePolicy.interpolate(fps, [
+      { value: 10, bitrate: bitrate10 * 2 },
+      { value: 15, bitrate: bitrate15 * 2 },
+      { value: 30, bitrate: bitrate30 * 2 },
+      { value: 60, bitrate: maximum60 }
+    ]);
+  }
+  /**
+   * 在相邻参考点间线性插值，表外按最近端点的比例外推。
+   */
+  static interpolate(value, points) {
+    const first = points[0];
+    if (value <= first.value) {
+      return first.bitrate * (value / first.value);
+    }
+    for (let index = 1; index < points.length; index += 1) {
+      const upper = points[index];
+      if (value <= upper.value) {
+        const lower = points[index - 1];
+        const ratio = (value - lower.value) / (upper.value - lower.value);
+        return lower.bitrate + (upper.bitrate - lower.bitrate) * ratio;
+      }
+    }
+    const last = points[points.length - 1];
+    return last.bitrate * (value / last.value);
+  }
+};
+/**
+ * 最高码率相对参考值的预算系数。
+ */
+__publicField(_EncodingBitratePolicy, "bitrateScale", 0.6);
+/**
+ * 流畅优先码率参考，按像素面积升序排列，单位为 kbps。
+ */
+__publicField(_EncodingBitratePolicy, "referenceBitratesAt15FPS", [
+  { value: 120 * 120, bitrate: 50 },
+  { value: 160 * 120, bitrate: 65 },
+  { value: 180 * 180, bitrate: 100 },
+  { value: 240 * 180, bitrate: 120 },
+  { value: 320 * 180, bitrate: 140 },
+  { value: 320 * 240, bitrate: 200 },
+  { value: 424 * 240, bitrate: 220 },
+  { value: 360 * 360, bitrate: 260 },
+  { value: 480 * 360, bitrate: 320 },
+  { value: 640 * 360, bitrate: 400 },
+  { value: 640 * 480, bitrate: 500 },
+  { value: 848 * 480, bitrate: 610 },
+  { value: 960 * 720, bitrate: 910 },
+  { value: 1280 * 720, bitrate: 1130 },
+  { value: 1920 * 1080, bitrate: 2080 }
+]);
+/**
+ * 30 fps 的像素面积与码率参考点，单位为 kbps。
+ */
+__publicField(_EncodingBitratePolicy, "referenceBitratesAt30FPS", [
+  { value: 360 * 360, bitrate: 400 },
+  { value: 480 * 360, bitrate: 490 },
+  { value: 640 * 360, bitrate: 600 },
+  { value: 640 * 480, bitrate: 750 },
+  { value: 848 * 480, bitrate: 930 },
+  { value: 960 * 720, bitrate: 1380 },
+  { value: 1280 * 720, bitrate: 1710 },
+  { value: 1920 * 1080, bitrate: 3150 }
+]);
+var EncodingBitratePolicy = _EncodingBitratePolicy;
+
 // src/Stream/Room/RoomHeartbeat.ts
 var RoomHeartbeat = class {
   /**
@@ -7022,7 +7132,7 @@ var RoomController = class {
    *
    * @throws 已有房间未离开、操作失效或进房失败时抛出错误。
    */
-  async join(connection, ensureActive2) {
+  async join(connection, ensureActive2, measureRtcJoin) {
     try {
       ensureActive2();
     } catch (error) {
@@ -7041,11 +7151,14 @@ var RoomController = class {
       if (!this.customCodec) this.codec = new RoomMessageCodec(
         connection.provider === "vertc" /* vertc */ ? null : connection.provider === "agora" /* agora */ ? "__agora_chunk__" : "__trtc_chunk__"
       );
-      await this.rtcManager.joinRoom(toRoomJoinConfiguration(connection));
+      const configuration = toRoomJoinConfiguration(connection);
+      const completeRtcJoin = measureRtcJoin?.();
+      await this.rtcManager.joinRoom(configuration);
       ensureActive2();
       if (this.state.kind !== "joining" || this.state.operationID !== operationID || this.leaveOperation) {
         throw new XmaxError("CANCELLED" /* cancelled */, "RTC room join was cancelled");
       }
+      completeRtcJoin?.();
       this.state = { kind: "joined", userID: connection.userID };
       this.heartbeat.start(connection.userID);
     } catch (error) {
@@ -7097,7 +7210,8 @@ var RoomController = class {
         targetSize: options.targetSize,
         mirror: options.mirror ?? false,
         faceRestoration: options.faceRestoration ?? false,
-        extraParams: options.extraParams
+        extraParams: options.extraParams,
+        ...this.downlinkBitrates(options.targetSize ?? options.videoFormat)
       })
     );
   }
@@ -7136,10 +7250,23 @@ var RoomController = class {
       RoomEvent.changeTargetSize({
         userID: this.requireUserID(),
         taskID: options.taskID,
-        targetSize: options.targetSize
+        targetSize: options.targetSize,
+        ...this.downlinkBitrates(options.targetSize)
       })
     );
   }
+  /**
+   * 按回传尺寸和 24 fps 估算下行码率，最高值限制在 100～10000 kbps。
+   * 估算不设置服务端帧率，也不沿用显式上传码率。
+   */
+  downlinkBitrates(size) {
+    const { maximum } = EncodingBitratePolicy.resolve(
+      Math.round(size.width),
+      Math.round(size.height),
+      24
+    );
+    return { minimumBitrate: 100, maximumBitrate: Math.min(1e4, maximum) };
+  }
   /**
    * 尝试发送生成停止信令；未进房或任务标识为空时忽略。
    */
@@ -7241,7 +7368,7 @@ var ENCODER_PREFERENCE_MAP = {
   ["maintainFramerate" /* maintainFramerate */]: "maintainFramerate" /* maintainFramerate */,
   ["maintainQuality" /* maintainQuality */]: "maintainQuality" /* maintainQuality */
 };
-var _EncodingController = class _EncodingController {
+var EncodingController = class {
   /**
    * 创建编码控制器。
    *
@@ -7266,21 +7393,13 @@ var _EncodingController = class _EncodingController {
       minimum = videoFormat.minimumBitrate;
       maximum = videoFormat.maximumBitrate;
     } else {
-      const bitrates = _EncodingController.resolveBitrates(
-        videoFormat.width * videoFormat.height,
+      const defaults = EncodingBitratePolicy.resolve(
+        videoFormat.width,
+        videoFormat.height,
         videoFormat.fps
       );
-      const maximumBitrate = Math.round(bitrates.maximum);
-      if (!Number.isFinite(maximumBitrate)) {
-        throw new XmaxError(
-          "INVALID_CONFIGURATION" /* invalidConfiguration */,
-          "Realtime video format exceeds the supported bitrate range"
-        );
-      }
-      const defaultMinimum = Math.max(1, Math.round(bitrates.minimum));
-      const defaultMaximum = Math.max(defaultMinimum + 1, maximumBitrate);
-      minimum = videoFormat.minimumBitrate ?? defaultMinimum;
-      maximum = videoFormat.maximumBitrate ?? defaultMaximum;
+      minimum = videoFormat.minimumBitrate ?? defaults.minimum;
+      maximum = videoFormat.maximumBitrate ?? defaults.maximum;
     }
     if (minimum > maximum) {
       throw new XmaxError(
@@ -7321,97 +7440,7 @@ var _EncodingController = class _EncodingController {
     }
     return format;
   }
-  /**
-   * 按像素面积与帧率计算码率区间（kbps）：流畅优先为最低，画质优先为最高。
-   */
-  static resolveBitrates(pixels, fps) {
-    const bitrate15 = _EncodingController.interpolate(
-      pixels,
-      _EncodingController.referenceBitratesAt15FPS
-    );
-    const first30 = _EncodingController.referenceBitratesAt30FPS[0];
-    let bitrate30;
-    if (pixels < first30.value) {
-      const reference15 = _EncodingController.interpolate(
-        first30.value,
-        _EncodingController.referenceBitratesAt15FPS
-      );
-      bitrate30 = bitrate15 * (first30.bitrate / reference15);
-    } else {
-      bitrate30 = _EncodingController.interpolate(
-        pixels,
-        _EncodingController.referenceBitratesAt30FPS
-      );
-    }
-    const bitrate10 = bitrate15 * (400 / 500);
-    const minimum60 = bitrate30 * (4780 / 3150);
-    const maximum60 = bitrate30 * (6500 / 3150);
-    return {
-      minimum: _EncodingController.interpolate(fps, [
-        { value: 10, bitrate: bitrate10 },
-        { value: 15, bitrate: bitrate15 },
-        { value: 30, bitrate: bitrate30 },
-        { value: 60, bitrate: minimum60 }
-      ]),
-      maximum: _EncodingController.interpolate(fps, [
-        { value: 10, bitrate: bitrate10 * 2 },
-        { value: 15, bitrate: bitrate15 * 2 },
-        { value: 30, bitrate: bitrate30 * 2 },
-        { value: 60, bitrate: maximum60 }
-      ])
-    };
-  }
-  /**
-   * 在相邻参考点间线性插值，表外按最近端点的比例外推。
-   */
-  static interpolate(value, points) {
-    const first = points[0];
-    if (value <= first.value) {
-      return first.bitrate * (value / first.value);
-    }
-    for (let index = 1; index < points.length; index += 1) {
-      const upper = points[index];
-      if (value <= upper.value) {
-        const lower = points[index - 1];
-        const ratio = (value - lower.value) / (upper.value - lower.value);
-        return lower.bitrate + (upper.bitrate - lower.bitrate) * ratio;
-      }
-    }
-    const last = points[points.length - 1];
-    return last.bitrate * (value / last.value);
-  }
 };
-/**
- * 流畅优先码率参考，按像素面积升序排列，单位为 kbps。
- */
-__publicField(_EncodingController, "referenceBitratesAt15FPS", [
-  { value: 120 * 120, bitrate: 50 },
-  { value: 160 * 120, bitrate: 65 },
-  { value: 180 * 180, bitrate: 100 },
-  { value: 240 * 180, bitrate: 120 },
-  { value: 320 * 180, bitrate: 140 },
-  { value: 320 * 240, bitrate: 200 },
-  { value: 424 * 240, bitrate: 220 },
-  { value: 360 * 360, bitrate: 260 },
-  { value: 480 * 360, bitrate: 320 },
-  { value: 640 * 360, bitrate: 400 },
-  { value: 640 * 480, bitrate: 500 },
-  { value: 848 * 480, bitrate: 610 },
-  { value: 960 * 720, bitrate: 910 },
-  { value: 1280 * 720, bitrate: 1130 },
-  { value: 1920 * 1080, bitrate: 2080 }
-]);
-__publicField(_EncodingController, "referenceBitratesAt30FPS", [
-  { value: 360 * 360, bitrate: 400 },
-  { value: 480 * 360, bitrate: 490 },
-  { value: 640 * 360, bitrate: 600 },
-  { value: 640 * 480, bitrate: 750 },
-  { value: 848 * 480, bitrate: 930 },
-  { value: 960 * 720, bitrate: 1380 },
-  { value: 1280 * 720, bitrate: 1710 },
-  { value: 1920 * 1080, bitrate: 3150 }
-]);
-var EncodingController = _EncodingController;
 
 // src/Stream/StreamController.ts
 function makeInitialState() {
@@ -7580,9 +7609,9 @@ var StreamController = class {
    *
    * @throws 连接已取消，或 RTC 进房、房间配置与本地流发布失败时抛出错误。
    */
-  async connect(connection, includeLocalAudio, ensureActive2, beforePublish, publishLocalMedia = true) {
+  async connect(connection, includeLocalAudio, ensureActive2, beforePublish, publishLocalMedia = true, measureRtcJoin) {
     this.configureRoom({ roomID: connection.roomID, botID: connection.botID });
-    await this.roomController.join(connection, ensureActive2);
+    await this.roomController.join(connection, ensureActive2, measureRtcJoin);
     ensureActive2();
     XmaxLogger.stream.info(
       () => `RTC \u623F\u95F4\u5DF2\u914D\u7F6E (RTC Room Configured)
@@ -8180,12 +8209,13 @@ var StreamController = class {
 
 // src/Stream/Quality/QualityTiers.ts
 var INITIAL_QUALITY_LEVEL = 2;
+var MINIMUM_QUALITY_SHORT_SIDE = 240;
 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 }
+  L1: { scale: 1, width: 1024, height: 1920, frameRate: 30 },
+  L2: { scale: 0.8, width: 818, height: 1536, frameRate: 24 },
+  L3: { scale: 0.65, width: 664, height: 1248, frameRate: 24 },
+  L4: { scale: 0.5, width: 512, height: 960, frameRate: 20 },
+  L5: { scale: 0.4, width: 408, height: 768, frameRate: 16 }
 };
 
 // src/Stream/Quality/QualityPolicy.ts
@@ -8201,9 +8231,13 @@ var DEFAULT_POLICY = {
 // src/Stream/Quality/QualityController.ts
 var ORDERED_QUALITY_TIERS = Object.values(QUALITY_TIERS);
 var QualityController = class {
-  constructor(apply, now = () => performance.now(), policy = {}) {
+  /**
+   * 创建调档状态机；候选档位不满足编码约束时保持当前档位，不跨档尝试。
+   */
+  constructor(apply, now = () => performance.now(), policy = {}, canApply = () => true) {
     __publicField(this, "apply", apply);
     __publicField(this, "now", now);
+    __publicField(this, "canApply", canApply);
     __publicField(this, "policy");
     __publicField(this, "active", false);
     __publicField(this, "index", 0);
@@ -8293,10 +8327,13 @@ var QualityController = class {
     this.good = this.poor = 0;
   }
   async change(index, reason) {
+    this.resetCounts();
+    if (!this.canApply(index + 1)) {
+      return;
+    }
     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;
@@ -8321,12 +8358,20 @@ var QualityController = class {
 // 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");
+  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);
+  const shortSide = Math.min(baseline.width, baseline.height);
+  const minimum = Math.min(shortSide, MINIMUM_QUALITY_SHORT_SIDE);
+  const scale = Math.max(tier.scale, minimum / shortSide);
+  const even = (value) => Math.max(2, Math.floor(value / 2 + 1e-9) * 2);
   return { width: even(baseline.width * scale), height: even(baseline.height * scale) };
 }
+function supportsQualityEncoding(format) {
+  const defaults = EncodingBitratePolicy.resolve(format.width, format.height, format.fps);
+  return (format.minimumBitrate ?? defaults.minimum) <= (format.maximumBitrate ?? defaults.maximum);
+}
 function qualityVideoFormat(baseline, level) {
   const size = qualityVideoSize(baseline, level);
   const tier = Object.values(QUALITY_TIERS)[level - 1];
@@ -8338,35 +8383,59 @@ function qualityVideoFormat(baseline, level) {
 }
 
 // src/Stream/Quality/QualityHistory.ts
-var QualityHistory = class {
-  constructor(model, provider) {
+var _QualityHistory = class _QualityHistory {
+  /**
+   * 创建按模型与 RTC 提供方隔离的档位存储。
+   */
+  constructor(model, provider, now = Date.now) {
     __publicField(this, "model", model);
     __publicField(this, "provider", provider);
+    __publicField(this, "now", now);
   }
-  /** 无记录、损坏、SSR 或浏览器禁止存储时使用默认 L2。 */
+  /**
+   * 无记录、过期、损坏、时钟回退或存储不可用时使用默认 L2。
+   */
   read(direction) {
     try {
-      const level = Number(globalThis.localStorage.getItem(this.key(direction)));
-      if (this.isValid(level)) return level;
+      const entry = JSON.parse(globalThis.localStorage.getItem(this.key(direction)) ?? "null");
+      const now = this.now();
+      if (entry && this.isValid(entry.level) && Number.isFinite(entry.savedAt) && entry.savedAt > 0 && now >= entry.savedAt && now - entry.savedAt < _QualityHistory.expirationMs) {
+        return entry.level;
+      }
     } catch {
     }
     return INITIAL_QUALITY_LEVEL;
   }
-  /** 仅在应用成功后调用；下行成功表示信令已发送，不代表服务端已确认生效。 */
+  /**
+   * 应用成功后保存档位并刷新一小时有效期；下行成功仅表示信令已发送。
+   */
   write(direction, level) {
-    if (!this.isValid(level)) return;
+    if (!this.isValid(level)) {
+      return;
+    }
     try {
-      globalThis.localStorage.setItem(this.key(direction), String(level));
+      globalThis.localStorage.setItem(this.key(direction), JSON.stringify({ level, savedAt: this.now() }));
     } catch {
     }
   }
+  /**
+   * 生成当前方向的存储键；无时间戳的旧记录按无效记录处理。
+   */
   key(direction) {
     return `xmax:quality:v1:${this.provider}:${encodeURIComponent(this.model)}:${direction}`;
   }
+  /**
+   * 校验档位编号。
+   */
   isValid(level) {
     return Number.isInteger(level) && level >= 1 && level <= Object.keys(QUALITY_TIERS).length;
   }
 };
+/**
+ * 历史档位有效期，单位为毫秒。
+ */
+__publicField(_QualityHistory, "expirationMs", 60 * 60 * 1e3);
+var QualityHistory = _QualityHistory;
 
 // src/Core/Realtime/RealtimeCoordinator.ts
 function scopeAffects(scope, kind) {
@@ -8504,7 +8573,7 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
       await this.errorHandler.report(error);
       throw error;
     }
-    const operationKind = kind === "generation" /* generation */ && this.state.connectionState === "Generating" /* generating */ ? "configuration" /* configuration */ : kind;
+    const operationKind = kind === "generation" /* generation */ && (this.state.connectionState === "Generating" /* generating */ || this.state.connectionState === "Starting" /* starting */ && !!this.state.taskID) ? "configuration" /* configuration */ : kind;
     const lease = new OperationLease(failureScope);
     const resultPromise = (async () => body(lease))();
     const operation = {
@@ -8544,6 +8613,19 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
       new RealtimeState({ connectionState: "Ready" /* ready */ })
     );
   }
+  /**
+   * 当前生成任务和远端展示均就绪后进入 generating；迟到通知不恢复已结束任务。
+   */
+  async remotePreviewDidBecomeReady(sessionID, taskID, isCurrent) {
+    if (this.termination || this.state.connectionState !== "Starting" /* starting */ || this.state.sessionID !== sessionID || this.state.taskID !== taskID || !isCurrent()) {
+      return;
+    }
+    await this.setState(new RealtimeState({
+      connectionState: "Generating" /* generating */,
+      sessionID,
+      taskID
+    }));
+  }
   /**
    * 断开实时连接；尚未提交连接状态的活跃操作也会被取消。
    */
@@ -8836,11 +8918,16 @@ var RealtimeLaunchTimer = class {
     return this.measure("permissionMs", performance.now());
   }
   /**
-   * 开始会话与进房计时，返回连接阶段完成时调用的记录函数。
-   * 相机预热等待计入连接耗时。
+   * 开始创建业务会话的计时。
+   */
+  startSession() {
+    return this.measure("sessionMs", performance.now());
+  }
+  /**
+   * 开始 RTC 适配器进房调用的计时。
    */
-  startConnection() {
-    return this.measure("connectionMs", performance.now());
+  startRtcJoin() {
+    return this.measure("rtcJoinMs", performance.now());
   }
   /**
    * 开始发布本地流计时，返回发布完成时调用的记录函数。
@@ -8849,11 +8936,17 @@ var RealtimeLaunchTimer = class {
     return this.measure("publishMs", performance.now());
   }
   /**
-   * 开始等待远端显示首帧；完成回调同时记录首帧耗时和实际总耗时。
+   * 开始等待远端首帧提交合成器，不包含后续渲染预热。
    */
   startFirstFrame() {
     return this.measure("firstFrameMs", performance.now());
   }
+  /**
+   * 首帧就绪后开始渲染预热；结束时记录预热及实际总耗时，不含渐入动画。
+   */
+  startRenderWarmup() {
+    return this.measure("renderWarmupMs", performance.now());
+  }
   /**
    * 冻结本轮结果，令尚未完成的回调失效；下一轮相机启动才重置。
    */
@@ -8874,7 +8967,7 @@ var RealtimeLaunchTimer = class {
       this.snapshot = Object.freeze({
         ...this.snapshot,
         [key]: now - startedAt,
-        ...key === "firstFrameMs" ? { totalMs: now - this.startedAt } : {}
+        ...key === "renderWarmupMs" ? { totalMs: now - this.startedAt } : {}
       });
       this.notify();
     };
@@ -8925,8 +9018,8 @@ var XmaxRealtimeConnectionManager = class {
   }
   /**
    * 创建会话、配置编码、进房并发布本地媒体，启动心跳后返回远端占位流。
-   * 进房结束即记录连接耗时；可选 beforePublish 检查阻塞发布，计入连接耗时；
-   * 发布本地流单独计时。
+   * 会话创建、RTC 进房和本地流发布分别计时；可选 beforePublish 检查阻塞发布，
+   * 其等待只反映在实际完整启动耗时中。
    * @param options.localTrack 当前本地媒体轨道。
    * @param options.remoteVideoFormat 原始生成及远端画面规格，缺省使用本地轨道规格。
    * @param options.localVideoFormat 发布前实际应用的上行编码格式；与原始生成及远端格式分开。
@@ -8943,10 +9036,11 @@ var XmaxRealtimeConnectionManager = class {
     const sessionService = this.requireSessionService();
     const streamController = this.dependencies.streamController;
     options.ensureCurrent();
-    const completeConnection = this.dependencies.timing.startConnection();
+    const completeSession = this.dependencies.timing.startSession();
     const session = await sessionService.createSession(options.model);
     this.activeSession = session;
     options.ensureCurrent();
+    completeSession();
     const connection = session.connection;
     if (!connection) {
       throw new XmaxError(
@@ -8979,11 +9073,10 @@ var XmaxRealtimeConnectionManager = class {
     }, async () => {
       options.ensureCurrent();
       await options.beforePublish?.();
-      completeConnection();
+      options.ensureCurrent();
       completePublish = this.dependencies.timing.startPublish();
-    }, publishLocalMedia);
+    }, publishLocalMedia, () => this.dependencies.timing.startRtcJoin());
     options.ensureCurrent();
-    completeConnection();
     completePublish?.();
     options.onPublished();
     sessionService.startHeartbeat(session.id, {
@@ -9426,6 +9519,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
      */
     __publicField(this, "launchTimer", new RealtimeLaunchTimer());
     __publicField(this, "remoteFrameDisplayHandler");
+    __publicField(this, "remoteRenderWarmupCompletedHandler");
     /**
      * 媒体权限弹窗观察
      */
@@ -9502,6 +9596,10 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     });
     this.renderController = new RenderController({
       onFrameDisplayed: () => this.remoteFrameDisplayHandler?.(),
+      onRenderWarmupCompleted: () => {
+        this.remoteRenderWarmupCompletedHandler?.();
+        void this.completeGenerationPresentation().catch((error) => this.errorHandler.report(error));
+      },
       onAttached: () => this.applyRemoteInterpolation(),
       onDetached: () => {
         this.interpolationRevision++;
@@ -9530,6 +9628,10 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
           await this.applyUplinkQuality(change.to, token, signal);
         });
+      }, void 0, {}, (level) => {
+        const track = this.currentUplinkTrack;
+        const state2 = track && this.qualityStates.get(track);
+        return !!state2 && supportsQualityEncoding(this.uplinkQualityFormat(state2.baseline, level));
       });
       this.downlinkQualityController = new QualityController(async (change, signal) => {
         await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
@@ -9600,6 +9702,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       }
       const level = Math.max(1, Math.min(Object.keys(QUALITY_TIERS).length, state2.level + (direction === "upgrade" ? -1 : 1)));
       if (level === state2.level) return;
+      if (!supportsQualityEncoding(this.uplinkQualityFormat(state2.baseline, level))) {
+        throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Quality level conflicts with explicit bitrate constraints");
+      }
       this.adaptiveQualityRevision++;
       controller.resetSamples();
       await this.applyUplinkQuality(level, token);
@@ -10061,7 +10166,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     const track = this.currentUplinkTrack;
     const previous = track?.videoFormat;
     const state2 = this.currentState.connectionState;
-    if (!track || !previous || state2 !== "Connected" /* connected */ && state2 !== "Generating" /* generating */) {
+    if (!track || !previous || state2 !== "Connected" /* connected */ && state2 !== "Starting" /* starting */ && state2 !== "Generating" /* generating */) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Frame rate updates require a connected local camera, external or file stream");
     }
     if (!Number.isFinite(fps) || fps <= 0) {
@@ -10182,7 +10287,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       void 0,
       async (token) => {
         const connectionState = this.coordinator.currentState.connectionState;
-        if (connectionState === "Connecting" /* connecting */ || connectionState === "Connected" /* connected */ || connectionState === "Generating" /* generating */) {
+        if (connectionState === "Connecting" /* connecting */ || connectionState === "Connected" /* connected */ || connectionState === "Starting" /* starting */ || connectionState === "Generating" /* generating */) {
           throw new XmaxError(
             "INVALID_CONFIGURATION" /* invalidConfiguration */,
             "A realtime connection is already active"
@@ -10197,6 +10302,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    *
    * 尚未连接时先建立实时连接；已在生成时默认更新条件，restart 为 true 时重新开始生成。
    * 首次生成必须提供条件上下文，之后缺省时复用最近一次缓存的上下文。
+   * 返回后请将远端流挂载到 SDK 视频视图；首帧及渲染预热完成后状态才进入 generating。
    *
    * @param options.localStream 由当前 Manager 创建的摄像头、外部视频轨、本地文件或网络视频源。
    * @param options.context 本次生成使用的条件上下文；缺省时复用缓存。
@@ -10204,7 +10310,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * @param options.faceRestoration 是否启用原始人脸回贴，默认 false；正在生成时通过 change_condition 更新。
    * @param options.extraParams 合并到本次 start 或 change_condition 的 params；不缓存，自动恢复时不携带，不允许覆盖 SDK 字段。
    * @param options.record 是否录制远端原始音视频约 20 秒，默认 false；仅 start 有效，条件更新时忽略，重启录制暂不支持。
-   * @returns 承载远端生成画面的媒体流。
+   * @returns 可挂载的远端媒体流，不等待渲染预热；展示就绪以 generating 状态为准。
    * @throws extraParams 包含非 JSON 数据、循环引用或 SDK 保留字段时，在连接或更新前抛出 invalidConfiguration。
    * @throws 本地流不属于当前 Manager、缺少可用的条件上下文、信令发送
    * 或生成确认失败时抛出错误；失败时自动停止生成任务并释放连接资源。
@@ -10230,8 +10336,8 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
           );
         }
         const currentState = this.coordinator.currentState;
-        const isGenerating = currentState.connectionState === "Generating" /* generating */;
-        if (isGenerating && options.restart !== true) {
+        const hasGeneration = currentState.connectionState === "Generating" /* generating */ || currentState.connectionState === "Starting" /* starting */ && !!currentState.taskID;
+        if (hasGeneration && options.restart !== true) {
           await this.generationManager.update(currentState.taskID, {
             videoFormat,
             context: options.context,
@@ -10248,7 +10354,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
           throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Create a network video stream before using a reference video");
         }
         const context = referenceVideo ? new RealtimeContext({ ...supplied, referenceVideo }) : supplied;
-        if (currentState.connectionState !== "Connected" /* connected */ && !isGenerating) {
+        if (currentState.connectionState !== "Connected" /* connected */ && !hasGeneration) {
           await this.performConnect(options.localStream, token);
         }
         return this.performStartGeneration(
@@ -10300,7 +10406,11 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     if (this.qualityStates.has(track)) return void 0;
     const baseline = track.videoFormat;
     if (!baseline) return void 0;
-    return { baseline, level: this.qualityHistory.read("uplink") };
+    let level = this.qualityHistory.read("uplink");
+    while (level > 1 && !supportsQualityEncoding(this.uplinkQualityFormat(baseline, level))) {
+      level--;
+    }
+    return { baseline, level };
   }
   /**
    * 建立实时连接：创建会话、进房发布、启动心跳并准备远端渲染轨道。
@@ -10386,6 +10496,15 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   async performStartGeneration(token, videoFormat, context, restart, faceRestoration, extraParams, record2 = false) {
     token.setFailureScope(0 /* connection */);
+    const sessionID = this.connectionManager.currentSessionID;
+    if (!sessionID) {
+      throw new XmaxError("SESSION_ERROR" /* sessionError */, "Realtime session is unavailable");
+    }
+    await this.coordinator.commit(
+      new RealtimeState({ connectionState: "Starting" /* starting */, sessionID }),
+      token
+    );
+    token.ensureCurrent();
     if (restart) {
       void this.recordingController.stop("restarted" /* restarted */);
     }
@@ -10393,9 +10512,14 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     const targetSize = this.downlinkQualityController ? qualityVideoSize(videoFormat, initialLevel) : void 0;
     await this.prepareFrameInterpolation(targetSize ?? videoFormat, token);
     const completeFirstFrame = this.launchTimer.startFirstFrame();
+    this.remoteRenderWarmupCompletedHandler = void 0;
     this.remoteFrameDisplayHandler = () => {
-      if (!token.signal.aborted) completeFirstFrame();
+      if (!token.signal.aborted) {
+        completeFirstFrame();
+        this.remoteRenderWarmupCompletedHandler ?? (this.remoteRenderWarmupCompletedHandler = this.launchTimer.startRenderWarmup());
+      }
     };
+    this.renderController.prepareForGeneration();
     const taskID = await this.generationManager.start({
       videoFormat,
       signal: token.signal,
@@ -10426,10 +10550,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       } : void 0,
       extraParams
     });
-    const sessionID = this.connectionManager.currentSessionID;
-    if (!sessionID) {
-      throw new XmaxError("SESSION_ERROR" /* sessionError */, "Realtime session is unavailable");
-    }
+    token.ensureCurrent();
     this.downlinkQualityController?.stop();
     this.downlinkQualityState = {
       taskID,
@@ -10438,14 +10559,17 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       size: targetSize ?? { width: videoFormat.width, height: videoFormat.height }
     };
     await this.coordinator.commit(
-      new RealtimeState({ connectionState: "Generating" /* generating */, sessionID, taskID }),
+      new RealtimeState({ connectionState: "Starting" /* starting */, sessionID, taskID }),
       token
     );
+    token.ensureCurrent();
+    await this.completeGenerationPresentation();
+    token.ensureCurrent();
     this.qualityHistory?.write("downlink", initialLevel);
     const onFinish = this.mediaController.onNetworkVideoFinish;
     if (this.mediaController.source === "networkVideo") {
       this.streamController.activateNetworkVideoCompletion(() => {
-        if (this.currentState.taskID === taskID && this.currentState.connectionState === "Generating" /* generating */) {
+        if (this.currentState.taskID === taskID && (this.currentState.connectionState === "Starting" /* starting */ || this.currentState.connectionState === "Generating" /* generating */)) {
           void this.recordingController.stop("generationEnded" /* generationEnded */);
           return onFinish?.();
         }
@@ -10453,6 +10577,20 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     }
     return this.connectionManager.makeRemoteStream();
   }
+  /**
+   * 任务启动成功且当前视图完成预热后提交展示就绪状态，不阻塞远端流返回。
+   */
+  async completeGenerationPresentation() {
+    const { sessionID, taskID } = this.currentState;
+    if (!sessionID || !taskID) {
+      return;
+    }
+    await this.coordinator.remotePreviewDidBecomeReady(
+      sessionID,
+      taskID,
+      () => this.renderController.isReady
+    );
+  }
   /**
    * 心跳失败或会话失效：结束当前连接生命周期并通过最终状态给出原因。
    */
@@ -10471,6 +10609,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     this.mediaController.pauseLocalVideo();
     this.launchTimer.cancel();
     this.remoteFrameDisplayHandler = void 0;
+    this.remoteRenderWarmupCompletedHandler = void 0;
     this.clearVideoStatistics();
     this.interpolationSize = void 0;
     this.applyRemoteInterpolation();
@@ -11013,9 +11152,9 @@ var XmaxClient = class {
   /**
    * 创建媒体处理与能力查询 Service。
    *
-   * @param model 媒体输入规则使用的模型，默认为 `x2.0-trtc`。
+   * @param model 媒体输入规则使用的模型，默认为 `x2.1.1-preview-cn`。
    */
-  createMediaService(model = "x2.0-trtc" /* x2_0_trtc */) {
+  createMediaService(model = "x2.1.1-preview-cn" /* x2_1_1_preview_cn */) {
     return new MediaService(model);
   }
   /**
@@ -11033,7 +11172,7 @@ var RealtimeConfiguration = class {
   /**
    * 创建实时业务配置。
    *
-   * @param init.model 实时生成业务使用的模型；未知名称原样透传，默认配置同 x2.1-preview。
+   * @param init.model 实时生成业务使用的模型；未知名称原样透传，默认配置同 x2.1.1-preview-cn。
    * @param init.provider RTC 提供方，默认按模型定义选择；必须受模型支持，创建后不可切换。
    * @param init.isFrameInterpolationEnabled 是否默认开启远端生成画面的插帧，默认 false。
    */
@@ -11206,6 +11345,75 @@ var RenderStatisticsController = class {
   }
 };
 
+// src/Render/Video/RenderWarmupController.ts
+var RenderWarmupController = class {
+  /**
+   * 创建视图预热控制器。
+   */
+  constructor(element) {
+    __publicField(this, "element", element);
+    /**
+     * 预热配置与生命周期
+     */
+    __publicField(this, "durationMs");
+    __publicField(this, "timer");
+    __publicField(this, "started", false);
+    __publicField(this, "completed", false);
+  }
+  /**
+   * 是否仍在等待首帧或预热完成；期间不允许对不可见画面交互。
+   */
+  get isPending() {
+    return this.durationMs !== void 0 && !this.completed;
+  }
+  /**
+   * 为新媒体隐藏画面；undefined 表示直接显示，不启用预热。
+   */
+  prepare(durationMs) {
+    this.reset();
+    this.durationMs = durationMs;
+    if (durationMs === void 0) {
+      return;
+    }
+    this.element.style.transition = "none";
+    this.element.style.opacity = "0";
+    this.element.style.pointerEvents = "none";
+  }
+  /**
+   * 首帧就绪后开始一次性预热，结束时通知并渐入画面。
+   */
+  start(onCompleted) {
+    if (this.durationMs === void 0 || this.started) {
+      return;
+    }
+    this.started = true;
+    this.timer = setTimeout(() => {
+      this.timer = void 0;
+      this.completed = true;
+      const reduceMotion = globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+      this.element.style.transition = reduceMotion ? "none" : "opacity 300ms ease-in-out";
+      this.element.style.opacity = "1";
+      this.element.style.pointerEvents = "";
+      onCompleted();
+    }, this.durationMs);
+  }
+  /**
+   * 换流或卸载时取消预热和渐入，防止旧任务显示新画面。
+   */
+  reset() {
+    clearTimeout(this.timer);
+    this.timer = void 0;
+    this.started = false;
+    this.completed = false;
+    if (this.durationMs !== void 0) {
+      this.element.style.transition = "";
+      this.element.style.opacity = "";
+      this.element.style.pointerEvents = "";
+    }
+    this.durationMs = void 0;
+  }
+};
+
 // ../../node_modules/.pnpm/framegen@1.4.0/node_modules/framegen/rt.js
 var WG = 8;
 var texBgSeq = 0;
@@ -14120,6 +14328,10 @@ var XmaxVideoView = class {
      * 呈现统计组件
      */
     __publicField(this, "statisticsController");
+    /**
+     * 远端画面预热与渐入组件
+     */
+    __publicField(this, "warmupController");
     /**
      * DOM 挂载状态
      */
@@ -14136,6 +14348,7 @@ var XmaxVideoView = class {
     this.element.style.position = "relative";
     this.element.style.overflow = "hidden";
     this.element.style.backgroundColor = "black";
+    this.warmupController = new RenderWarmupController(this.element);
     this.videoElement = document.createElement("video");
     this.statisticsController = new RenderStatisticsController(this.videoElement);
     this.videoElement.autoplay = true;
@@ -14159,7 +14372,7 @@ var XmaxVideoView = class {
    */
   set isInteractionEnabled(enabled) {
     this.interactionEnabled = enabled;
-    this.trajectoryOverlay?.configure(this.contentMode, this.mirrored, enabled);
+    this.trajectoryOverlay?.configure(this.contentMode, this.mirrored, enabled && !this.warmupController.isPending);
   }
   /**
    * 自定义轨迹视觉效果；undefined 表示使用 SDK 默认效果。
@@ -14260,6 +14473,7 @@ var XmaxVideoView = class {
     this.startInterpolation();
     this.startRenderStatistics();
     if ((this.videoElement.srcObject || this.videoElement.getAttribute("src")) && !this.hasNotifiedFrameDisplay) {
+      this.prepareRenderWarmup();
       this.armFrameDisplayNotification();
     }
   }
@@ -14272,6 +14486,8 @@ var XmaxVideoView = class {
     this.statisticsController.stop();
     this.stopInterpolation();
     this.cancelFrameDisplayNotification();
+    this.warmupController.reset();
+    this.hasNotifiedFrameDisplay = false;
     if (this.videoElement.getAttribute("src")) {
       this.videoElement.pause();
     }
@@ -14281,6 +14497,7 @@ var XmaxVideoView = class {
    * 设置网络视频预览；静音播放一次，不捕获或发布媒体轨道。 @internal
    */
   setVideoURL(url) {
+    this.warmupController.reset();
     this.statisticsController.stop();
     this.stopInterpolation();
     this.cancelFrameDisplayNotification();
@@ -14309,13 +14526,27 @@ var XmaxVideoView = class {
     this.cancelFrameDisplayNotification();
     this.hasNotifiedFrameDisplay = false;
     this.videoElement.srcObject = stream;
+    this.warmupController.reset();
     if (stream) {
       this.videoElement.autoplay = true;
+      this.prepareRenderWarmup();
       this.armFrameDisplayNotification();
       this.startInterpolation();
       this.startRenderStatistics();
     }
   }
+  /**
+   * 新生成任务重新等待首帧和预热，不替换正在播放的媒体流。 @internal
+   */
+  prepareForGeneration() {
+    this.cancelFrameDisplayNotification();
+    this.warmupController.reset();
+    this.hasNotifiedFrameDisplay = false;
+    this.prepareRenderWarmup();
+    if (!this.detached && this.videoElement.srcObject) {
+      this.armFrameDisplayNotification();
+    }
+  }
   /**
    * 由远端绑定注入配置；本地预览不走此管线。 @internal
    */
@@ -14390,6 +14621,7 @@ var XmaxVideoView = class {
    * 解绑当前轨道并清空渲染内容。
    */
   detachCurrentTrack() {
+    this.warmupController.reset();
     this.disposeTrajectory();
     this.statisticsController.stop();
     const track = this.currentTrack;
@@ -14417,8 +14649,15 @@ var XmaxVideoView = class {
       }
       this.hasNotifiedFrameDisplay = true;
       this.cancelFrameDisplayNotification();
+      const notifiedSequence = this.frameNotificationSequence;
       binding?.frameDisplayHandler?.();
       this.frameDisplayHandler?.();
+      if (notifiedSequence === this.frameNotificationSequence) {
+        this.warmupController.start(() => {
+          this.applyContentMode();
+          binding?.renderWarmupCompletedHandler?.();
+        });
+      }
     };
     if (typeof this.videoElement.requestVideoFrameCallback === "function") {
       this.videoFrameCallbackID = this.videoElement.requestVideoFrameCallback(notify);
@@ -14446,11 +14685,19 @@ var XmaxVideoView = class {
       this.onPlaying = void 0;
     }
   }
+  /**
+   * 仅远端渲染绑定启用预热，本地预览和普通媒体直接显示。
+   */
+  prepareRenderWarmup() {
+    const binding = this.currentTrack ? VideoRenderRegistry.binding(this.currentTrack) : void 0;
+    this.warmupController.prepare(binding?.renderWarmupMs);
+    this.applyContentMode();
+  }
   /**
    * 应用显示模式与镜像样式。
    */
   applyContentMode() {
-    this.trajectoryOverlay?.configure(this.contentMode, this.mirrored, this.interactionEnabled);
+    this.trajectoryOverlay?.configure(this.contentMode, this.mirrored, this.interactionEnabled && !this.warmupController.isPending);
     this.videoElement.style.objectFit = OBJECT_FIT[this.contentMode];
     this.videoElement.style.transform = this.mirrored ? "scaleX(-1)" : "";
     if (this.interpolationCanvas) {
@@ -14477,7 +14724,7 @@ var XmaxVideoView = class {
     }
     const overlay = new TrajectoryOverlayView(this.customTrajectoryRenderer ?? new DefaultTrajectoryEffectRenderer());
     this.trajectoryOverlay = overlay;
-    overlay.configure(this.contentMode, this.mirrored, this.interactionEnabled);
+    overlay.configure(this.contentMode, this.mirrored, this.interactionEnabled && !this.warmupController.isPending);
     this.element.appendChild(overlay.element);
     binding.attach(overlay);
   }
@@ -14578,7 +14825,7 @@ var XmaxRealtimeVideoView = class {
   }
   /**
    * 当前显示的远端生成视频轨道。
-   * 设置新轨道后等待首帧提交显示再渐入；置空时立即恢复本地预览。
+   * SDK 远端轨道等待首帧及预热后渐入；置空时立即恢复本地预览。
    */
   get remoteTrack() {
     return this.currentRemoteTrack;
@@ -14639,18 +14886,23 @@ var XmaxRealtimeVideoView = class {
     this.element.remove();
   }
   /**
-   * 更新远端轨道绑定：重置渐入状态，等待首帧提交后再显示远端画面。
+   * 更新远端轨道绑定；SDK 轨道共用单轨视图的预热，普通轨道等待首帧后渐入。
    */
   updateRemoteTrack() {
     const remoteTrack = this.currentRemoteTrack;
     this.remoteVideoView.frameDisplayHandler = void 0;
+    this.remoteVideoView.track = void 0;
     this.remoteVideoView.element.style.transition = "";
     this.remoteVideoView.element.style.opacity = "0";
     this.remoteVideoView.element.style.visibility = "hidden";
-    this.remoteVideoView.track = void 0;
     if (!remoteTrack) {
       return;
     }
+    if (VideoRenderRegistry.binding(remoteTrack)?.renderWarmupMs !== void 0) {
+      this.remoteVideoView.element.style.visibility = "visible";
+      this.remoteVideoView.track = remoteTrack;
+      return;
+    }
     this.remoteVideoView.frameDisplayHandler = () => {
       if (this.currentRemoteTrack !== remoteTrack) {
         return;
@@ -14713,4 +14965,4 @@ export {
   XmaxVideoView,
   XmaxRealtimeVideoView
 };
-//# sourceMappingURL=chunk-ILZL4W2G.js.map
+//# sourceMappingURL=chunk-LOYJFYQT.js.map