@xmaxai/web-sdk 1.0.0 → 1.0.1

package/dist/{chunk-JJWUZ3AW.cjs → chunk-FH3OPC6F.cjs}

@@ -9,7 +9,9 @@ var XmaxEnvironment = /* @__PURE__ */ ((XmaxEnvironment2) => {
   return XmaxEnvironment2;
 })(XmaxEnvironment || {});
 var API_BASE_URLS = {
-  // 临时联调环境。
+  /**
+   * 临时联调环境。
+   */
   ["china" /* china */]: "https://dev.xmaxai.com/open/api/v1",
   ["global" /* global */]: "https://api.xmax.cloud/open/api/v1"
 };
@@ -38,8 +40,13 @@ var CONSOLE_METHOD = {
 var BRAND_BADGE_STYLE = "background:#2563eb;color:#fff;border-radius:3px;padding:1px 4px;font-weight:600;";
 var CATEGORY_BADGE_STYLE = "background:#475569;color:#fff;border-radius:3px;padding:1px 4px;font-weight:600;";
 var _XmaxLogger = class _XmaxLogger {
+  /**
+   * 创建固定业务分类的日志入口，共享全局日志选项和语言配置。
+   */
   constructor(category) {
-    // 日志类别
+    /**
+     * 日志类别
+     */
     __publicField(this, "category");
     this.category = category;
   }
@@ -53,31 +60,45 @@ var _XmaxLogger = class _XmaxLogger {
     state.options = options;
     state.environment = environment;
   }
-  /** 选择日志细项文案；日志标题保持原有中英双语。 */
+  /**
+   * 选择日志细项文案；日志标题保持原有中英双语。
+   */
   static localized(chinese, english) {
     return state.environment === "china" /* china */ ? chinese : english;
   }
-  /** 判断指定日志类型是否已开启。 */
+  /**
+   * 判断指定日志类型是否已开启。
+   */
   static isEnabled(option) {
     return (state.options & option) !== 0;
   }
-  /** 输出调试日志。 */
+  /**
+   * 输出调试日志。
+   */
   debug(message, option = 1 /* business */) {
     this.log("debug", message, option);
   }
-  /** 输出信息日志。 */
+  /**
+   * 输出信息日志。
+   */
   info(message, option = 1 /* business */) {
     this.log("info", message, option);
   }
-  /** 输出警告日志。 */
+  /**
+   * 输出警告日志。
+   */
   warning(message, option = 1 /* business */) {
     this.log("warning", message, option);
   }
-  /** 输出错误日志。 */
+  /**
+   * 输出错误日志。
+   */
   error(message, option = 1 /* business */) {
     this.log("error", message, option);
   }
-  /** 按日志类型开关输出到控制台；未开启时不求值日志内容。 */
+  /**
+   * 按日志类型开关输出到控制台；未开启时不求值日志内容。
+   */
   log(level, message, option) {
     if (!_XmaxLogger.isEnabled(option)) {
       return;
@@ -98,7 +119,9 @@ var _XmaxLogger = class _XmaxLogger {
     console[CONSOLE_METHOD[level]](`[Xmax][${this.category}] ${text}`);
   }
 };
-// 分类日志
+/**
+ * 分类日志
+ */
 __publicField(_XmaxLogger, "realtime", new _XmaxLogger("Realtime"));
 __publicField(_XmaxLogger, "rtc", new _XmaxLogger("RTC"));
 __publicField(_XmaxLogger, "media", new _XmaxLogger("Media"));
@@ -142,12 +165,20 @@ var XmaxError = class _XmaxError extends Error {
    */
   constructor(code, message, options) {
     super(message);
-    // 错误信息
-    /** SDK 统一错误码。 */
+    /**
+     * 错误信息
+     */
+    /**
+     * SDK 统一错误码。
+     */
     __publicField(this, "code");
-    /** Xmax API 返回的业务错误码；非 API 业务错误时为空。 */
+    /**
+     * Xmax API 返回的业务错误码；非 API 业务错误时为空。
+     */
     __publicField(this, "apiCode");
-    /** HTTP 响应状态码；请求未获得响应时为空。 */
+    /**
+     * HTTP 响应状态码；请求未获得响应时为空。
+     */
     __publicField(this, "httpStatus");
     this.name = "XmaxError";
     this.code = code;
@@ -170,9 +201,11 @@ var XmaxError = class _XmaxError extends Error {
 };
 
 // src/Foundation/Runtime/RuntimeInfo.ts
-var XMAX_SDK_VERSION = "1.0.0";
+var XMAX_SDK_VERSION = "1.0.1";
 var _RuntimeInfo = class _RuntimeInfo {
-  /** 序列化为接口传输使用的 snake_case 字段。 */
+  /**
+   * 序列化为接口传输使用的 snake_case 字段。
+   */
   static toJSON(snapshot = _RuntimeInfo.current) {
     return {
       platform: snapshot.platform,
@@ -181,7 +214,9 @@ var _RuntimeInfo = class _RuntimeInfo {
       device_model: snapshot.deviceModel
     };
   }
-  /** 读取浏览器 User-Agent；非浏览器环境返回 unknown。 */
+  /**
+   * 读取浏览器 User-Agent；非浏览器环境返回 unknown。
+   */
   static currentOSVersion() {
     if (typeof navigator !== "undefined" && navigator.userAgent) {
       return navigator.userAgent;
@@ -189,7 +224,12 @@ var _RuntimeInfo = class _RuntimeInfo {
     return "unknown";
   }
 };
-/** 当前运行环境快照。 */
+/**
+ * 运行环境快照
+ */
+/**
+ * 当前运行环境快照。
+ */
 __publicField(_RuntimeInfo, "current", {
   platform: "web",
   osVersion: _RuntimeInfo.currentOSVersion(),
@@ -209,17 +249,24 @@ var _ApiService = class _ApiService {
    * @param options.fetchImpl fetch 实现（可替换，测试用）。
    */
   constructor(options) {
-    // 平台资源
+    /**
+     * 请求身份、地址与超时配置
+     */
     __publicField(this, "apiKey");
     __publicField(this, "baseURL");
     __publicField(this, "timeoutMs");
+    /**
+     * 网络传输依赖
+     */
     __publicField(this, "fetchImpl");
     this.apiKey = options.apiKey.trim();
     this.baseURL = options.baseURL;
     this.timeoutMs = _nullishCoalesce(options.timeoutMs, () => ( _ApiService.defaultTimeoutMs));
     this.fetchImpl = _nullishCoalesce(options.fetchImpl, () => ( ((url, init) => fetch(url, init))));
   }
-  /** 发送请求并返回统一响应中的数据。 */
+  /**
+   * 发送请求并返回统一响应中的数据。
+   */
   async request(method, path, body) {
     this.validateConfiguration();
     const request = this.makeRequest(method, path, body);
@@ -248,23 +295,33 @@ var _ApiService = class _ApiService {
       throw mapped;
     }
   }
-  /** 发送 GET 请求。 */
+  /**
+   * 发送 GET 请求。
+   */
   get(path) {
     return this.request("GET" /* get */, path);
   }
-  /** 发送 POST 请求。 */
+  /**
+   * 发送 POST 请求。
+   */
   post(path, body) {
     return this.request("POST" /* post */, path, body);
   }
-  /** 发送 PUT 请求。 */
+  /**
+   * 发送 PUT 请求。
+   */
   put(path, body) {
     return this.request("PUT" /* put */, path, body);
   }
-  /** 发送 DELETE 请求。 */
+  /**
+   * 发送 DELETE 请求。
+   */
   delete(path) {
     return this.request("DELETE" /* delete */, path);
   }
-  /** 校验 API Key 与 Base URL 配置。 */
+  /**
+   * 校验 API Key 与 Base URL 配置。
+   */
   validateConfiguration() {
     if (this.apiKey.length === 0) {
       throw new XmaxError("INVALID_API_KEY" /* invalidAPIKey */, "API key cannot be empty");
@@ -287,7 +344,9 @@ var _ApiService = class _ApiService {
       );
     }
   }
-  /** 构造请求地址、请求头与请求体；路径必须相对且与 Base URL 同源。 */
+  /**
+   * 构造请求地址、请求头与请求体；路径必须相对且与 Base URL 同源。
+   */
   makeRequest(method, path, body) {
     const normalizedPath = path.trim();
     if (normalizedPath.length === 0 || normalizedPath.includes("://") || normalizedPath.startsWith("//")) {
@@ -333,7 +392,9 @@ var _ApiService = class _ApiService {
       }
     };
   }
-  /** 解析统一响应信封并返回数据；业务失败或数据缺失时抛出错误。 */
+  /**
+   * 解析统一响应信封并返回数据；业务失败或数据缺失时抛出错误。
+   */
   static parseResponse(text, status) {
     let envelope;
     try {
@@ -348,7 +409,7 @@ var _ApiService = class _ApiService {
       const message = _optionalChain([envelope, 'access', _4 => _4.message, 'optionalAccess', _5 => _5.trim, 'call', _6 => _6()]);
       throw new XmaxError(
         "API_ERROR" /* apiError */,
-        message && message.length > 0 ? message : "Xmax API request failed",
+        message || "Xmax API request failed",
         { apiCode: envelope.code, httpStatus: status }
       );
     }
@@ -361,7 +422,9 @@ var _ApiService = class _ApiService {
     }
     return envelope.data;
   }
-  /** 将传输层异常映射为 SDK 统一错误。 */
+  /**
+   * 将传输层异常映射为 SDK 统一错误。
+   */
   static transportError(error) {
     if (error instanceof XmaxError) {
       return error;
@@ -378,7 +441,9 @@ var _ApiService = class _ApiService {
       `HTTP request failed: ${message}`
     );
   }
-  /** 输出失败日志。 */
+  /**
+   * 输出失败日志。
+   */
   logFailure(method, path, error, startedAt) {
     XmaxLogger.api.error(
       () => `API \u8BF7\u6C42\u5931\u8D25 (API Request Failed)
@@ -387,8 +452,12 @@ var _ApiService = class _ApiService {
     );
   }
 };
-// API 配置
-/** 默认请求超时时间（毫秒）。 */
+/**
+ * API 配置
+ */
+/**
+ * 默认请求超时时间（毫秒）。
+ */
 __publicField(_ApiService, "defaultTimeoutMs", 15e3);
 var ApiService = _ApiService;
 
@@ -410,11 +479,35 @@ var RealtimeVideoFormat = class _RealtimeVideoFormat {
    * @param init.encoderPreference 上传编码策略偏好，默认值为 maintainFramerate。
    */
   constructor(init) {
+    /**
+     * 视频规格
+     */
+    /**
+     * 视频宽度，单位为像素。
+     */
     __publicField(this, "width");
+    /**
+     * 视频高度，单位为像素。
+     */
     __publicField(this, "height");
+    /**
+     * 视频帧率，单位为 fps。
+     */
     __publicField(this, "fps");
+    /**
+     * 上传编码配置
+     */
+    /**
+     * 最低上传码率，单位为 kbps；未指定时由 SDK 计算，0 表示不设最低码率。
+     */
     __publicField(this, "minimumBitrate");
+    /**
+     * 最高上传码率，单位为 kbps；未指定时由 SDK 计算。
+     */
     __publicField(this, "maximumBitrate");
+    /**
+     * 弱网下优先保障帧率或分辨率的编码策略。
+     */
     __publicField(this, "encoderPreference");
     this.width = init.width;
     this.height = init.height;
@@ -453,7 +546,9 @@ var RealtimeVideoFormat = class _RealtimeVideoFormat {
       );
     }
   }
-  /** 调整尺寸，保留帧率和上传编码配置。 */
+  /**
+   * 调整尺寸，保留帧率和上传编码配置。
+   */
   resized(width, height) {
     return new _RealtimeVideoFormat({
       width,
@@ -468,16 +563,25 @@ var RealtimeVideoFormat = class _RealtimeVideoFormat {
 
 // src/Service/Realtime/RealtimeModel.ts
 var RealtimeModel = /* @__PURE__ */ ((RealtimeModel2) => {
+  RealtimeModel2["x2_0"] = "x2.0";
+  RealtimeModel2["x2_0_pro"] = "x2.0-pro";
   RealtimeModel2["x2_fast_1080p"] = "x2-fast-1080p";
   return RealtimeModel2;
 })(RealtimeModel || {});
 var RESOLUTION_BUCKETS = {
+  ["x2.0" /* x2_0 */]: [],
+  ["x2.0-pro" /* x2_0_pro */]: [
+    { width: 1024, height: 1920 },
+    { width: 1920, height: 1024 }
+  ],
   ["x2-fast-1080p" /* x2_fast_1080p */]: [
     { width: 1024, height: 1920 },
     { width: 1920, height: 1024 }
   ]
 };
 var MAXIMUM_INPUT_PIXELS = {
+  ["x2.0" /* x2_0 */]: 128e4,
+  ["x2.0-pro" /* x2_0_pro */]: 21e5,
   ["x2-fast-1080p" /* x2_fast_1080p */]: 21e5
 };
 function resolutionBuckets(model) {
@@ -495,7 +599,10 @@ function inputSizeAlignment(_model) {
 function defaultFrameRate(_model) {
   return 30;
 }
-function defaultCameraVideoFormat(_model) {
+function defaultCameraVideoFormat(model) {
+  if (model === "x2.0" /* x2_0 */) {
+    return new RealtimeVideoFormat({ width: 832, height: 1472, fps: 30 });
+  }
   return new RealtimeVideoFormat({ width: 1024, height: 1920, fps: 30 });
 }
 
@@ -521,11 +628,15 @@ var MediaService = class {
    * @param model 媒体输入规则使用的模型，默认为 `x2-fast-1080p`。
    */
   constructor(model = "x2-fast-1080p" /* x2_fast_1080p */) {
-    // 模型约束
+    /**
+     * 模型约束
+     */
     __publicField(this, "model");
     this.model = model;
   }
-  /** Web 插帧保留原始尺寸；/16 对齐由 GPU 内部补边处理，不缩小回传视频。 */
+  /**
+   * Web 插帧保留原始尺寸；/16 对齐由 GPU 内部补边处理，不缩小回传视频。
+   */
   resolveFrameInterpolationSize(size) {
     const { width, height } = size;
     if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width <= 0 || height <= 0) {
@@ -533,10 +644,15 @@ var MediaService = class {
     }
     return { width, height };
   }
-  /** WebGPU 适配器探测是异步的；实际性能和运行状态由渲染管线判断。 */
+  /**
+   * WebGPU 适配器探测是异步的；实际性能和运行状态由渲染管线判断。
+   */
   async supportsFrameInterpolation(size) {
     return await frameInterpolationAdapter(size) !== null;
   }
+  /**
+   * 按模型分辨率档位或像素预算解析输入尺寸，保持宽高比例并对齐；不支持的规格抛错。
+   */
   resolveModelInputSize(size) {
     const buckets = resolutionBuckets(this.model);
     if (buckets.length > 0) {
@@ -586,7 +702,9 @@ var MediaService = class {
       validated.height * scale
     );
   }
-  /** 在对齐网格上选择满足面积限制且最接近目标的尺寸。 */
+  /**
+   * 在对齐网格上选择满足面积限制且最接近目标的尺寸。
+   */
   boundedAlignedSize(width, height) {
     const alignment = inputSizeAlignment(this.model);
     const unitPixels = alignment * alignment;
@@ -614,7 +732,9 @@ var MediaService = class {
     }
     return bestSize;
   }
-  /** 校验尺寸为有限正数，并归一化为不小于 1 的整数。 */
+  /**
+   * 校验尺寸为有限正数，并归一化为不小于 1 的整数。
+   */
   validatedSize(size) {
     if (!Number.isFinite(size.width) || !Number.isFinite(size.height) || size.width <= 0 || size.height <= 0) {
       throw new XmaxError(
@@ -639,11 +759,20 @@ var StoredFile = class {
    * @param init.etag 对象存储返回的 ETag。
    */
   constructor(init) {
-    /** 文件的访问地址。 */
+    /**
+     * 存储结果
+     */
+    /**
+     * 文件的访问地址。
+     */
     __publicField(this, "url");
-    /** 对象存储中的对象键。 */
+    /**
+     * 对象存储中的对象键。
+     */
     __publicField(this, "objectKey");
-    /** 对象存储返回的 ETag；未返回时为空。 */
+    /**
+     * 对象存储返回的 ETag；未返回时为空。
+     */
     __publicField(this, "etag");
     this.url = init.url;
     this.objectKey = init.objectKey;
@@ -672,11 +801,17 @@ var StorageService = class _StorageService {
    * @param options.identifierGenerator 标识来源（可替换，测试用）。
    */
   constructor(options) {
-    // 服务层组件
+    /**
+     * 服务层组件
+     */
     __publicField(this, "apiService");
-    // 平台资源
+    /**
+     * 平台资源
+     */
     __publicField(this, "clientFactory");
-    // 标识生成
+    /**
+     * 标识生成
+     */
     __publicField(this, "dateGenerator");
     __publicField(this, "identifierGenerator");
     this.apiService = options.apiService;
@@ -684,7 +819,9 @@ var StorageService = class _StorageService {
     this.dateGenerator = _nullishCoalesce(options.dateGenerator, () => ( (() => /* @__PURE__ */ new Date())));
     this.identifierGenerator = _nullishCoalesce(options.identifierGenerator, () => ( (() => crypto.randomUUID().toLowerCase())));
   }
-  /** 上传图片并返回访问地址。 */
+  /**
+   * 上传图片并返回访问地址。
+   */
   async uploadImage(options) {
     const startedAt = Date.now();
     try {
@@ -734,7 +871,9 @@ var StorageService = class _StorageService {
       );
     }
   }
-  /** 获取临时存储配置；字段不完整时抛出 API 错误。 */
+  /**
+   * 获取临时存储配置；字段不完整时抛出 API 错误。
+   */
   async fetchStorageConfiguration() {
     const payload = await this.apiService.get("/cos/sts");
     const message = "Invalid storage credential payload";
@@ -755,12 +894,16 @@ var StorageService = class _StorageService {
       credentials: { accessKeyID, secretAccessKey, sessionToken }
     };
   }
-  /** 生成对象键：`${prefix}${毫秒时间戳}_${标识}_${文件名}`。 */
+  /**
+   * 生成对象键：`${prefix}${毫秒时间戳}_${标识}_${文件名}`。
+   */
   makeObjectKey(prefix, fileName) {
     const milliseconds = Math.round(this.dateGenerator().getTime());
     return `${prefix}${milliseconds}_${this.identifierGenerator()}_${fileName}`;
   }
-  /** 生产环境 COS 客户端工厂：动态加载 cos-js-sdk-v5 并按临时凭证创建客户端。 */
+  /**
+   * 生产环境 COS 客户端工厂：动态加载 cos-js-sdk-v5 并按临时凭证创建客户端。
+   */
   static async cosClientFactory(configuration) {
     const module = await Promise.resolve().then(() => _interopRequireWildcard(require("cos-js-sdk-v5")));
     const COS = module.default;
@@ -770,7 +913,9 @@ var StorageService = class _StorageService {
       SecurityToken: configuration.credentials.sessionToken
     });
   }
-  /** 调用对象存储上传并包装为 Promise。 */
+  /**
+   * 调用对象存储上传并包装为 Promise。
+   */
   static putObject(client, params) {
     return new Promise((resolve, reject) => {
       client.putObject(params, (error, data) => {
@@ -806,7 +951,9 @@ var StorageService = class _StorageService {
     }
     return `https://${configuration.bucket}.cos.${configuration.region}.myqcloud.com/${objectKey}`;
   }
-  /** 统一构造上传体。 */
+  /**
+   * 统一构造上传体。
+   */
   static makeBody(data, contentType) {
     if (data instanceof Blob) {
       return data;
@@ -814,7 +961,9 @@ var StorageService = class _StorageService {
     const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
     return new Blob([bytes], { type: contentType });
   }
-  /** 校验文件名非空且不包含路径分隔符。 */
+  /**
+   * 校验文件名非空且不包含路径分隔符。
+   */
   static validateFileName(fileName) {
     const safeName = fileName.trim();
     if (!safeName || safeName.includes("/") || safeName.includes("\\")) {
@@ -825,12 +974,16 @@ var StorageService = class _StorageService {
     }
     return safeName;
   }
-  /** 按文件名后缀推断内容类型。 */
+  /**
+   * 按文件名后缀推断内容类型。
+   */
   static inferContentType(fileName) {
     const extension = _nullishCoalesce(_optionalChain([fileName, 'access', _29 => _29.split, 'call', _30 => _30("."), 'access', _31 => _31.pop, 'call', _32 => _32(), 'optionalAccess', _33 => _33.toLowerCase, 'call', _34 => _34()]), () => ( ""));
     return _nullishCoalesce(CONTENT_TYPES[extension], () => ( "application/octet-stream"));
   }
-  /** 格式化字节数用于日志输出。 */
+  /**
+   * 格式化字节数用于日志输出。
+   */
   static formatByteCount(bytes) {
     if (bytes < 1024) {
       return `${bytes} B`;
@@ -840,10 +993,12 @@ var StorageService = class _StorageService {
     }
     return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
   }
-  /** 归一化可选字符串：去除首尾空白后为空时返回 `undefined`。 */
+  /**
+   * 归一化可选字符串：去除首尾空白后为空时返回 `undefined`。
+   */
   static nonEmpty(value) {
     const normalized = _optionalChain([value, 'optionalAccess', _35 => _35.trim, 'call', _36 => _36()]);
-    return normalized && normalized.length > 0 ? normalized : void 0;
+    return normalized || void 0;
   }
 };
 
@@ -856,12 +1011,23 @@ var CameraPosition = /* @__PURE__ */ ((CameraPosition3) => {
 
 // src/Foundation/RTC/RtcEngineManager.ts
 var RtcEngineLease = class {
+  /**
+   * 为已创建的引擎生成独占租约标识，供引擎管理器核对释放请求。
+   */
   constructor(engine) {
-    // RTC 资源
-    /** 租约持有的 TRTC 引擎实例。 */
+    /**
+     * RTC 资源
+     */
+    /**
+     * 租约持有的 TRTC 引擎实例。
+     */
     __publicField(this, "engine");
-    // 运行标识
-    /** 租约标识。 */
+    /**
+     * 运行标识
+     */
+    /**
+     * 租约标识。
+     */
     __publicField(this, "id");
     this.engine = engine;
     this.id = `lease-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
@@ -874,11 +1040,17 @@ var _RtcEngineManager = class _RtcEngineManager {
    * @param makeEngine 引擎工厂（可替换，测试用）。
    */
   constructor(makeEngine = _RtcEngineManager.defaultMakeEngine) {
-    // 依赖
+    /**
+     * 依赖
+     */
     __publicField(this, "makeEngine");
-    // RTC 资源
+    /**
+     * RTC 资源
+     */
     __publicField(this, "activeLease");
-    // 运行状态
+    /**
+     * 运行状态
+     */
     __publicField(this, "requests", []);
     this.makeEngine = makeEngine;
   }
@@ -901,7 +1073,9 @@ var _RtcEngineManager = class _RtcEngineManager {
       });
     });
   }
-  /** 释放有效租约、销毁 Engine，并把独占权交给下一个等待者。 */
+  /**
+   * 释放有效租约、销毁 Engine，并把独占权交给下一个等待者。
+   */
   release(lease) {
     if (_optionalChain([this, 'access', _37 => _37.activeLease, 'optionalAccess', _38 => _38.id]) !== lease.id) {
       return;
@@ -913,13 +1087,17 @@ var _RtcEngineManager = class _RtcEngineManager {
     }
     void this.fulfillNextRequest();
   }
-  /** 动态加载 TRTC SDK 并创建引擎实例。 */
+  /**
+   * 动态加载 TRTC SDK 并创建引擎实例。
+   */
   static async defaultMakeEngine() {
     const module = await Promise.resolve().then(() => _interopRequireWildcard(require("trtc-sdk-v5")));
     module.default.setLogLevel(5);
     return module.default.create();
   }
-  /** 创建新引擎租约。 */
+  /**
+   * 创建新引擎租约。
+   */
   async createLease() {
     const engine = await this.makeEngine();
     if (!engine) {
@@ -930,7 +1108,9 @@ var _RtcEngineManager = class _RtcEngineManager {
     }
     return new RtcEngineLease(engine);
   }
-  /** 满足下一个排队请求；创建失败时拒绝该请求并继续处理后续请求。 */
+  /**
+   * 满足下一个排队请求；创建失败时拒绝该请求并继续处理后续请求。
+   */
   async fulfillNextRequest() {
     while (!this.activeLease && this.requests.length > 0) {
       const request = this.requests.shift();
@@ -947,12 +1127,20 @@ var _RtcEngineManager = class _RtcEngineManager {
     }
   }
 };
-/** 共享实例。 */
+/**
+ * 共享管理入口
+ */
+/**
+ * 共享实例。
+ */
 __publicField(_RtcEngineManager, "shared", new _RtcEngineManager());
 var RtcEngineManager = _RtcEngineManager;
 
 // src/Foundation/RTC/RtcStatsLogger.ts
 var RtcStatsLogger = class {
+  /**
+   * 按上下行及音视频分组输出白名单统计指标，仅在 performance 日志启用时格式化。
+   */
   static logStatistics(stats) {
     XmaxLogger.rtc.info(() => {
       const blocks = [this.block("RTC \u8FD0\u884C\u7EDF\u8BA1 (RTC Statistics)", [
@@ -981,12 +1169,18 @@ var RtcStatsLogger = class {
       return blocks.join("\n\n");
     }, 2 /* performance */);
   }
+  /**
+   * 输出上下行网络质量等级、RTT 和丢包率，遵循 performance 日志开关。
+   */
   static logNetworkQuality(stats) {
     XmaxLogger.rtc.info(() => this.block("\u7F51\u7EDC\u8D28\u91CF (Network Quality Metrics)", [
       `${XmaxLogger.localized("\u672C\u5730\u4E0A\u884C\uFF1A", "Local Uplink: ")}${this.quality(stats.uplinkNetworkQuality)}, RTT ${this.value(stats.uplinkRTT, "ms")}, ${XmaxLogger.localized("\u4E22\u5305\u7387 ", "Loss ")}${this.value(stats.uplinkLoss, "%")}`,
       `${XmaxLogger.localized("\u672C\u5730\u4E0B\u884C\uFF08\u5E73\u5747\uFF09\uFF1A", "Local Downlink (Average): ")}${this.quality(stats.downlinkNetworkQuality)}, RTT ${this.value(stats.downlinkRTT, "ms")}, ${XmaxLogger.localized("\u4E22\u5305\u7387 ", "Loss ")}${this.value(stats.downlinkLoss, "%")}`
     ]), 2 /* performance */);
   }
+  /**
+   * 格式化音频码率和音量；远端音频额外包含播放延迟。
+   */
   static audioBlock(title, stats, remote) {
     return this.block(title, [
       `${XmaxLogger.localized("\u7801\u7387\uFF1A", "Bitrate: ")}${this.value(stats.bitrate, "kbps")}`,
@@ -994,6 +1188,9 @@ var RtcStatsLogger = class {
       ...remote ? this.playbackLines(stats) : []
     ]);
   }
+  /**
+   * 格式化视频流类型、尺寸、帧率和码率；远端视频额外包含播放延迟。
+   */
   static videoBlock(title, stats, remote) {
     return this.block(title, [
       `${XmaxLogger.localized("\u6D41\u7C7B\u578B\uFF1A", "Stream Type: ")}${_nullishCoalesce(stats.videoType, () => ( "\u2014"))}`,
@@ -1003,22 +1200,33 @@ var RtcStatsLogger = class {
       ...remote ? this.playbackLines(stats) : []
     ]);
   }
+  /**
+   * 格式化 TRTC 播放缓冲及估算端到端延迟，缺失或无效指标显示占位符。
+   */
   static playbackLines(stats) {
     return [
       `${XmaxLogger.localized("\u64AD\u653E\u7F13\u51B2\u5EF6\u8FDF\uFF1A", "Jitter Buffer Delay: ")}${this.value(stats.jitterBufferDelay, "ms")}`,
       `${XmaxLogger.localized("RTC \u7AEF\u5230\u7AEF\u5EF6\u8FDF\uFF08\u4F30\u7B97\uFF09\uFF1A", "RTC End-to-End Delay (Estimated): ")}${this.value(stats.point2pointDelay, "ms")}`
     ];
   }
+  /**
+   * 为指标列表添加标题和树形行前缀，生成一个控制台日志分组。
+   */
   static block(title, lines) {
     return [title, ...lines.map((line, index) => `${index === lines.length - 1 ? "\u2514\u2500" : "\u251C\u2500"} ${line}`)].join("\n");
   }
-  /** TRTC 丢包率已是百分数，无需再乘 100。 */
+  /**
+   * TRTC 丢包率已是百分数，无需再乘 100。
+   */
   static value(value, unit = "") {
     if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
       return "\u2014";
     }
     return `${Number(value.toFixed(2))}${unit ? `${unit === "%" ? "" : " "}${unit}` : ""}`;
   }
+  /**
+   * 将 TRTC 质量等级映射为本地化文案；未知等级回退为“未知”。
+   */
   static quality(value) {
     const names = [
       ["\u672A\u77E5", "Unknown"],
@@ -1057,25 +1265,39 @@ var RtcManager = class {
    * @param engineManager 引擎租约管理组件（可替换，测试用）。
    */
   constructor(engineManager = RtcEngineManager.shared) {
-    // 依赖
+    /**
+     * 依赖
+     */
     __publicField(this, "engineManager");
-    // RTC 资源
+    /**
+     * RTC 资源
+     */
     __publicField(this, "lease");
-    // 采集状态
+    /**
+     * 采集状态
+     */
     __publicField(this, "isCapturing", false);
     __publicField(this, "isAudioCapturing", false);
-    // 房间状态
+    /**
+     * 房间状态
+     */
     __publicField(this, "isInRoom", false);
-    // 事件监听
+    /**
+     * 事件监听
+     */
     __publicField(this, "eventListener");
     __publicField(this, "removeStatsListeners");
     this.engineManager = engineManager;
   }
-  /** RTC 引擎是否已初始化。 */
+  /**
+   * RTC 引擎是否已初始化。
+   */
   get isInitialized() {
     return this.lease !== void 0;
   }
-  /** 初始化 RTC 引擎（获取独占租约）并注册事件桥接；已初始化时重复调用不产生效果。 */
+  /**
+   * 初始化 RTC 引擎（获取独占租约）并注册事件桥接；已初始化时重复调用不产生效果。
+   */
   async initialize() {
     if (this.lease) {
       return;
@@ -1084,7 +1306,9 @@ var RtcManager = class {
     this.registerEventBridge(lease.engine);
     this.lease = lease;
   }
-  /** 停止采集与发布、销毁 RTC 引擎并释放租约；未初始化时重复调用不产生效果。 */
+  /**
+   * 停止采集与发布、销毁 RTC 引擎并释放租约；未初始化时重复调用不产生效果。
+   */
   async destroy() {
     const lease = this.lease;
     this.lease = void 0;
@@ -1177,7 +1401,9 @@ var RtcManager = class {
       throw this.mapError(error);
     }
   }
-  /** 停止摄像头采集；引擎未初始化或采集未启动时不产生效果。 */
+  /**
+   * 停止摄像头采集；引擎未初始化或采集未启动时不产生效果。
+   */
   async stopCameraCapture() {
     const engine = _optionalChain([this, 'access', _43 => _43.lease, 'optionalAccess', _44 => _44.engine]);
     this.isCapturing = false;
@@ -1225,7 +1451,9 @@ var RtcManager = class {
       throw this.mapError(error);
     }
   }
-  /** 离开当前 RTC 房间；未在房间中或引擎未初始化时不产生效果，退房失败仅记录日志。 */
+  /**
+   * 离开当前 RTC 房间；未在房间中或引擎未初始化时不产生效果，退房失败仅记录日志。
+   */
   async leaveRoom() {
     const engine = _optionalChain([this, 'access', _45 => _45.lease, 'optionalAccess', _46 => _46.engine]);
     if (!engine || !this.isInRoom) {
@@ -1292,7 +1520,9 @@ var RtcManager = class {
       throw this.mapError(error);
     }
   }
-  /** 停止发布本地视频流；采集保持运行，本地预览不受影响。 */
+  /**
+   * 停止发布本地视频流；采集保持运行，本地预览不受影响。
+   */
   async unpublishLocalVideo() {
     const engine = _optionalChain([this, 'access', _47 => _47.lease, 'optionalAccess', _48 => _48.engine]);
     if (!engine || !this.isCapturing) {
@@ -1322,7 +1552,9 @@ var RtcManager = class {
       throw this.mapError(error);
     }
   }
-  /** 停止发布本地音频流；麦克风采集保持运行。 */
+  /**
+   * 停止发布本地音频流；麦克风采集保持运行。
+   */
   async unpublishLocalAudio() {
     const engine = _optionalChain([this, 'access', _49 => _49.lease, 'optionalAccess', _50 => _50.engine]);
     if (!engine || !this.isAudioCapturing) {
@@ -1413,11 +1645,15 @@ var RtcManager = class {
       data: encoded.buffer
     });
   }
-  /** 设置 RTC 事件监听器，传入空值时清除监听器。 */
+  /**
+   * 设置 RTC 事件监听器，传入空值时清除监听器。
+   */
   setEventListener(listener) {
     this.eventListener = listener;
   }
-  /** 注册引擎事件桥接：媒体、消息及性能日志。 */
+  /**
+   * 注册引擎事件桥接：媒体、消息及性能日志。
+   */
   registerEventBridge(engine) {
     const source = engine;
     const onStatistics = (stats) => {
@@ -1499,7 +1735,9 @@ var RtcManager = class {
       _optionalChain([this, 'access', _77 => _77.eventListener, 'optionalAccess', _78 => _78.onCustomMessageReceived, 'call', _79 => _79(event.userId, message)]);
     });
   }
-  /** 返回当前引擎实例；未初始化时抛出错误。 */
+  /**
+   * 返回当前引擎实例；未初始化时抛出错误。
+   */
   requireEngine() {
     const engine = _optionalChain([this, 'access', _80 => _80.lease, 'optionalAccess', _81 => _81.engine]);
     if (!engine) {
@@ -1510,7 +1748,9 @@ var RtcManager = class {
     }
     return engine;
   }
-  /** 将 TRTC 错误映射为 SDK 统一错误。 */
+  /**
+   * 将 TRTC 错误映射为 SDK 统一错误。
+   */
   mapError(error) {
     if (error instanceof XmaxError) {
       return error;
@@ -1528,28 +1768,16 @@ var RtcManager = class {
   }
 };
 
-// src/Foundation/Media/Camera/CameraExposureGate.ts
-var SAMPLE_INTERVAL_MS = 80;
-var STABLE_DURATION_MS = 400;
-var TIMEOUT_MS = 5e3;
-var CameraExposureGate = class {
-  constructor() {
-    __publicField(this, "baseline");
-    __publicField(this, "lastTime");
-    __publicField(this, "count", 0);
-  }
-  reset() {
-    this.baseline = void 0;
-    this.lastTime = void 0;
-    this.count = 0;
-  }
-  /** 只接受新的采样帧；中央区域需足够亮，并在至少 400 ms 内保持稳定。 */
-  accept(pixels, time) {
+// src/Foundation/Media/Camera/CameraFrameValidator.ts
+var FALLBACK_POLL_INTERVAL_MS = 16;
+var TIMEOUT_MS = 2e3;
+var CameraFrameValidator = class {
+  /**
+   * 单帧中央区域亮度达标即放行，不等待连续帧或曝光稳定。
+   */
+  accept(pixels) {
     const size = pixels.length / 4;
-    if (!size || !Number.isInteger(size)) {
-      this.reset();
-      return false;
-    }
+    if (!size || !Number.isInteger(size)) return false;
     const histogram = new Uint32Array(256);
     let total = 0;
     let dark = 0;
@@ -1566,22 +1794,10 @@ var CameraExposureGate = class {
       if (accumulated >= size / 2) break;
     }
     const mean = total / size;
-    if (mean < 24 || median < 18 || dark / size > 0.75) {
-      this.reset();
-      return false;
-    }
-    const baseline = this.baseline;
-    const stable = baseline && this.lastTime !== void 0 && time > this.lastTime && time - this.lastTime <= 250 && Math.abs(mean - baseline.mean) <= Math.max(5, baseline.mean * 0.1) && Math.abs(median - baseline.median) <= Math.max(5, baseline.median * 0.1);
-    if (!stable) {
-      this.baseline = { mean, median, time };
-      this.count = 0;
-    }
-    this.lastTime = time;
-    this.count++;
-    return this.count >= 5 && time - this.baseline.time >= STABLE_DURATION_MS;
+    return mean >= 24 && median >= 18 && dark / size <= 0.75;
   }
 };
-function waitForCameraExposure(track, signal) {
+function waitForValidCameraFrame(track, signal) {
   return new Promise((resolve, reject) => {
     let video;
     let timeout;
@@ -1589,8 +1805,8 @@ function waitForCameraExposure(track, signal) {
     let frameCallback;
     let finished = false;
     const started = performance.now();
-    const gate = new CameraExposureGate();
-    const finish = (error) => {
+    const gate = new CameraFrameValidator();
+    const finish = (result = "valid") => {
       if (finished) return;
       finished = true;
       clearTimeout(timeout);
@@ -1603,12 +1819,19 @@ function waitForCameraExposure(track, signal) {
       }
       signal.removeEventListener("abort", abort);
       track.removeEventListener("ended", ended);
-      if (error) {
-        if (error.code !== "CANCELLED" /* cancelled */) XmaxLogger.media.warning(() => error.message);
-        reject(error);
+      if (result instanceof XmaxError) {
+        if (result.code !== "CANCELLED" /* cancelled */) XmaxLogger.media.warning(() => result.message);
+        reject(result);
       } else {
-        XmaxLogger.media.info(() => `\u76F8\u673A\u66DD\u5149\u68C0\u67E5\u901A\u8FC7 (Camera Exposure Ready)
+        if (result === "timeout") {
+          XmaxLogger.media.warning(() => XmaxLogger.localized(
+            "\u76F8\u673A\u4EAE\u5EA6\u68C0\u67E5\u8D85\u65F6\uFF0C\u6309\u5F53\u524D\u753B\u9762\u7EE7\u7EED\u751F\u6210 (Camera Frame Validation Timed Out; Continuing)\n\u2514\u2500 \u672A\u83B7\u5F97\u4EAE\u5EA6\u5408\u683C\u5E27\uFF0C\u4E0D\u518D\u7B49\u5F85\u3002",
+            "Camera Frame Validation Timed Out; Continuing\n\u2514\u2500 No sufficiently bright frame received; proceeding without further waiting."
+          ));
+        } else {
+          XmaxLogger.media.info(() => `\u76F8\u673A\u66DD\u5149\u68C0\u67E5\u901A\u8FC7 (Camera Exposure Ready)
 \u2514\u2500 ${Math.round(performance.now() - started)} ms`);
+        }
         resolve();
       }
     };
@@ -1639,21 +1862,17 @@ function waitForCameraExposure(track, signal) {
       video.srcObject = new MediaStream([track]);
       document.body.appendChild(video);
       const source = video;
-      let lastSample = -Infinity;
       let lastFrameTime = -Infinity;
-      const sample = (now, mediaTime) => {
-        if (now - lastSample < SAMPLE_INTERVAL_MS) return;
+      const sample = (mediaTime) => {
         if (source.readyState < 2 || !source.videoWidth || !source.videoHeight || track.muted || !track.enabled) {
-          gate.reset();
           return;
         }
         if (mediaTime === lastFrameTime) return;
-        lastSample = now;
         lastFrameTime = mediaTime;
         const width = source.videoWidth;
         const height = source.videoHeight;
         context.drawImage(source, width * 0.2, height * 0.2, width * 0.6, height * 0.6, 0, 0, 64, 48);
-        if (gate.accept(context.getImageData(0, 0, 64, 48).data, now)) finish();
+        if (gate.accept(context.getImageData(0, 0, 64, 48).data)) finish();
       };
       const fail = (error) => finish(new XmaxError(
         "MEDIA_ERROR" /* mediaError */,
@@ -1662,10 +1881,10 @@ function waitForCameraExposure(track, signal) {
       const schedule = () => {
         if (finished) return;
         if (typeof source.requestVideoFrameCallback === "function") {
-          frameCallback = source.requestVideoFrameCallback((now, metadata) => {
+          frameCallback = source.requestVideoFrameCallback((_now, metadata) => {
             frameCallback = void 0;
             try {
-              sample(now, metadata.mediaTime);
+              sample(metadata.mediaTime);
               schedule();
             } catch (error) {
               fail(error);
@@ -1675,22 +1894,16 @@ function waitForCameraExposure(track, signal) {
           poll = setTimeout(() => {
             try {
               const frameTime = typeof source.getVideoPlaybackQuality === "function" ? source.getVideoPlaybackQuality().totalVideoFrames : source.currentTime;
-              sample(performance.now(), frameTime);
+              sample(frameTime);
               schedule();
             } catch (error) {
               fail(error);
             }
-          }, SAMPLE_INTERVAL_MS);
+          }, FALLBACK_POLL_INTERVAL_MS);
         }
       };
-      timeout = setTimeout(() => finish(new XmaxError(
-        "CAMERA_EXPOSURE_TIMEOUT" /* cameraExposureTimeout */,
-        XmaxLogger.localized(
-          "\u76F8\u673A\u753B\u9762\u8FC7\u6697\u6216\u5C1A\u672A\u7A33\u5B9A\uFF0C\u672A\u53D1\u5E03\u89C6\u9891\u3002\u8BF7\u6539\u5584\u5149\u7167\u540E\u91CD\u8BD5\u3002",
-          "Camera frames are too dark or not stable. Video was not published. Improve lighting and retry."
-        )
-      )), TIMEOUT_MS);
-      XmaxLogger.media.info(() => "\u7B49\u5F85\u76F8\u673A\u66DD\u5149\u7A33\u5B9A (Waiting for Camera Exposure)");
+      timeout = setTimeout(() => finish("timeout"), TIMEOUT_MS);
+      XmaxLogger.media.info(() => "\u7B49\u5F85\u9996\u5F20\u4EAE\u5EA6\u5408\u683C\u5E27 (Waiting for the First Sufficiently Bright Frame)");
       void source.play().then(schedule, fail);
     } catch (error) {
       finish(new XmaxError(
@@ -1760,19 +1973,31 @@ var PermissionManager = class {
 
 // src/Service/Realtime/VideoRenderBinding.ts
 var _VideoRenderRegistry = class _VideoRenderRegistry {
-  /** @internal */
+  /**
+   * 注册轨道的自定义渲染绑定，覆盖该轨道已有的绑定。
+   * @internal
+   */
   static register(track, binding) {
     _VideoRenderRegistry.bindings.set(track, binding);
   }
-  /** @internal */
+  /**
+   * 移除轨道的渲染绑定，不执行视图解绑或资源释放。
+   * @internal
+   */
   static unregister(track) {
     _VideoRenderRegistry.bindings.delete(track);
   }
-  /** @internal */
+  /**
+   * 查询轨道的自定义渲染绑定；未注册时返回 undefined。
+   * @internal
+   */
   static binding(forTrack) {
     return _VideoRenderRegistry.bindings.get(forTrack);
   }
 };
+/**
+ * 轨道渲染绑定索引
+ */
 __publicField(_VideoRenderRegistry, "bindings", /* @__PURE__ */ new WeakMap());
 var VideoRenderRegistry = _VideoRenderRegistry;
 
@@ -1786,12 +2011,20 @@ var RealtimeVideoTrack = class {
    * @param init.position 本地相机轨道的初始摄像头位置。
    */
   constructor(init) {
-    // 轨道信息
-    /** 视频轨道标识。 */
+    /**
+     * 轨道信息
+     */
+    /**
+     * 视频轨道标识。
+     */
     __publicField(this, "id");
-    // 动态元数据
+    /**
+     * 动态元数据
+     */
     __publicField(this, "metadata");
-    // 平台资源
+    /**
+     * 平台资源
+     */
     /**
      * SDK 内部：轨道对应的 Web 媒体轨。
      * 本地轨道在采集启动后可用；远端轨道在订阅成功后可用。
@@ -1803,19 +2036,27 @@ var RealtimeVideoTrack = class {
       position: init.position
     };
   }
-  /** 当前视频轨道使用的视频格式。 */
+  /**
+   * 当前视频轨道使用的视频格式。
+   */
   get videoFormat() {
     return this.metadata.videoFormat;
   }
-  /** 本地相机轨道当前使用的摄像头位置。 */
+  /**
+   * 本地相机轨道当前使用的摄像头位置。
+   */
   get position() {
     return this.metadata.position;
   }
-  /** 更新轨道视频格式。 @internal */
+  /**
+   * 更新轨道视频格式。 @internal
+   */
   updateVideoFormat(videoFormat) {
     this.metadata.videoFormat = videoFormat;
   }
-  /** 更新轨道摄像头位置。 @internal */
+  /**
+   * 更新轨道摄像头位置。 @internal
+   */
   updatePosition(position) {
     this.metadata.position = position;
   }
@@ -1830,9 +2071,16 @@ var RealtimeMediaStream = class {
    * @param init.videoTrack 媒体流包含的视频轨道。
    */
   constructor(init) {
-    /** 媒体流标识。 */
+    /**
+     * 流标识与轨道
+     */
+    /**
+     * 媒体流标识。
+     */
     __publicField(this, "id");
-    /** 媒体流包含的视频轨道。 */
+    /**
+     * 媒体流包含的视频轨道。
+     */
     __publicField(this, "videoTrack");
     this.id = init.id;
     this.videoTrack = init.videoTrack;
@@ -1850,47 +2098,77 @@ var _CameraController = class _CameraController {
    * @param options.errorListener 运行期错误回调。
    */
   constructor(options) {
-    // 基础层组件
+    /**
+     * 基础层组件
+     */
     __publicField(this, "permissionManager");
     __publicField(this, "rtcManager");
-    // 服务层组件
+    /**
+     * 服务层组件
+     */
     __publicField(this, "mediaService");
-    // 事件监听
+    /**
+     * 事件监听
+     */
     __publicField(this, "errorListener");
     __publicField(this, "previewReadyHandler");
-    // 本地资源
+    /**
+     * 本地资源
+     */
     __publicField(this, "activeTrack");
     __publicField(this, "previewStream");
     __publicField(this, "previewMirrorApplier");
-    // 预览状态
+    /**
+     * 预览状态
+     */
     __publicField(this, "hasCapturedFrame", false);
     __publicField(this, "isPreviewAttached", false);
-    // 麦克风配置
+    /**
+     * 当前相机流配置
+     */
     __publicField(this, "storedUseMicrophone", false);
+    __publicField(this, "storedFrameValidationEnabled", true);
     this.permissionManager = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _88 => _88.permissionManager]), () => ( new PermissionManager()));
     this.rtcManager = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _89 => _89.rtcManager]), () => ( new RtcManager()));
     this.mediaService = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _90 => _90.mediaService]), () => ( new MediaService()));
     this.errorListener = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _91 => _91.errorListener]), () => ( (() => {
     })));
   }
-  /** 当前活动的本地相机视频轨道；尚未创建时为空。 */
+  /**
+   * 当前活动的本地相机视频轨道；尚未创建时为空。
+   */
   get currentTrack() {
     return this.activeTrack;
   }
-  /** 当前相机流是否配置为使用麦克风。 */
+  /**
+   * 当前相机流是否配置为使用麦克风。
+   */
   get useMicrophone() {
     return this.activeTrack !== void 0 && this.storedUseMicrophone;
   }
-  async waitUntilExposureReady(signal) {
+  /**
+   * 当前活动相机流是否启用发布前亮度检测；没有活动流时为 false。
+   */
+  get isFrameValidationEnabled() {
+    return this.activeTrack !== void 0 && this.storedFrameValidationEnabled;
+  }
+  /**
+   * 等待当前轨道首张合格帧或超时放行；禁用时跳过，取消或轨道被替换时拒绝。
+   */
+  async waitForValidCameraFrame(signal) {
     const track = this.activeTrack;
     const mediaTrack = _optionalChain([track, 'optionalAccess', _92 => _92.mediaStreamTrack]);
     if (!mediaTrack) throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Camera capture is not running");
-    await waitForCameraExposure(mediaTrack, signal);
+    if (signal.aborted) throw new XmaxError("CANCELLED" /* cancelled */, "Camera frame validation cancelled");
+    if (!this.isFrameValidationEnabled) return;
+    await waitForValidCameraFrame(mediaTrack, signal);
     if (this.activeTrack !== track || track.mediaStreamTrack !== mediaTrack) {
       throw new XmaxError("CANCELLED" /* cancelled */, "Camera track changed during exposure check");
     }
   }
-  /** 设置当前相机流的一次性内部就绪处理；条件为已收到有效帧且预览已绑定。 */
+  /**
+   * 设置当前相机流的一次性内部就绪处理；条件为已收到有效帧且预览已绑定。
+   */
   setPreviewReadyHandler(handler) {
     this.previewReadyHandler = handler;
     const track = this.activeTrack;
@@ -1904,6 +2182,7 @@ var _CameraController = class _CameraController {
    * @param options.videoFormat 期望的输出尺寸、帧率和编码配置；尺寸按模型规则调整。
    * @param options.position 首次启动时使用的摄像头位置。
    * @param options.useMicrophone 是否申请麦克风权限并允许实时连接时启动音频采集。
+   * @param options.enableFrameValidation 是否在发布前检测帧亮度，默认 true；false 跳过检测及其等待。
    * @returns 包含本地相机视频轨道的媒体流。
    * @throws 已有活动相机流、格式无效、权限不足或采集启动失败时抛出错误。
    */
@@ -1928,6 +2207,7 @@ var _CameraController = class _CameraController {
       await this.rtcManager.initialize();
       this.activeTrack = track;
       this.storedUseMicrophone = options.useMicrophone;
+      this.storedFrameValidationEnabled = _nullishCoalesce(options.enableFrameValidation, () => ( true));
       this.hasCapturedFrame = false;
       this.isPreviewAttached = false;
       this.registerPreviewBinding(track);
@@ -1946,7 +2226,9 @@ var _CameraController = class _CameraController {
       throw XmaxError.from(error);
     }
   }
-  /** 停止相机采集并销毁 RTC 引擎，释放当前轨道及本地预览资源。 */
+  /**
+   * 停止相机采集并销毁 RTC 引擎，释放当前轨道及本地预览资源。
+   */
   async stopLocalCameraStream() {
     const track = this.activeTrack;
     this.activeTrack = void 0;
@@ -1954,6 +2236,7 @@ var _CameraController = class _CameraController {
     this.previewStream = void 0;
     this.previewMirrorApplier = void 0;
     this.storedUseMicrophone = false;
+    this.storedFrameValidationEnabled = true;
     this.hasCapturedFrame = false;
     this.isPreviewAttached = false;
     await this.rtcManager.stopCameraCapture();
@@ -1996,7 +2279,9 @@ var _CameraController = class _CameraController {
     this.observeMediaTrack(track, mediaTrack);
     return new RealtimeMediaStream({ id: "stream0" /* local */, videoTrack: track });
   }
-  /** 为相机轨道注册预览渲染绑定：attach 时挂流、镜像并标记预览已绑定。 */
+  /**
+   * 为相机轨道注册预览渲染绑定：attach 时挂流、镜像并标记预览已绑定。
+   */
   registerPreviewBinding(track) {
     VideoRenderRegistry.register(track, {
       attachHandler: (view) => {
@@ -2022,7 +2307,9 @@ var _CameraController = class _CameraController {
       }
     });
   }
-  /** 监听媒体轨首帧与意外结束：首帧推进预览就绪，意外结束上报错误。 */
+  /**
+   * 监听媒体轨首帧与意外结束：首帧推进预览就绪，意外结束上报错误。
+   */
   observeMediaTrack(track, mediaTrack) {
     const isCurrent = () => this.activeTrack === track && track.mediaStreamTrack === mediaTrack;
     if (mediaTrack.muted) {
@@ -2053,7 +2340,9 @@ var _CameraController = class _CameraController {
       );
     });
   }
-  /** 满足"已收到有效帧且预览已绑定"时触发一次性就绪回调。 */
+  /**
+   * 满足"已收到有效帧且预览已绑定"时触发一次性就绪回调。
+   */
   notifyPreviewReady(track) {
     if (this.activeTrack !== track || !this.hasCapturedFrame || !this.isPreviewAttached || !this.previewReadyHandler) {
       return;
@@ -2062,7 +2351,9 @@ var _CameraController = class _CameraController {
     this.previewReadyHandler = void 0;
     handler(() => this.activeTrack === track);
   }
-  /** 按模型输入规则校验并解析目标视频规格。 */
+  /**
+   * 按模型输入规则校验并解析目标视频规格。
+   */
   resolveVideoFormat(videoFormat) {
     videoFormat.validate();
     const targetSize = this.mediaService.resolveModelInputSize({
@@ -2074,7 +2365,9 @@ var _CameraController = class _CameraController {
     return resolvedFormat;
   }
 };
-// 轨道标识
+/**
+ * 轨道标识
+ */
 __publicField(_CameraController, "localVideoTrackID", "video0");
 var CameraController = _CameraController;
 
@@ -2090,18 +2383,34 @@ var RealtimeSession = class {
    * @param init.closeReason 会话关闭原因。
    */
   constructor(init) {
-    // 会话信息
-    /** 会话标识（sessionUid）。 */
+    /**
+     * 会话信息
+     */
+    /**
+     * 会话标识（sessionUid）。
+     */
     __publicField(this, "id");
-    /** 业务用户标识。 */
+    /**
+     * 业务用户标识。
+     */
     __publicField(this, "userID");
-    // 运行状态
-    /** 会话状态（如 ACTIVE）；响应未携带时为空。 */
+    /**
+     * 运行状态
+     */
+    /**
+     * 会话状态（如 ACTIVE）；响应未携带时为空。
+     */
     __publicField(this, "status");
-    /** 会话关闭原因。 */
+    /**
+     * 会话关闭原因。
+     */
     __publicField(this, "closeReason");
-    // RTC 连接
-    /** RTC 连接参数；心跳等响应未携带完整参数时为空。 */
+    /**
+     * RTC 连接
+     */
+    /**
+     * RTC 连接参数；心跳等响应未携带完整参数时为空。
+     */
     __publicField(this, "connection");
     this.id = init.id;
     this.userID = init.userID;
@@ -2125,22 +2434,42 @@ var RealtimeSessionConnection = class {
    * @param init.botID 房间内生成 Bot 的用户标识。
    */
   constructor(init) {
-    // RTC 提供方
-    /** RTC 提供方标识（当前仅支持 `trtc`）。 */
+    /**
+     * RTC 提供方
+     */
+    /**
+     * RTC 提供方标识（当前仅支持 `trtc`）。
+     */
     __publicField(this, "provider");
-    // 进房参数
-    /** TRTC 房间号（字符串房间号）。 */
+    /**
+     * 进房参数
+     */
+    /**
+     * TRTC 房间号（字符串房间号）。
+     */
     __publicField(this, "roomID");
-    /** TRTC SDKAppID（按字符串处理）。 */
+    /**
+     * TRTC SDKAppID（按字符串处理）。
+     */
     __publicField(this, "sdkAppID");
-    /** TRTC 登录身份（`rtc_user_id`，不是业务 `user_id`）。 */
+    /**
+     * TRTC 登录身份（`rtc_user_id`，不是业务 `user_id`）。
+     */
     __publicField(this, "userID");
-    /** TRTC 登录签名。 */
+    /**
+     * TRTC 登录签名。
+     */
     __publicField(this, "userSig");
-    /** TRTC 进房鉴权字段（字符串房间号对应的 privateMapKey）。 */
+    /**
+     * TRTC 进房鉴权字段（字符串房间号对应的 privateMapKey）。
+     */
     __publicField(this, "privateMapKey");
-    // 房间成员
-    /** 房间内生成 Bot 的用户标识，用于匹配远端结果流。 */
+    /**
+     * 房间成员
+     */
+    /**
+     * 房间内生成 Bot 的用户标识，用于匹配远端结果流。
+     */
     __publicField(this, "botID");
     this.provider = init.provider;
     this.roomID = init.roomID;
@@ -2162,34 +2491,48 @@ var RealtimeSessionService = class _RealtimeSessionService {
    * @param options.sleep 心跳等待实现（可替换，测试用）。
    */
   constructor(options) {
-    // 服务层组件
+    /**
+     * 服务层组件
+     */
     __publicField(this, "apiService");
-    // 心跳配置
+    /**
+     * 心跳配置
+     */
     __publicField(this, "heartbeatIntervalMs");
     __publicField(this, "sleep");
-    // 运行状态
+    /**
+     * 运行状态
+     */
     __publicField(this, "heartbeatVersion", 0);
     this.apiService = options.apiService;
     this.heartbeatIntervalMs = _nullishCoalesce(options.heartbeatIntervalMs, () => ( 1e4));
     this.sleep = _nullishCoalesce(options.sleep, () => ( ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))));
   }
-  /** 创建实时会话并返回 RTC 连接信息。 */
+  /**
+   * 创建实时会话并返回 RTC 连接信息。
+   */
   async createSession(model) {
     const payload = await this.apiService.post("/session", {
       model
     });
     return _RealtimeSessionService.makeSession(payload, true);
   }
-  /** 启动指定会话的周期心跳；重复启动会替换当前心跳。 */
+  /**
+   * 启动指定会话的周期心跳；重复启动会替换当前心跳。
+   */
   startHeartbeat(sessionID, handlers) {
     const version = ++this.heartbeatVersion;
     void this.runHeartbeat(version, sessionID, handlers);
   }
-  /** 停止当前心跳；已经失效的迟到结果不会再触发回调。 */
+  /**
+   * 停止当前心跳；已经失效的迟到结果不会再触发回调。
+   */
   stopHeartbeat() {
     this.heartbeatVersion += 1;
   }
-  /** 关闭指定实时会话。 */
+  /**
+   * 关闭指定实时会话。
+   */
   async closeSession(sessionID) {
     try {
       await this.apiService.delete(
@@ -2199,7 +2542,9 @@ var RealtimeSessionService = class _RealtimeSessionService {
       throw XmaxError.from(error);
     }
   }
-  /** 周期心跳：等待 → 请求 → 校验会话活跃并回调刷新；失败时失效版本并回调。 */
+  /**
+   * 周期心跳：等待 → 请求 → 校验会话活跃并回调刷新；失败时失效版本并回调。
+   */
   async runHeartbeat(version, sessionID, handlers) {
     while (this.heartbeatVersion === version) {
       await this.sleep(this.heartbeatIntervalMs);
@@ -2223,14 +2568,18 @@ var RealtimeSessionService = class _RealtimeSessionService {
       }
     }
   }
-  /** 发送一次心跳请求并解析会话数据（不要求携带完整连接参数）。 */
+  /**
+   * 发送一次心跳请求并解析会话数据（不要求携带完整连接参数）。
+   */
   async heartbeatSession(sessionID) {
     const payload = await this.apiService.put(
       `/session/${sessionID}/heartbeat`
     );
     return _RealtimeSessionService.makeSession(payload, false);
   }
-  /** 校验会话仍处于活跃状态；状态明确非 ACTIVE 时抛出会话错误。 */
+  /**
+   * 校验会话仍处于活跃状态；状态明确非 ACTIVE 时抛出会话错误。
+   */
   static ensureSessionActive(session) {
     if (!session.status || session.status === "ACTIVE") {
       return;
@@ -2240,7 +2589,9 @@ var RealtimeSessionService = class _RealtimeSessionService {
       _nullishCoalesce(session.closeReason, () => ( `Session is no longer active: ${session.status}`))
     );
   }
-  /** 由会话接口数据构造会话模型；`requiresConnection` 要求携带完整 RTC 连接参数。 */
+  /**
+   * 由会话接口数据构造会话模型；`requiresConnection` 要求携带完整 RTC 连接参数。
+   */
   static makeSession(payload, requiresConnection) {
     const sessionID = _RealtimeSessionService.nonEmpty(payload.sessionUid);
     if (!sessionID) {
@@ -2261,7 +2612,9 @@ var RealtimeSessionService = class _RealtimeSessionService {
       closeReason: _RealtimeSessionService.nonEmpty(payload.closeReason)
     });
   }
-  /** 解析 `modelExtra` 中的 TRTC 连接参数；字段不完整或提供方不支持时返回空。 */
+  /**
+   * 解析 `modelExtra` 中的 TRTC 连接参数；字段不完整或提供方不支持时返回空。
+   */
   static makeConnection(modelExtra) {
     const payload = _RealtimeSessionService.decodeConnectionPayload(modelExtra);
     if (!payload) {
@@ -2290,7 +2643,9 @@ var RealtimeSessionService = class _RealtimeSessionService {
       botID: _RealtimeSessionService.nonEmpty(payload.rtc_bot_id)
     });
   }
-  /** `modelExtra` 可能为对象或 JSON 字符串，统一解析为连接参数字段。 */
+  /**
+   * `modelExtra` 可能为对象或 JSON 字符串，统一解析为连接参数字段。
+   */
   static decodeConnectionPayload(modelExtra) {
     if (typeof modelExtra === "string") {
       try {
@@ -2304,10 +2659,12 @@ var RealtimeSessionService = class _RealtimeSessionService {
     }
     return void 0;
   }
-  /** 归一化可选字符串：去除首尾空白后为空时返回 `undefined`。 */
+  /**
+   * 归一化可选字符串：去除首尾空白后为空时返回 `undefined`。
+   */
   static nonEmpty(value) {
     const normalized = _optionalChain([value, 'optionalAccess', _98 => _98.trim, 'call', _99 => _99()]);
-    return normalized && normalized.length > 0 ? normalized : void 0;
+    return normalized || void 0;
   }
 };
 
@@ -2325,6 +2682,9 @@ var RealtimeConnectionState = /* @__PURE__ */ ((RealtimeConnectionState2) => {
 var RealtimeReason = {
   normal: { kind: "normal" },
   orientationChanged: { kind: "orientationChanged" },
+  /**
+   * 将 SDK 错误包装为状态切换原因，保留错误码和原始说明。
+   */
   failure(error) {
     return { kind: "failure", error };
   }
@@ -2339,13 +2699,30 @@ var RealtimeState = class {
    * @param init.reason 状态变化原因，默认无。
    */
   constructor(init) {
-    /** 当前连接生命周期状态。 */
+    /**
+     * 连接生命周期
+     */
+    /**
+     * 当前连接生命周期状态。
+     */
     __publicField(this, "connectionState");
-    /** 当前或最近一次实时 Session 标识。 */
+    /**
+     * 业务标识
+     */
+    /**
+     * 当前或最近一次实时 Session 标识。
+     */
     __publicField(this, "sessionID");
-    /** 当前生成任务标识。 */
+    /**
+     * 当前生成任务标识。
+     */
     __publicField(this, "taskID");
-    /** 进入当前状态的原因；正常开始新的操作时清空。 */
+    /**
+     * 状态变化原因
+     */
+    /**
+     * 进入当前状态的原因；正常开始新的操作时清空。
+     */
     __publicField(this, "reason");
     this.connectionState = init.connectionState;
     this.sessionID = init.sessionID;
@@ -2371,15 +2748,23 @@ var RemoteStream = class {
    * @param init.userID 远端流所属用户标识。
    */
   constructor(init) {
-    // 流标识
-    /** 远端流所在房间号。 */
+    /**
+     * 流标识
+     */
+    /**
+     * 远端流所在房间号。
+     */
     __publicField(this, "roomID");
-    /** 远端流所属用户标识。 */
+    /**
+     * 远端流所属用户标识。
+     */
     __publicField(this, "userID");
     this.roomID = init.roomID;
     this.userID = init.userID;
   }
-  /** 跨房间唯一的远端流键。 */
+  /**
+   * 跨房间唯一的远端流键。
+   */
   get key() {
     return `${this.roomID}:${this.userID}`;
   }
@@ -2397,16 +2782,28 @@ var RoomJoinConfiguration = class {
    * @param init.privateMapKey TRTC 进房鉴权字段。
    */
   constructor(init) {
-    // 进房参数
-    /** TRTC 房间号（字符串房间号）。 */
+    /**
+     * 进房参数
+     */
+    /**
+     * TRTC 房间号（字符串房间号）。
+     */
     __publicField(this, "roomID");
-    /** TRTC 登录身份（`rtc_user_id`）。 */
+    /**
+     * TRTC 登录身份（`rtc_user_id`）。
+     */
     __publicField(this, "userID");
-    /** TRTC SDKAppID（字符串形式，进房时转换为数值）。 */
+    /**
+     * TRTC SDKAppID（字符串形式，进房时转换为数值）。
+     */
     __publicField(this, "sdkAppID");
-    /** TRTC 登录签名。 */
+    /**
+     * TRTC 登录签名。
+     */
     __publicField(this, "userSig");
-    /** TRTC 进房鉴权字段（字符串房间号对应的 privateMapKey）。 */
+    /**
+     * TRTC 进房鉴权字段（字符串房间号对应的 privateMapKey）。
+     */
     __publicField(this, "privateMapKey");
     this.roomID = init.roomID;
     this.userID = init.userID;
@@ -2418,7 +2815,9 @@ var RoomJoinConfiguration = class {
 
 // src/Stream/Room/RoomEvent.ts
 var RoomEvent = class _RoomEvent {
-  /** 生成开始信令。 */
+  /**
+   * 生成开始信令。
+   */
   static start(options) {
     return _RoomEvent.encode({
       event: "start",
@@ -2427,7 +2826,9 @@ var RoomEvent = class _RoomEvent {
       uid: options.taskID
     });
   }
-  /** 生成条件变更信令。 */
+  /**
+   * 生成条件变更信令。
+   */
   static changeCondition(options) {
     return _RoomEvent.encode({
       event: "change_condition",
@@ -2436,7 +2837,9 @@ var RoomEvent = class _RoomEvent {
       uid: options.taskID
     });
   }
-  /** 回传尺寸调整信令。 */
+  /**
+   * 回传尺寸调整信令。
+   */
   static changeTargetSize(options) {
     return _RoomEvent.encode({
       event: "change_target_size",
@@ -2450,7 +2853,9 @@ var RoomEvent = class _RoomEvent {
       uid: options.taskID
     });
   }
-  /** 生成停止信令。 */
+  /**
+   * 生成停止信令。
+   */
   static stop(options) {
     return _RoomEvent.encode({
       event: "stop",
@@ -2458,7 +2863,9 @@ var RoomEvent = class _RoomEvent {
       uid: options.taskID
     });
   }
-  /** 交互轨迹信令。 */
+  /**
+   * 交互轨迹信令。
+   */
   static tracks(options) {
     return _RoomEvent.encode({
       event: "tracks",
@@ -2467,14 +2874,18 @@ var RoomEvent = class _RoomEvent {
       uid: options.taskID
     });
   }
-  /** 房间心跳信令。 */
+  /**
+   * 房间心跳信令。
+   */
   static heartbeat(options) {
     return _RoomEvent.encode({
       event: "heartbeat",
       user_id: options.userID
     });
   }
-  /** 生成条件参数：模型、生成尺寸、回传尺寸、文本与参考图路径。 */
+  /**
+   * 生成条件参数：模型、生成尺寸、回传尺寸、文本与参考图路径。
+   */
   static generationParameters(options) {
     return {
       model: "default",
@@ -2487,7 +2898,9 @@ var RoomEvent = class _RoomEvent {
       ref_image_path: options.context.referencePath
     };
   }
-  /** 业务字段外加 `runtime` 运行环境信息并序列化为 JSON 文本。 */
+  /**
+   * 业务字段外加 `runtime` 运行环境信息并序列化为 JSON 文本。
+   */
   static encode(payload) {
     try {
       return JSON.stringify({ ...payload, runtime: RuntimeInfo.toJSON() });
@@ -2510,27 +2923,39 @@ var RoomHeartbeat = class {
    * @param options.sleep 心跳等待实现（可替换，测试用）。
    */
   constructor(options) {
-    // 基础层组件
+    /**
+     * 基础层组件
+     */
     __publicField(this, "rtcManager");
-    // 心跳配置
+    /**
+     * 心跳配置
+     */
     __publicField(this, "intervalMs");
     __publicField(this, "sleep");
-    // 运行状态
+    /**
+     * 运行状态
+     */
     __publicField(this, "cycleVersion", 0);
     this.rtcManager = options.rtcManager;
     this.intervalMs = _nullishCoalesce(options.intervalMs, () => ( 1e4));
     this.sleep = _nullishCoalesce(options.sleep, () => ( ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))));
   }
-  /** 启动周期心跳；重复启动会替换当前周期。 */
+  /**
+   * 启动周期心跳；重复启动会替换当前周期。
+   */
   start(userID) {
     const version = ++this.cycleVersion;
     void this.run(version, userID);
   }
-  /** 停止当前心跳周期；迟到结果不会再发送。 */
+  /**
+   * 停止当前心跳周期；迟到结果不会再发送。
+   */
   stop() {
     this.cycleVersion += 1;
   }
-  /** 周期循环：等待后发送心跳；发送失败仅记录日志，周期继续。 */
+  /**
+   * 周期循环：等待后发送心跳；发送失败仅记录日志，周期继续。
+   */
   async run(version, userID) {
     while (this.cycleVersion === version) {
       await this.sleep(this.intervalMs);
@@ -2556,7 +2981,9 @@ var RoomHeartbeat = class {
 var CHUNK_EVENT = "__trtc_chunk__";
 var _RoomMessageCodec = class _RoomMessageCodec {
   constructor() {
-    // 接收缓存
+    /**
+     * 接收缓存
+     */
     __publicField(this, "records", /* @__PURE__ */ new Map());
   }
   /**
@@ -2592,13 +3019,20 @@ var _RoomMessageCodec = class _RoomMessageCodec {
   /**
    * 处理入站消息。
    *
-   * @returns 普通业务消息原样返回；分片未收齐或组包结果不是合法
-   * JSON 时返回 `undefined`；分片收齐后返回完整消息并从缓存移除。
+   * @returns 返回解析后的业务消息；分片未收齐或 JSON 非法时返回
+   * `undefined`；分片收齐后从缓存移除并解析完整消息。
    */
   processIncoming(senderUserID, message) {
-    const chunk = _RoomMessageCodec.parseChunk(message);
+    let parsed;
+    try {
+      parsed = JSON.parse(message);
+    } catch (e12) {
+      XmaxLogger.room.warning(() => "\u623F\u95F4\u6D88\u606F\u4E0D\u662F\u5408\u6CD5 JSON (Room Message Is Not Valid JSON)");
+      return void 0;
+    }
+    const chunk = _RoomMessageCodec.parseChunk(parsed);
     if (!chunk) {
-      return message;
+      return parsed;
     }
     const key = `${senderUserID}:${chunk.eventId}`;
     let record = this.records.get(key);
@@ -2622,28 +3056,25 @@ var _RoomMessageCodec = class _RoomMessageCodec {
     }
     const joined = parts.join("");
     try {
-      JSON.parse(joined);
-    } catch (e12) {
+      return JSON.parse(joined);
+    } catch (e13) {
       XmaxLogger.room.warning(
         () => `\u623F\u95F4\u6D88\u606F\u7EC4\u5305\u540E\u4E0D\u662F\u5408\u6CD5 JSON (Reassembled Message Is Not Valid JSON)
 \u2514\u2500 eventId: ${chunk.eventId}`
       );
       return void 0;
     }
-    return joined;
   }
-  /** 清空未完成的组包缓存。 */
+  /**
+   * 清空未完成的组包缓存。
+   */
   reset() {
     this.records.clear();
   }
-  /** 识别分片消息；字段不完整时按普通业务消息处理。 */
-  static parseChunk(message) {
-    let parsed;
-    try {
-      parsed = JSON.parse(message);
-    } catch (e13) {
-      return void 0;
-    }
+  /**
+   * 从已解析的值识别分片消息；字段不完整时按普通业务消息处理。
+   */
+  static parseChunk(parsed) {
     if (typeof parsed !== "object" || parsed === null) {
       return void 0;
     }
@@ -2658,7 +3089,9 @@ var _RoomMessageCodec = class _RoomMessageCodec {
     }
     return { eventId: record.eventId, index, count, data: record.data };
   }
-  /** 淘汰最旧的未完成记录，保持缓存不超过上限。 */
+  /**
+   * 淘汰最旧的未完成记录，保持缓存不超过上限。
+   */
   evictOverflow() {
     while (this.records.size > _RoomMessageCodec.cacheLimit) {
       const oldest = this.records.keys().next().value;
@@ -2668,7 +3101,9 @@ var _RoomMessageCodec = class _RoomMessageCodec {
       this.records.delete(oldest);
     }
   }
-  /** 按 UTF-8 字节预算切分字符串，不拆分多字节字符。 */
+  /**
+   * 按 UTF-8 字节预算切分字符串，不拆分多字节字符。
+   */
   static sliceByByteBudget(message, budget) {
     const slices = [];
     let current = "";
@@ -2688,11 +3123,15 @@ var _RoomMessageCodec = class _RoomMessageCodec {
     }
     return slices;
   }
-  /** 计算字符串的 UTF-8 字节长度。 */
+  /**
+   * 计算字符串的 UTF-8 字节长度。
+   */
   static byteLength(value) {
     return new TextEncoder().encode(value).byteLength;
   }
-  /** 生成拆包事件标识（32 位十六进制）。 */
+  /**
+   * 生成拆包事件标识（32 位十六进制）。
+   */
   static makeEventId() {
     if (typeof crypto !== "undefined" && crypto.randomUUID) {
       return crypto.randomUUID().replace(/-/g, "");
@@ -2703,12 +3142,20 @@ var _RoomMessageCodec = class _RoomMessageCodec {
     ).join("");
   }
 };
-// 协议常量
-/** 触发拆包的消息字节阈值。 */
+/**
+ * 协议常量
+ */
+/**
+ * 触发拆包的消息字节阈值。
+ */
 __publicField(_RoomMessageCodec, "chunkThresholdBytes", 800);
-/** 单个分片正文的字节预算，保证分片 JSON 自身不超过阈值。 */
+/**
+ * 单个分片正文的字节预算，保证分片 JSON 自身不超过阈值。
+ */
 __publicField(_RoomMessageCodec, "chunkDataBudgetBytes", 600);
-/** 未完成组包记录的缓存上限（LRU）。 */
+/**
+ * 未完成组包记录的缓存上限（LRU）。
+ */
 __publicField(_RoomMessageCodec, "cacheLimit", 1e3);
 var RoomMessageCodec = _RoomMessageCodec;
 
@@ -2722,14 +3169,22 @@ var RoomController = class {
    * @param options.codec 房间消息编解码组件（可替换，测试用）。
    */
   constructor(options) {
-    // 基础层组件
+    /**
+     * 基础层组件
+     */
     __publicField(this, "rtcManager");
-    // 传输层组件
+    /**
+     * 传输层组件
+     */
     __publicField(this, "heartbeat");
     __publicField(this, "codec");
-    // 事件监听
+    /**
+     * 事件监听
+     */
     __publicField(this, "listener");
-    // 房间资源
+    /**
+     * 房间资源
+     */
     __publicField(this, "state", { kind: "idle" });
     __publicField(this, "leaveOperation");
     this.rtcManager = options.rtcManager;
@@ -2784,7 +3239,9 @@ var RoomController = class {
       throw XmaxError.from(error);
     }
   }
-  /** 停止房间心跳并离开当前 RTC 房间；并发的离开操作共享同一个任务。 */
+  /**
+   * 停止房间心跳并离开当前 RTC 房间；并发的离开操作共享同一个任务。
+   */
   async leave() {
     if (this.leaveOperation) {
       await this.leaveOperation;
@@ -2844,14 +3301,18 @@ var RoomController = class {
       })
     );
   }
-  /** 尝试发送生成停止信令；未进房或任务标识为空时忽略。 */
+  /**
+   * 尝试发送生成停止信令；未进房或任务标识为空时忽略。
+   */
   stopGeneration(taskID) {
     if (!taskID || this.state.kind !== "joined") {
       return;
     }
     this.send(RoomEvent.stop({ userID: this.state.userID, taskID }));
   }
-  /** 发送生成任务的交互轨迹；任务标识或轨迹为空时忽略。 */
+  /**
+   * 发送生成任务的交互轨迹；任务标识或轨迹为空时忽略。
+   */
   sendTracks(taskID, points) {
     if (!taskID || points.length === 0) {
       return;
@@ -2864,11 +3325,15 @@ var RoomController = class {
       })
     );
   }
-  /** 设置房间事件监听器，传入空值时清除监听器。 */
+  /**
+   * 设置房间事件监听器，传入空值时清除监听器。
+   */
   setListener(listener) {
     this.listener = listener;
   }
-  /** 执行离开：复位状态、停止心跳、清空组包缓存并退房。 */
+  /**
+   * 执行离开：复位状态、停止心跳、清空组包缓存并退房。
+   */
   async performLeave() {
     this.state = { kind: "idle" };
     this.heartbeat.stop();
@@ -2876,19 +3341,11 @@ var RoomController = class {
     await this.rtcManager.leaveRoom();
     this.leaveOperation = void 0;
   }
-  /** 组包入站消息并按目标用户过滤后分发完整业务消息。 */
+  /**
+   * 组包入站消息并按目标用户过滤后分发完整业务消息。
+   */
   handleIncomingMessage(senderUserID, raw) {
-    const complete = this.codec.processIncoming(senderUserID, raw);
-    if (complete === void 0) {
-      return;
-    }
-    let parsed;
-    try {
-      parsed = JSON.parse(complete);
-    } catch (e14) {
-      XmaxLogger.room.warning(() => "\u623F\u95F4\u6D88\u606F\u4E0D\u662F\u5408\u6CD5 JSON (Room Message Is Not Valid JSON)");
-      return;
-    }
+    const parsed = this.codec.processIncoming(senderUserID, raw);
     if (typeof parsed !== "object" || parsed === null) {
       return;
     }
@@ -2900,7 +3357,9 @@ var RoomController = class {
     }
     _optionalChain([this, 'access', _104 => _104.listener, 'optionalAccess', _105 => _105.onRoomMessage, 'call', _106 => _106(senderUserID, message)]);
   }
-  /** 发送房间信令并输出日志。 */
+  /**
+   * 发送房间信令并输出日志。
+   */
   send(message) {
     for (const packet of this.codec.encodeOutgoing(message)) {
       try {
@@ -2915,7 +3374,9 @@ var RoomController = class {
 ${JSON.stringify(JSON.parse(message), null, 2)}`
     );
   }
-  /** 返回当前房间中的用户标识；未进房时抛出错误。 */
+  /**
+   * 返回当前房间中的用户标识；未进房时抛出错误。
+   */
   requireUserID() {
     if (this.state.kind !== "joined") {
       throw new XmaxError("RTC_ERROR" /* rtcError */, "RTC room is not joined");
@@ -2936,10 +3397,15 @@ var _EncodingController = class _EncodingController {
    * @param options.rtcManager RTC 引擎与媒体传输组件。
    */
   constructor(options) {
-    // 基础层组件
+    /**
+     * 基础层组件
+     */
     __publicField(this, "rtcManager");
     this.rtcManager = options.rtcManager;
   }
+  /**
+   * 校验视频格式，解析显式或推荐码率范围后配置 RTC 编码器；参数或配置失败时抛错。
+   */
   async configure(videoFormat) {
     videoFormat.validate();
     let minimum;
@@ -2959,8 +3425,8 @@ var _EncodingController = class _EncodingController {
           "Realtime video format exceeds the supported bitrate range"
         );
       }
-      const defaultMinimum = Math.max(1, Math.trunc(Math.round(bitrates.minimum)));
-      const defaultMaximum = Math.max(defaultMinimum + 1, Math.trunc(maximumBitrate));
+      const defaultMinimum = Math.max(1, Math.round(bitrates.minimum));
+      const defaultMaximum = Math.max(defaultMinimum + 1, maximumBitrate);
       minimum = _nullishCoalesce(videoFormat.minimumBitrate, () => ( defaultMinimum));
       maximum = _nullishCoalesce(videoFormat.maximumBitrate, () => ( defaultMaximum));
     }
@@ -2979,7 +3445,9 @@ var _EncodingController = class _EncodingController {
       encoderPreference: ENCODER_PREFERENCE_MAP[videoFormat.encoderPreference]
     });
   }
-  /** 按像素面积与帧率计算码率区间（kbps）：流畅优先为最低，画质优先为最高。 */
+  /**
+   * 按像素面积与帧率计算码率区间（kbps）：流畅优先为最低，画质优先为最高。
+   */
   static resolveBitrates(pixels, fps) {
     const bitrate15 = _EncodingController.interpolate(
       pixels,
@@ -3017,7 +3485,9 @@ var _EncodingController = class _EncodingController {
       ])
     };
   }
-  /** 在相邻参考点间线性插值，表外按最近端点的比例外推。 */
+  /**
+   * 在相邻参考点间线性插值，表外按最近端点的比例外推。
+   */
   static interpolate(value, points) {
     const first = points[0];
     if (value <= first.value) {
@@ -3035,7 +3505,9 @@ var _EncodingController = class _EncodingController {
     return last.bitrate * (value / last.value);
   }
 };
-// 流畅优先码率参考，按像素面积升序排列，单位为 kbps。
+/**
+ * 流畅优先码率参考，按像素面积升序排列，单位为 kbps。
+ */
 __publicField(_EncodingController, "referenceBitratesAt15FPS", [
   { value: 120 * 120, bitrate: 50 },
   { value: 160 * 120, bitrate: 65 },
@@ -3088,22 +3560,34 @@ var StreamController = class {
    * @param options.generationTimeoutMs 生成开始确认超时时间（毫秒）；默认 30 秒。
    */
   constructor(options) {
-    // 基础层组件
+    /**
+     * 基础层组件
+     */
     __publicField(this, "rtcManager");
-    // 传输层组件
+    /**
+     * 传输层组件
+     */
     __publicField(this, "roomController");
     __publicField(this, "encodingController");
-    // 事件监听
+    /**
+     * 事件监听
+     */
     __publicField(this, "errorListener");
     __publicField(this, "remoteStreamListener");
     __publicField(this, "localVideoStatisticsListener");
     __publicField(this, "networkStatisticsListener");
     __publicField(this, "remoteVideoStatisticsListener");
-    // 生成配置
+    /**
+     * 生成配置
+     */
     __publicField(this, "generationTimeoutMs");
-    // 音频配置
+    /**
+     * 音频配置
+     */
     __publicField(this, "remoteAudioVolumePercentage", 100);
-    // 运行状态
+    /**
+     * 运行状态
+     */
     __publicField(this, "state", makeInitialState());
     this.rtcManager = options.rtcManager;
     this.roomController = _nullishCoalesce(options.roomController, () => ( new RoomController({ rtcManager: options.rtcManager })));
@@ -3138,27 +3622,39 @@ var StreamController = class {
       }
     });
   }
-  /** 当前是否存在正在启动或已经运行的生成任务。 */
+  /**
+   * 当前是否存在正在启动或已经运行的生成任务。
+   */
   get hasGenerationTask() {
     return this.state.generationTaskID !== void 0;
   }
-  /** 设置本地主视频流统计监听器，不改变 RTC 事件监听权。 */
+  /**
+   * 设置本地主视频流统计监听器，不改变 RTC 事件监听权。
+   */
   setLocalVideoStatisticsListener(listener) {
     this.localVideoStatisticsListener = listener;
   }
-  /** 网络统计不按远端用户过滤，连接发布完成后即可回调。 */
+  /**
+   * 网络统计不按远端用户过滤，连接发布完成后即可回调。
+   */
   setNetworkStatisticsListener(listener) {
     this.networkStatisticsListener = listener;
   }
-  /** 监听当前实际生成结果流的统计，不按会话下发的 botID 猜测结果流身份。 */
+  /**
+   * 监听当前实际生成结果流的统计，不按会话下发的 botID 猜测结果流身份。
+   */
   setRemoteVideoStatisticsListener(listener) {
     this.remoteVideoStatisticsListener = listener;
   }
-  /** 当前远端生成音频播放音量，取值范围为 `0...1`。 */
+  /**
+   * 当前远端生成音频播放音量，取值范围为 `0...1`。
+   */
   get remoteAudioVolume() {
     return this.remoteAudioVolumePercentage / 100;
   }
-  /** 设置远端生成音频播放音量，并应用到所有已订阅的远端音频。 */
+  /**
+   * 设置远端生成音频播放音量，并应用到所有已订阅的远端音频。
+   */
   setRemoteAudioVolume(volume) {
     const rtcVolume = Math.min(Math.max(Math.round(volume * 100), 0), 100);
     for (const userID of [...this.state.subscribedRemoteAudioUserIDs].sort()) {
@@ -3191,7 +3687,9 @@ var StreamController = class {
     ensureActive();
     await this.publishLocalStream(includeLocalAudio);
   }
-  /** 清理生成状态、本地发布和远端订阅，并离开当前 RTC 房间。 */
+  /**
+   * 清理生成状态、本地发布和远端订阅，并离开当前 RTC 房间。
+   */
   async disconnect() {
     await this.resetStream();
     await this.roomController.leave();
@@ -3256,7 +3754,7 @@ var StreamController = class {
       this.rejectGenerationStart(taskID, mapped);
       try {
         this.roomController.stopGeneration(taskID);
-      } catch (e15) {
+      } catch (e14) {
       }
       throw mapped;
     }
@@ -3334,11 +3832,15 @@ var StreamController = class {
       throw XmaxError.from(error);
     }
   }
-  /** 设置房间业务消息监听器，传入空值时清除监听器。 */
+  /**
+   * 设置房间业务消息监听器，传入空值时清除监听器。
+   */
   setRoomListener(listener) {
     this.roomController.setListener(listener);
   }
-  /** 配置当前房间；已有发布、订阅或生成任务时拒绝重新配置。 */
+  /**
+   * 配置当前房间；已有发布、订阅或生成任务时拒绝重新配置。
+   */
   configureRoom(options) {
     const roomID = options.roomID.trim();
     const botID = _nullishCoalesce(_optionalChain([options, 'access', _117 => _117.botID, 'optionalAccess', _118 => _118.trim, 'call', _119 => _119()]), () => ( ""));
@@ -3357,7 +3859,9 @@ var StreamController = class {
     this.state.roomID = roomID;
     this.state.botID = botID;
   }
-  /** 发布本地视频，按需发布本地音频；音频发布失败时回滚视频发布。 */
+  /**
+   * 发布本地视频，按需发布本地音频；音频发布失败时回滚视频发布。
+   */
   async publishLocalStream(includeAudio) {
     if (!this.state.roomID) {
       throw new XmaxError(
@@ -3383,7 +3887,9 @@ var StreamController = class {
       throw XmaxError.from(error);
     }
   }
-  /** 处理远端视频发布状态变化：按机器人标识过滤后订阅或清理。 */
+  /**
+   * 处理远端视频发布状态变化：按机器人标识过滤后订阅或清理。
+   */
   async handleRemoteVideoPublished(userID, published) {
     const trimmedUserID = userID.trim();
     if (!trimmedUserID) {
@@ -3420,7 +3926,9 @@ var StreamController = class {
       this.clearRemoteStream();
     }
   }
-  /** 订阅远端视频并在成功后就绪或确认生成任务。 */
+  /**
+   * 订阅远端视频并在成功后就绪或确认生成任务。
+   */
   async subscribeRemoteVideo(userID) {
     if (this.state.subscribedRemoteUserIDs.has(userID)) {
       return;
@@ -3452,7 +3960,9 @@ var StreamController = class {
       }
     }
   }
-  /** 订阅成功后就绪远端流：有待确认的生成任务时确认它，否则更新当前绑定。 */
+  /**
+   * 订阅成功后就绪远端流：有待确认的生成任务时确认它，否则更新当前绑定。
+   */
   confirmOrUpdateRemoteStream(userID, track) {
     const waiter = this.state.generationWaiter;
     const taskID = this.state.generationTaskID;
@@ -3485,7 +3995,9 @@ var StreamController = class {
       }
     }
   }
-  /** 订阅远端音频：先应用当前音量再订阅。 */
+  /**
+   * 订阅远端音频：先应用当前音量再订阅。
+   */
   async subscribeRemoteAudio(userID) {
     if (this.state.subscribedRemoteAudioUserIDs.has(userID)) {
       return;
@@ -3494,7 +4006,9 @@ var StreamController = class {
     await this.rtcManager.subscribeRemoteAudio(userID, true);
     this.state.subscribedRemoteAudioUserIDs.add(userID);
   }
-  /** 取消订阅远端音频；失败仅记录日志。 */
+  /**
+   * 取消订阅远端音频；失败仅记录日志。
+   */
   async unsubscribeRemoteAudio(userID) {
     if (!this.state.subscribedRemoteAudioUserIDs.delete(userID)) {
       return;
@@ -3533,7 +4047,9 @@ var StreamController = class {
     this.clearRemoteStream();
     return currentTaskID;
   }
-  /** 复位传输层：停止生成、取消全部远端订阅、取消本地发布。 */
+  /**
+   * 复位传输层：停止生成、取消全部远端订阅、取消本地发布。
+   */
   async resetStream() {
     await this.stopStreamGeneration("");
     const previousState = this.state;
@@ -3559,7 +4075,9 @@ var StreamController = class {
       );
     }
   }
-  /** 确认生成开始：清理等待器并兑现确认 Promise。 */
+  /**
+   * 确认生成开始：清理等待器并兑现确认 Promise。
+   */
   resolveGenerationStart(taskID) {
     const waiter = this.state.generationWaiter;
     if (this.state.generationTaskID !== taskID || _optionalChain([waiter, 'optionalAccess', _123 => _123.taskID]) !== taskID) {
@@ -3569,7 +4087,9 @@ var StreamController = class {
     clearTimeout(waiter.timeoutTimer);
     waiter.resolve();
   }
-  /** 拒绝生成开始：清理等待器并拒绝确认 Promise。 */
+  /**
+   * 拒绝生成开始：清理等待器并拒绝确认 Promise。
+   */
   rejectGenerationStart(taskID, error) {
     const waiter = this.state.generationWaiter;
     if (this.state.generationTaskID !== taskID || _optionalChain([waiter, 'optionalAccess', _124 => _124.taskID]) !== taskID) {
@@ -3579,7 +4099,9 @@ var StreamController = class {
     clearTimeout(waiter.timeoutTimer);
     waiter.reject(error);
   }
-  /** 通知渲染层清理远端生成流；失败仅记录日志。 */
+  /**
+   * 通知渲染层清理远端生成流；失败仅记录日志。
+   */
   clearRemoteStream() {
     _optionalChain([this, 'access', _125 => _125.remoteVideoStatisticsListener, 'optionalCall', _126 => _126(void 0)]);
     try {
@@ -3591,7 +4113,9 @@ var StreamController = class {
       );
     }
   }
-  /** 回滚本地视频发布；失败仅记录日志。 */
+  /**
+   * 回滚本地视频发布；失败仅记录日志。
+   */
   async rollbackLocalVideoPublication() {
     await this.performCleanup(
       "\u56DE\u6EDA RTC \u672C\u5730\u89C6\u9891\u53D1\u5E03\u5931\u8D25 (Failed to Roll Back RTC Local Video Publication)",
@@ -3601,7 +4125,9 @@ var StreamController = class {
       }
     );
   }
-  /** 执行清理动作；失败仅记录日志。 */
+  /**
+   * 执行清理动作；失败仅记录日志。
+   */
   async performCleanup(title, action) {
     try {
       await action();
@@ -3622,31 +4148,52 @@ function scopeAffects(scope, kind) {
   return kind !== "media" /* media */;
 }
 var OperationLease = class {
+  /**
+   * 创建操作租约；未指定失败范围时不自动扩大资源清理范围。
+   */
   constructor(failureScope) {
-    // 并发状态
+    /**
+     * 并发状态
+     */
     __publicField(this, "valid", true);
     __publicField(this, "terminalError");
     __publicField(this, "storedFailureScope");
     __publicField(this, "abortController", new AbortController());
     this.storedFailureScope = failureScope;
   }
+  /**
+   * 租约是否仍然有效，可用于异步结果提交前的快速判断。
+   */
   get isCurrent() {
     return this.valid;
   }
+  /**
+   * 首次使租约失效的错误；主动取消且未指定原因时为空。
+   */
   get failure() {
     return this.terminalError;
   }
+  /**
+   * 当前操作失败或取消时需要清理的资源范围。
+   */
   get failureScope() {
     return this.storedFailureScope;
   }
+  /**
+   * 租约失效时同步触发的取消信号。
+   */
   get signal() {
     return this.abortController.signal;
   }
-  /** 更新当前操作失败或被调用方取消时需要释放的资源范围。 */
+  /**
+   * 更新当前操作失败或被调用方取消时需要释放的资源范围。
+   */
   setFailureScope(scope) {
     this.storedFailureScope = scope;
   }
-  /** 作废租约并触发中止信号；首个终止原因被保留。 */
+  /**
+   * 作废租约并触发中止信号；首个终止原因被保留。
+   */
   invalidate(error) {
     this.valid = false;
     if (!this.terminalError) {
@@ -3654,7 +4201,9 @@ var OperationLease = class {
     }
     this.abortController.abort();
   }
-  /** 在异步边界后校验当前操作仍拥有实时生命周期。 */
+  /**
+   * 在异步边界后校验当前操作仍拥有实时生命周期。
+   */
   ensureCurrent() {
     if (!this.valid) {
       throw _nullishCoalesce(this.terminalError, () => ( RealtimeCoordinator.cancelledError()));
@@ -3663,22 +4212,33 @@ var OperationLease = class {
 };
 var operationSequence = 0;
 var RealtimeCoordinator = class _RealtimeCoordinator {
+  /**
+   * 注入错误分发与资源清理逻辑，初始状态为 idle。
+   */
   constructor(options) {
-    // 业务组件
+    /**
+     * 业务组件
+     */
     __publicField(this, "errorHandler");
     __publicField(this, "cleanup");
-    // 状态管理
+    /**
+     * 状态管理
+     */
     __publicField(this, "state", new RealtimeState({
       connectionState: "Idle" /* idle */
     }));
     __publicField(this, "stateListener");
-    // 操作管理
+    /**
+     * 操作管理
+     */
     __publicField(this, "activeOperation");
     __publicField(this, "termination");
     this.errorHandler = options.errorHandler;
     this.cleanup = options.cleanup;
   }
-  /** 当前实时状态快照。 */
+  /**
+   * 当前实时状态快照。
+   */
   get currentState() {
     return this.state;
   }
@@ -3734,12 +4294,16 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
       return this.handleFailure(error, operation);
     }
   }
-  /** 仅当前操作可以提交新的公开状态。 */
+  /**
+   * 仅当前操作可以提交新的公开状态。
+   */
   async commit(nextState, token) {
     token.ensureCurrent();
     await this.setState(nextState);
   }
-  /** 当前本地预览满足就绪条件后，结束媒体准备状态。 */
+  /**
+   * 当前本地预览满足就绪条件后，结束媒体准备状态。
+   */
   async localPreviewDidBecomeReady(isCurrent) {
     if (this.state.connectionState !== "Preparing" /* preparing */ || !isCurrent()) {
       return;
@@ -3748,12 +4312,16 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
       new RealtimeState({ connectionState: "Ready" /* ready */ })
     );
   }
-  /** 断开实时连接；尚未提交连接状态的活跃操作也会被取消。 */
+  /**
+   * 断开实时连接；尚未提交连接状态的活跃操作也会被取消。
+   */
   async disconnect(reason = RealtimeReason.normal) {
     const task = await this.beginDisconnect(reason);
     await task;
   }
-  /** 发起断开并返回收尾任务，使本地媒体调整不必等待网络资源释放。 */
+  /**
+   * 发起断开并返回收尾任务，使本地媒体调整不必等待网络资源释放。
+   */
   async beginDisconnect(reason) {
     const hasConnectionOperation = this.activeOperation ? scopeAffects(0 /* connection */, this.activeOperation.kind) : false;
     const state2 = this.state.connectionState;
@@ -3767,12 +4335,16 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
       reason
     );
   }
-  /** 终止指定范围并等待资源清理完成；并发终止请求会合并为最大范围。 */
+  /**
+   * 终止指定范围并等待资源清理完成；并发终止请求会合并为最大范围。
+   */
   async terminate(target, reason = RealtimeReason.normal) {
     const task = await this.requestTermination(target, void 0, reason);
     await task;
   }
-  /** 清理仍属于当前生命周期的后台故障，并通过最终状态提供原因。 */
+  /**
+   * 清理仍属于当前生命周期的后台故障，并通过最终状态提供原因。
+   */
   async terminateWithError(error, target, isCurrent = () => true) {
     if (!isCurrent()) {
       return;
@@ -3787,7 +4359,9 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
     );
     await task;
   }
-  /** 操作失败处理：取消走终止流程，错误按失败范围清理或直接上报。 */
+  /**
+   * 操作失败处理：取消走终止流程，错误按失败范围清理或直接上报。
+   */
   async handleFailure(error, operation) {
     const operationWasCancelled = error instanceof XmaxError && error.code === "CANCELLED" /* cancelled */ || error instanceof DOMException && error.name === "AbortError" || !operation.lease.isCurrent;
     if (operationWasCancelled) {
@@ -3832,7 +4406,9 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
     this.finish(operation);
     throw resolvedError;
   }
-  /** 发起或合并终止请求，作废旧操作并进入断开中状态。 */
+  /**
+   * 发起或合并终止请求，作废旧操作并进入断开中状态。
+   */
   async requestTermination(target, error, reason, origin) {
     let pending = this.termination;
     if (pending) {
@@ -3875,7 +4451,9 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
     );
     return pending.task;
   }
-  /** 执行终止：等待旧操作收尾，分级清理资源，提交最终状态。 */
+  /**
+   * 执行终止：等待旧操作收尾，分级清理资源，提交最终状态。
+   */
   async performTermination(id) {
     const pending = this.termination;
     if (!pending || pending.id !== id) {
@@ -3921,13 +4499,17 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
       return;
     }
   }
-  /** 结束指定操作，释放操作准入场。 */
+  /**
+   * 结束指定操作，释放操作准入场。
+   */
   finish(operation) {
     if (_optionalChain([this, 'access', _129 => _129.activeOperation, 'optionalAccess', _130 => _130.id]) === operation.id) {
       this.activeOperation = void 0;
     }
   }
-  /** 提交新状态并通知监听器；状态未变化时不通知。 */
+  /**
+   * 提交新状态并通知监听器；状态未变化时不通知。
+   */
   async setState(nextState) {
     if (this.state.equals(nextState)) {
       return;
@@ -3935,7 +4517,9 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
     this.state = nextState;
     _optionalChain([this, 'access', _131 => _131.stateListener, 'optionalCall', _132 => _132(nextState)]);
   }
-  /** 构造统一的操作取消错误。 */
+  /**
+   * 构造统一的操作取消错误。
+   */
   static cancelledError() {
     return new XmaxError(
       "CANCELLED" /* cancelled */,
@@ -3947,10 +4531,14 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
 // src/Core/Realtime/RealtimeErrorHandler.ts
 var RealtimeErrorHandler = class {
   constructor() {
-    // 运行状态
+    /**
+     * 运行状态
+     */
     __publicField(this, "pendingFailures", []);
   }
-  /** 上报错误；当前通过日志输出，后续里程碑接入状态原因上报。 */
+  /**
+   * 上报错误；当前通过日志输出，后续里程碑接入状态原因上报。
+   */
   async report(error) {
     if (error.code === "CANCELLED" /* cancelled */) {
       return;
@@ -3961,7 +4549,9 @@ var RealtimeErrorHandler = class {
 \u2514\u2500 ${XmaxLogger.localized("\u539F\u56E0\uFF1A", "Reason: ")}${error.code} ${error.message}`
     );
   }
-  /** 清理仍属于已终止生命周期的后台故障。 */
+  /**
+   * 清理仍属于已终止生命周期的后台故障。
+   */
   invalidatePendingFailures(_target) {
     this.pendingFailures = [];
   }
@@ -3970,16 +4560,28 @@ var RealtimeErrorHandler = class {
 // src/Core/Realtime/RealtimeLaunchTimer.ts
 var RealtimeLaunchTimer = class {
   constructor() {
+    /**
+     * 统计快照与观察者
+     */
     __publicField(this, "snapshot", Object.freeze({}));
     __publicField(this, "listener");
+    /**
+     * 当前启动周期与计时起点
+     */
     __publicField(this, "sequence", 0);
     __publicField(this, "active", false);
     __publicField(this, "startedAt", 0);
   }
+  /**
+   * 设置统计监听器并立即回放当前快照；传 undefined 取消监听。
+   */
   setListener(listener) {
     this.listener = listener;
     this.notify();
   }
+  /**
+   * 开始新的启动周期并清空旧快照，返回记录相机创建完成的一次性回调。
+   */
   startCamera() {
     this.sequence += 1;
     this.active = true;
@@ -3989,17 +4591,34 @@ var RealtimeLaunchTimer = class {
     this.notify();
     return complete;
   }
+  /**
+   * 开始会话与进房计时，返回连接阶段完成时调用的记录函数。
+   */
   startConnection() {
     return this.measure("connectionMs", performance.now());
   }
+  /**
+   * 开始亮度检测计时；合格帧到达或超时放行时调用返回的记录函数。
+   */
+  startFrameValidation() {
+    return this.measure("frameValidationMs", performance.now());
+  }
+  /**
+   * 开始等待远端显示首帧；完成回调同时记录首帧耗时和实际总耗时。
+   */
   startFirstFrame() {
     return this.measure("firstFrameMs", performance.now());
   }
-  /** 冻结本轮结果，令尚未完成的回调失效；下一轮相机启动才重置。 */
+  /**
+   * 冻结本轮结果，令尚未完成的回调失效；下一轮相机启动才重置。
+   */
   cancel() {
     this.active = false;
     this.sequence += 1;
   }
+  /**
+   * 创建当前周期的一次性计时回调；周期失效或该阶段已记录时忽略调用。
+   */
   measure(key, startedAt) {
     const sequence = this.sequence;
     return () => {
@@ -4015,34 +4634,52 @@ var RealtimeLaunchTimer = class {
       this.notify();
     };
   }
+  /**
+   * 分发不可变快照；隔离同步和异步观察者异常，避免影响媒体生命周期。
+   */
   notify() {
     try {
       void Promise.resolve(_optionalChain([this, 'access', _133 => _133.listener, 'optionalCall', _134 => _134(this.snapshot)])).catch(() => {
       });
-    } catch (e16) {
+    } catch (e15) {
     }
   }
 };
 
 // src/Core/Realtime/XmaxRealtimeConnectionManager.ts
 var XmaxRealtimeConnectionManager = class {
+  /**
+   * 注入会话、传输、计时和渲染回调依赖；连接资源在 connect 时创建。
+   */
   constructor(dependencies) {
     __publicField(this, "dependencies", dependencies);
+    /**
+     * 会话资源
+     */
     __publicField(this, "activeSession");
+    /**
+     * 远端轨道与渲染绑定
+     */
     __publicField(this, "activeRemoteTrack");
-    __publicField(this, "remoteBinding");
-    __publicField(this, "targetSize");
+    __publicField(this, "remoteTarget");
   }
+  /**
+   * 当前活动会话标识；尚未连接或清理完成后为空。
+   */
   get currentSessionID() {
     return _optionalChain([this, 'access', _135 => _135.activeSession, 'optionalAccess', _136 => _136.id]);
   }
-  get currentTargetSize() {
-    return this.targetSize;
-  }
-  /** 未配置 API 服务时在连接操作开始前报错，不影响本地预览。 */
+  /**
+   * 未配置 API 服务时在连接操作开始前报错，不影响本地预览。
+   */
   validateConfiguration() {
     this.requireSessionService();
   }
+  /**
+   * 创建会话、配置编码、进房并发布本地媒体，启动心跳后返回远端占位流。
+   * 进房结束即记录连接耗时；可选 beforePublish 检查只阻塞发布，不计入连接耗时。
+   * @throws 会话、进房、发布失败或操作租约已失效时抛出错误，由上层统一清理。
+   */
   async connect(options) {
     const sessionService = this.requireSessionService();
     const streamController = this.dependencies.streamController;
@@ -4069,9 +4706,12 @@ var XmaxRealtimeConnectionManager = class {
     options.ensureCurrent();
     await streamController.connect(connection, options.includeLocalAudio, () => {
       options.ensureCurrent();
-    }, options.beforePublish);
-    options.ensureCurrent();
-    completeConnection();
+    }, async () => {
+      options.ensureCurrent();
+      completeConnection();
+      options.ensureCurrent();
+      await _optionalChain([options, 'access', _137 => _137.beforePublish, 'optionalCall', _138 => _138()]);
+    });
     options.ensureCurrent();
     options.onPublished();
     sessionService.startHeartbeat(session.id, {
@@ -4091,19 +4731,30 @@ var XmaxRealtimeConnectionManager = class {
     streamController.setRemoteAudioVolume(this.dependencies.remoteAudioVolume());
     return new RealtimeMediaStream({ id: "stream1" /* remote */, videoTrack: remoteTrack });
   }
+  /**
+   * 更新已绑定远端视图的插帧配置；传 undefined 停用插帧。
+   */
   setFrameInterpolation(options) {
-    _optionalChain([this, 'access', _137 => _137.remoteBinding, 'optionalAccess', _138 => _138.setFrameInterpolation, 'call', _139 => _139(options)]);
+    _optionalChain([this, 'access', _139 => _139.remoteTarget, 'optionalAccess', _140 => _140.setFrameInterpolation, 'optionalCall', _141 => _141(options)]);
   }
+  /**
+   * 清空远端视图的媒体流，保留轨道与视图绑定以供统一清理。
+   */
   clearRemoteMedia() {
-    _optionalChain([this, 'access', _140 => _140.remoteBinding, 'optionalAccess', _141 => _141.setMediaStream, 'call', _142 => _142(null)]);
+    _optionalChain([this, 'access', _142 => _142.remoteTarget, 'optionalAccess', _143 => _143.setMediaStream, 'call', _144 => _144(null)]);
   }
+  /**
+   * 停止会话心跳；未配置会话服务时不执行操作。
+   */
   stopHeartbeat() {
-    _optionalChain([this, 'access', _143 => _143.dependencies, 'access', _144 => _144.sessionService, 'optionalAccess', _145 => _145.stopHeartbeat, 'call', _146 => _146()]);
+    _optionalChain([this, 'access', _145 => _145.dependencies, 'access', _146 => _146.sessionService, 'optionalAccess', _147 => _147.stopHeartbeat, 'call', _148 => _148()]);
   }
-  /** 等待接收轨解除静音；超时只警告，取消必须立即退出并移除监听。 */
+  /**
+   * 等待接收轨解除静音；超时只警告，取消必须立即退出并移除监听。
+   */
   async waitUntilRemoteTrackReady(timeoutMs, signal) {
     if (signal.aborted) throw RealtimeCoordinator.cancelledError();
-    const mediaTrack = _optionalChain([this, 'access', _147 => _147.activeRemoteTrack, 'optionalAccess', _148 => _148.mediaStreamTrack]);
+    const mediaTrack = _optionalChain([this, 'access', _149 => _149.activeRemoteTrack, 'optionalAccess', _150 => _150.mediaStreamTrack]);
     if (!mediaTrack || !mediaTrack.muted) return;
     await new Promise((resolve, reject) => {
       const cleanup = () => {
@@ -4140,7 +4791,7 @@ var XmaxRealtimeConnectionManager = class {
       if (track) {
         track.mediaStreamTrack = void 0;
       }
-      _optionalChain([this, 'access', _149 => _149.remoteBinding, 'optionalAccess', _150 => _150.setMediaStream, 'call', _151 => _151(null)]);
+      _optionalChain([this, 'access', _151 => _151.remoteTarget, 'optionalAccess', _152 => _152.setMediaStream, 'call', _153 => _153(null)]);
       return;
     }
     if (!track) {
@@ -4150,9 +4801,11 @@ var XmaxRealtimeConnectionManager = class {
       );
     }
     track.mediaStreamTrack = binding.videoTrack;
-    _optionalChain([this, 'access', _152 => _152.remoteBinding, 'optionalAccess', _153 => _153.setMediaStream, 'call', _154 => _154(new MediaStream([binding.videoTrack]))]);
+    _optionalChain([this, 'access', _154 => _154.remoteTarget, 'optionalAccess', _155 => _155.setMediaStream, 'call', _156 => _156(new MediaStream([binding.videoTrack]))]);
   }
-  /** 为远端轨道注册渲染绑定：attach 时挂流占位，媒体轨到达后送入画面。 */
+  /**
+   * 为远端轨道注册渲染绑定：attach 时挂流占位，媒体轨到达后送入画面。
+   */
   registerRemoteBinding(track) {
     VideoRenderRegistry.register(track, {
       frameDisplayHandler: () => {
@@ -4161,39 +4814,34 @@ var XmaxRealtimeConnectionManager = class {
         }
       },
       attachHandler: (view) => {
-        _optionalChain([this, 'access', _155 => _155.remoteBinding, 'optionalAccess', _156 => _156.setFrameInterpolation, 'call', _157 => _157(void 0)]);
+        _optionalChain([this, 'access', _157 => _157.remoteTarget, 'optionalAccess', _158 => _158.setFrameInterpolation, 'optionalCall', _159 => _159(void 0)]);
         view.isMirrored = this.dependencies.isMirrored();
-        this.remoteBinding = {
-          target: view,
-          setFrameInterpolation: (options) => _optionalChain([view, 'access', _158 => _158.setFrameInterpolation, 'optionalCall', _159 => _159(options)]),
-          setMediaStream: (stream) => {
-            view.setMediaStream(stream);
-          },
-          setMirrored: (mirrored) => {
-            view.isMirrored = mirrored;
-          }
-        };
+        this.remoteTarget = view;
         this.dependencies.onRenderAttached();
         const mediaTrack = track.mediaStreamTrack;
         view.setMediaStream(mediaTrack ? new MediaStream([mediaTrack]) : null);
       },
       detachHandler: (view) => {
-        if (_optionalChain([this, 'access', _160 => _160.remoteBinding, 'optionalAccess', _161 => _161.target]) === view) {
+        if (this.remoteTarget === view) {
           this.dependencies.onRenderDetached();
-          this.remoteBinding = void 0;
+          this.remoteTarget = void 0;
         }
-        _optionalChain([view, 'access', _162 => _162.setFrameInterpolation, 'optionalCall', _163 => _163(void 0)]);
+        _optionalChain([view, 'access', _160 => _160.setFrameInterpolation, 'optionalCall', _161 => _161(void 0)]);
         view.setMediaStream(null);
       }
     });
   }
-  /** 同步远端结果画面的镜像状态：与当前本地摄像头位置保持一致。 */
+  /**
+   * 同步远端结果画面的镜像状态：与当前本地摄像头位置保持一致。
+   */
   updateRemoteMirror() {
-    _optionalChain([this, 'access', _164 => _164.remoteBinding, 'optionalAccess', _165 => _165.setMirrored, 'call', _166 => _166(
-      this.dependencies.isMirrored()
-    )]);
+    if (this.remoteTarget) {
+      this.remoteTarget.isMirrored = this.dependencies.isMirrored();
+    }
   }
-  /** 构造当前远端生成结果媒体流。 */
+  /**
+   * 构造当前远端生成结果媒体流。
+   */
   makeRemoteStream() {
     const track = this.activeRemoteTrack;
     if (!track) {
@@ -4234,9 +4882,11 @@ var XmaxRealtimeConnectionManager = class {
       closeReason: session.closeReason
     });
   }
-  /** 尽力清理全部连接资源，即使退房失败也关闭服务端会话。 */
+  /**
+   * 尽力清理全部连接资源，即使退房失败也关闭服务端会话。
+   */
   async disconnect() {
-    const sessionID = _optionalChain([this, 'access', _167 => _167.activeSession, 'optionalAccess', _168 => _168.id]);
+    const sessionID = _optionalChain([this, 'access', _162 => _162.activeSession, 'optionalAccess', _163 => _163.id]);
     this.stopHeartbeat();
     this.clearRemoteMedia();
     try {
@@ -4252,8 +4902,7 @@ var XmaxRealtimeConnectionManager = class {
     }
     this.activeSession = void 0;
     this.activeRemoteTrack = void 0;
-    this.remoteBinding = void 0;
-    this.targetSize = void 0;
+    this.remoteTarget = void 0;
     if (sessionID && this.dependencies.sessionService) {
       try {
         await this.dependencies.sessionService.closeSession(sessionID);
@@ -4264,7 +4913,9 @@ var XmaxRealtimeConnectionManager = class {
     }
     return sessionID;
   }
-  /** 获取会话 Service；未配置 API 服务时抛出配置错误。 */
+  /**
+   * 获取会话 Service；未配置 API 服务时抛出配置错误。
+   */
   requireSessionService() {
     if (!this.dependencies.sessionService) {
       throw new XmaxError(
@@ -4278,14 +4929,25 @@ var XmaxRealtimeConnectionManager = class {
 
 // src/Core/Realtime/XmaxRealtimeGenerationManager.ts
 var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
+  /**
+   * 注入房间传输组件和任务标识生成器，不创建会话或启动生成。
+   */
   constructor(streamController, taskIDGenerator = _XmaxRealtimeGenerationManager.createTaskID) {
     __publicField(this, "streamController", streamController);
     __publicField(this, "taskIDGenerator", taskIDGenerator);
+    /**
+     * 当前生成条件与任务标识
+     */
     __publicField(this, "currentContext");
     __publicField(this, "activeTaskID");
+    /**
+     * 并发停止操作的共享结果
+     */
     __publicField(this, "pendingStop");
   }
-  /** 首次请求在建立连接前校验条件；后续请求可复用缓存。 */
+  /**
+   * 首次请求在建立连接前校验条件；后续请求可复用缓存。
+   */
   validateContext(context) {
     const resolved = _nullishCoalesce(context, () => ( this.currentContext));
     if (!resolved) {
@@ -4293,6 +4955,10 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
     }
     return resolved;
   }
+  /**
+   * 发送生成指令并等待确认、远端就绪和音频激活，成功后返回任务标识。
+   * 条件上下文在生成确认后缓存；启动失败时尽力停止本次任务并保留原始错误。
+   */
   async start(options) {
     const context = this.validateContext(options.context);
     options.ensureCurrent();
@@ -4302,7 +4968,6 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
       const confirmation = this.streamController.beginGeneration({
         taskID,
         videoFormat: options.videoFormat,
-        targetSize: options.targetSize,
         context
       });
       await this.awaitConfirmation(confirmation, options.signal);
@@ -4318,6 +4983,9 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
       throw error;
     }
   }
+  /**
+   * 更新活动任务的生成条件；信令发送成功后才覆盖缓存，无任务或上下文时抛错。
+   */
   update(taskID, options) {
     const context = _nullishCoalesce(options.context, () => ( this.currentContext));
     if (!taskID || !context) {
@@ -4326,11 +4994,13 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
     this.streamController.updateGeneration({
       taskID,
       videoFormat: options.videoFormat,
-      targetSize: options.targetSize,
       context
     });
     this.currentContext = context;
   }
+  /**
+   * 幂等停止指定活动任务；并发调用共享结果，停止失败仅记录日志。
+   */
   async stop(taskID = this.activeTaskID) {
     if (this.pendingStop && (!taskID || this.pendingStop.taskID === taskID)) {
       return this.pendingStop.completion;
@@ -4349,13 +5019,19 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
     try {
       await completion;
     } finally {
-      if (_optionalChain([this, 'access', _169 => _169.pendingStop, 'optionalAccess', _170 => _170.completion]) === completion) this.pendingStop = void 0;
+      if (_optionalChain([this, 'access', _164 => _164.pendingStop, 'optionalAccess', _165 => _165.completion]) === completion) this.pendingStop = void 0;
     }
   }
+  /**
+   * 清空缓存的生成条件并等待活动任务停止，供断连和关闭流程使用。
+   */
   async reset(taskID) {
     this.currentContext = void 0;
     await this.stop(_nullishCoalesce(this.activeTaskID, () => ( (taskID || void 0))));
   }
+  /**
+   * 等待生成确认；取消时立即拒绝，并在所有结束路径移除取消监听。
+   */
   async awaitConfirmation(confirmation, signal) {
     await new Promise((resolve, reject) => {
       const cleanup = () => signal.removeEventListener("abort", abort);
@@ -4377,7 +5053,9 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
       if (signal.aborted) abort();
     });
   }
-  /** 生成当前生成任务的唯一标识。 */
+  /**
+   * 生成当前生成任务的唯一标识。
+   */
   static createTaskID() {
     const hex = crypto.randomUUID().replace(/-/g, "");
     let binary = "";
@@ -4400,19 +5078,32 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 相机控制器与传输层共享同一个 RTC 引擎。
    */
   constructor(options, dependencies) {
-    // 业务配置
+    /**
+     * 业务配置
+     */
     __publicField(this, "options");
     __publicField(this, "mediaService");
+    /**
+     * 插帧能力、用户配置与渲染版本
+     */
     __publicField(this, "supportsInterpolation");
     __publicField(this, "interpolationRequested");
     __publicField(this, "interpolationSize");
     __publicField(this, "interpolationRevision", 0);
-    // 业务组件
+    /**
+     * 业务组件
+     */
     __publicField(this, "coordinator");
     __publicField(this, "errorHandler");
     __publicField(this, "cameraController");
+    /**
+     * 启动计时与首帧通知
+     */
     __publicField(this, "launchTimer", new RealtimeLaunchTimer());
     __publicField(this, "remoteFrameDisplayHandler");
+    /**
+     * 本地、远端和网络统计快照及观察者
+     */
     __publicField(this, "localVideoStatistics");
     __publicField(this, "localVideoStatisticsListener");
     __publicField(this, "remoteVideoStatistics");
@@ -4420,28 +5111,32 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     __publicField(this, "acceptsVideoStatistics", false);
     __publicField(this, "networkStatistics");
     __publicField(this, "networkStatisticsListener");
-    // 实时业务管理组件；状态所有权分别归连接和生成管理器。
+    /**
+     * 实时业务管理组件；状态所有权分别归连接和生成管理器。
+     */
     __publicField(this, "connectionManager");
     __publicField(this, "generationManager");
     __publicField(this, "streamController");
-    // 音量配置
+    /**
+     * 音量配置
+     */
     __publicField(this, "storedLocalAudioVolume", 1);
     __publicField(this, "storedRemoteAudioVolume", 0);
     this.options = options;
     this.mediaService = new MediaService(options.model);
     this.interpolationRequested = options.isFrameInterpolationEnabled;
-    this.supportsInterpolation = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _171 => _171.supportsFrameInterpolation]), () => ( (async (size) => await frameInterpolationAdapter(size) !== null)));
+    this.supportsInterpolation = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _166 => _166.supportsFrameInterpolation]), () => ( (async (size) => await frameInterpolationAdapter(size) !== null)));
     this.errorHandler = new RealtimeErrorHandler();
-    const rtcManager = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _172 => _172.rtcManager]), () => ( new RtcManager()));
-    this.cameraController = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _173 => _173.cameraController]), () => ( new CameraController({
+    const rtcManager = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _167 => _167.rtcManager]), () => ( new RtcManager()));
+    this.cameraController = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _168 => _168.cameraController]), () => ( new CameraController({
       rtcManager,
-      mediaService: new MediaService(options.model),
+      mediaService: this.mediaService,
       errorListener: (error) => {
         void this.errorHandler.report(error);
       }
     })));
-    const sessionService = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _174 => _174.sessionService]), () => ( (_optionalChain([dependencies, 'optionalAccess', _175 => _175.apiService]) ? new RealtimeSessionService({ apiService: dependencies.apiService }) : void 0)));
-    this.streamController = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _176 => _176.streamController]), () => ( new StreamController({
+    const sessionService = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _169 => _169.sessionService]), () => ( (_optionalChain([dependencies, 'optionalAccess', _170 => _170.apiService]) ? new RealtimeSessionService({ apiService: dependencies.apiService }) : void 0)));
+    this.streamController = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _171 => _171.streamController]), () => ( new StreamController({
       rtcManager,
       errorListener: (error) => {
         void this.errorHandler.report(error);
@@ -4455,12 +5150,12 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       sessionService,
       streamController: this.streamController,
       timing: this.launchTimer,
-      isMirrored: () => _optionalChain([this, 'access', _177 => _177.cameraController, 'access', _178 => _178.currentTrack, 'optionalAccess', _179 => _179.position]) === "front" /* front */,
+      isMirrored: () => _optionalChain([this, 'access', _172 => _172.cameraController, 'access', _173 => _173.currentTrack, 'optionalAccess', _174 => _174.position]) === "front" /* front */,
       remoteAudioVolume: () => this.storedRemoteAudioVolume,
       onHeartbeatFailure: (sessionID, error) => {
         void this.handleHeartbeatFailure(sessionID, error);
       },
-      onFrameDisplayed: () => _optionalChain([this, 'access', _180 => _180.remoteFrameDisplayHandler, 'optionalCall', _181 => _181()]),
+      onFrameDisplayed: () => _optionalChain([this, 'access', _175 => _175.remoteFrameDisplayHandler, 'optionalCall', _176 => _176()]),
       onRenderAttached: () => this.applyRemoteInterpolation(),
       onRenderDetached: () => {
         this.interpolationRevision++;
@@ -4490,16 +5185,24 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       }
     });
   }
-  /** 当前实时连接与生成状态。 */
+  /**
+   * 当前实时连接与生成状态。
+   */
   get currentState() {
     return this.coordinator.currentState;
   }
+  /**
+   * 当前是否请求启用插帧；能力探测或运行期降级后可能为 false。
+   */
   get isFrameInterpolationEnabled() {
     return this.interpolationRequested;
   }
+  /**
+   * 串行更新插帧开关；开启前验证能力，不支持时抛错并保留原配置，不改变回传尺寸。
+   */
   async setFrameInterpolationEnabled(enabled) {
     await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
-      const format = _optionalChain([this, 'access', _182 => _182.cameraController, 'access', _183 => _183.currentTrack, 'optionalAccess', _184 => _184.videoFormat]);
+      const format = _optionalChain([this, 'access', _177 => _177.cameraController, 'access', _178 => _178.currentTrack, 'optionalAccess', _179 => _179.videoFormat]);
       const size = format && enabled ? this.mediaService.resolveFrameInterpolationSize(format) : void 0;
       if (enabled && !await this.checkInterpolationSupport(size, token)) {
         token.ensureCurrent();
@@ -4511,6 +5214,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       this.applyRemoteInterpolation();
     });
   }
+  /**
+   * 根据当前视频尺寸准备插帧，能力不可用时降级为原视频，并在应用前校验租约。
+   */
   async prepareFrameInterpolation(format, token) {
     let size;
     if (this.interpolationRequested) {
@@ -4527,6 +5233,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     this.interpolationSize = size;
     this.applyRemoteInterpolation();
   }
+  /**
+   * 在 5 秒预算内探测插帧能力；超时或探测失败返回 false，主动取消则拒绝。
+   */
   checkInterpolationSupport(size, token) {
     return new Promise((resolve, reject) => {
       const finish = (supported) => {
@@ -4550,6 +5259,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       void this.supportsInterpolation(size).then(finish, () => finish(false));
     });
   }
+  /**
+   * 将当前插帧配置同步到远端绑定，并用版本号忽略旧管线的迟到失败。
+   */
   applyRemoteInterpolation() {
     const revision = ++this.interpolationRevision;
     const size = this.interpolationSize;
@@ -4561,6 +5273,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       }
     } : void 0);
   }
+  /**
+   * 关闭已失败的插帧配置并记录降级原因，保持原始视频渲染可用。
+   */
   handleInterpolationFailure(error) {
     this.interpolationRequested = false;
     this.interpolationSize = void 0;
@@ -4568,11 +5283,15 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     XmaxLogger.render.warning(() => `\u63D2\u5E27\u5DF2\u964D\u7EA7 (Frame Interpolation Disabled)
 \u2514\u2500 ${XmaxError.from(error).message}`);
   }
-  /** 当前本地媒体预览音量，取值范围为 `0...1`。 */
+  /**
+   * 当前本地媒体预览音量，取值范围为 `0...1`。
+   */
   get localAudioVolume() {
     return this.storedLocalAudioVolume;
   }
-  /** 当前远端生成音频播放音量，取值范围为 `0...1`。 */
+  /**
+   * 当前远端生成音频播放音量，取值范围为 `0...1`。
+   */
   get remoteAudioVolume() {
     return this.storedRemoteAudioVolume;
   }
@@ -4584,39 +5303,56 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
   async setStateListener(listener) {
     await this.coordinator.setStateListener(listener);
   }
-  /** 监听启动耗时；设置后立即回放，传 undefined 取消监听。 */
+  /**
+   * 监听启动耗时；设置后立即回放，传 undefined 取消监听。
+   */
   async setLaunchTimingListener(listener) {
     this.launchTimer.setListener(listener);
   }
-  /** 监听本地主视频流的实际运行统计；立即回放最新快照。 */
+  /**
+   * 监听本地主视频流的实际运行统计；立即回放最新快照。
+   */
   async setLocalVideoStatisticsListener(listener) {
     this.localVideoStatisticsListener = listener;
     this.notifyLocalVideoStatistics();
   }
-  /** 监听当前生成结果流的实际运行统计；立即回放最新快照。 */
+  /**
+   * 监听当前生成结果流的实际运行统计；立即回放最新快照。
+   */
   async setRemoteVideoStatisticsListener(listener) {
     this.remoteVideoStatisticsListener = listener;
     this.notifyRemoteVideoStatistics();
   }
+  /**
+   * 回放当前远端视频统计，隔离观察者的同步和异步异常。
+   */
   notifyRemoteVideoStatistics() {
     try {
-      void Promise.resolve(_optionalChain([this, 'access', _185 => _185.remoteVideoStatisticsListener, 'optionalCall', _186 => _186(this.remoteVideoStatistics)])).catch(() => {
+      void Promise.resolve(_optionalChain([this, 'access', _180 => _180.remoteVideoStatisticsListener, 'optionalCall', _181 => _181(this.remoteVideoStatistics)])).catch(() => {
       });
-    } catch (e17) {
+    } catch (e16) {
     }
   }
-  /** 网络统计立即回放最新快照，无数据或断开后为 undefined。 */
+  /**
+   * 网络统计立即回放最新快照，无数据或断开后为 undefined。
+   */
   async setNetworkStatisticsListener(listener) {
     this.networkStatisticsListener = listener;
     this.notifyNetworkStatistics();
   }
+  /**
+   * 回放当前网络统计，隔离观察者的同步和异步异常。
+   */
   notifyNetworkStatistics() {
     try {
-      void Promise.resolve(_optionalChain([this, 'access', _187 => _187.networkStatisticsListener, 'optionalCall', _188 => _188(this.networkStatistics)])).catch(() => {
+      void Promise.resolve(_optionalChain([this, 'access', _182 => _182.networkStatisticsListener, 'optionalCall', _183 => _183(this.networkStatistics)])).catch(() => {
       });
-    } catch (e18) {
+    } catch (e17) {
     }
   }
+  /**
+   * 清除远端视频统计；原先存在数据时通知观察者数据已失效。
+   */
   clearRemoteVideoStatistics() {
     const hadStatistics = this.remoteVideoStatistics !== void 0;
     this.remoteVideoStatistics = void 0;
@@ -4624,13 +5360,19 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       this.notifyRemoteVideoStatistics();
     }
   }
+  /**
+   * 回放当前本地视频统计，隔离观察者的同步和异步异常。
+   */
   notifyLocalVideoStatistics() {
     try {
-      void Promise.resolve(_optionalChain([this, 'access', _189 => _189.localVideoStatisticsListener, 'optionalCall', _190 => _190(this.localVideoStatistics)])).catch(() => {
+      void Promise.resolve(_optionalChain([this, 'access', _184 => _184.localVideoStatisticsListener, 'optionalCall', _185 => _185(this.localVideoStatistics)])).catch(() => {
       });
-    } catch (e19) {
+    } catch (e18) {
     }
   }
+  /**
+   * 停止接收媒体统计并清空各类快照，仅对曾有数据的统计发出清空通知。
+   */
   clearVideoStatistics() {
     this.acceptsVideoStatistics = false;
     const hadNetworkStatistics = this.networkStatistics !== void 0;
@@ -4677,6 +5419,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    *
    * 将返回的轨道绑定到预览视图；收到有效帧且视图已绑定后进入 `ready`。
    *
+   * @param options.enableFrameValidation 是否在发布前检测帧亮度，默认 true；false 跳过检测及其等待。
    * @returns 包含本地相机视频轨道的媒体流。
    * @throws 模型不支持相机输入、配置无效、权限或采集启动失败时抛出错误。
    */
@@ -4711,7 +5454,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       }
     );
   }
-  /** 停止本地相机流并释放本地预览与 RTC 资源。 */
+  /**
+   * 停止本地相机流并释放本地预览与 RTC 资源。
+   */
   async stopLocalCameraStream() {
     await this.coordinator.run(
       "media" /* media */,
@@ -4752,8 +5497,8 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 使用当前 Manager 创建的本地流建立实时连接。
    *
    * 创建实时会话、加入 RTC 房间并发布本地流，成功后启动会话心跳。
-   * 发布前并行检查相机亮度稳定性；5 秒内未通过检查时抛出
-   * `cameraExposureTimeout`，不发布媒体，接入方可改善光照后重试。
+   * 启用帧检测时，发布前并行检查相机亮度，首张合格帧即放行；2 秒内未通过检查则
+   * 记录警告并按当前画面继续发布，不因环境较暗而阻断连接。
    * 返回的远端媒体流在生成开始后承载远端生成画面。
    *
    * @param localStream 由 `createLocalCameraStream` 创建的本地媒体流。
@@ -4812,7 +5557,6 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         if (currentState.connectionState === "Generating" /* generating */) {
           this.generationManager.update(currentState.taskID, {
             videoFormat,
-            targetSize: this.connectionManager.currentTargetSize,
             context: options.context
           });
           return this.connectionManager.makeRemoteStream();
@@ -4825,7 +5569,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       }
     );
   }
-  /** 断开实时连接并保留当前本地媒体预览。 */
+  /**
+   * 断开实时连接并保留当前本地媒体预览。
+   */
   async disconnect() {
     this.launchTimer.cancel();
     this.clearVideoStatistics();
@@ -4866,9 +5612,17 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     token.signal.addEventListener("abort", abortExposure, { once: true });
     if (token.signal.aborted) abortExposure();
     try {
-      const cameraReady = this.cameraController.waitUntilExposureReady(exposureController.signal);
-      void cameraReady.catch(() => {
-      });
+      let beforePublish;
+      if (this.cameraController.isFrameValidationEnabled) {
+        const completeFrameValidation = this.launchTimer.startFrameValidation();
+        const cameraReady = this.cameraController.waitForValidCameraFrame(exposureController.signal).then(() => {
+          token.ensureCurrent();
+          completeFrameValidation();
+        });
+        void cameraReady.catch(() => {
+        });
+        beforePublish = () => cameraReady;
+      }
       const remote = await this.connectionManager.connect({
         localTrack,
         model: this.options.model,
@@ -4877,7 +5631,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         onPublished: () => {
           this.acceptsVideoStatistics = true;
         },
-        beforePublish: () => cameraReady
+        beforePublish
       });
       await this.coordinator.commit(
         new RealtimeState({
@@ -4892,7 +5646,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       abortExposure();
     }
   }
-  /** 编排插帧、首帧计时和生成状态，任务与确认由生成管理器负责。 */
+  /**
+   * 编排插帧、首帧计时和生成状态，任务与确认由生成管理器负责。
+   */
   async performStartGeneration(token, videoFormat, context) {
     token.setFailureScope(0 /* connection */);
     await this.prepareFrameInterpolation(videoFormat, token);
@@ -4902,7 +5658,6 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     };
     const taskID = await this.generationManager.start({
       videoFormat,
-      targetSize: this.connectionManager.currentTargetSize,
       context,
       signal: token.signal,
       ensureCurrent: () => token.ensureCurrent(),
@@ -4921,7 +5676,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     );
     return this.connectionManager.makeRemoteStream();
   }
-  /** 心跳失败或会话失效：结束当前连接生命周期并通过最终状态给出原因。 */
+  /**
+   * 心跳失败或会话失效：结束当前连接生命周期并通过最终状态给出原因。
+   */
   async handleHeartbeatFailure(sessionID, error) {
     await this.coordinator.terminateWithError(
       error,
@@ -4929,7 +5686,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       () => this.connectionManager.currentSessionID === sessionID
     );
   }
-  /** 统一清理顺序：停止心跳与生成，再断开连接；all 额外释放本地媒体。 */
+  /**
+   * 统一清理顺序：停止心跳与生成，再断开连接；all 额外释放本地媒体。
+   */
   async performCleanup(scope, taskID) {
     this.launchTimer.cancel();
     this.remoteFrameDisplayHandler = void 0;
@@ -4955,7 +5714,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       hasLocalMedia: this.cameraController.currentTrack !== void 0
     };
   }
-  /** 校验音量取值范围为 `0...1`。 */
+  /**
+   * 校验音量取值范围为 `0...1`。
+   */
   static validateVolume(volume) {
     if (!Number.isFinite(volume) || volume < 0 || volume > 1) {
       throw new XmaxError(
@@ -4976,11 +5737,23 @@ var XmaxConfiguration = class {
    * @param init.loggerOptions SDK 输出的日志类型；默认为空。
    */
   constructor(init) {
-    /** 调用 Xmax 服务使用的 API Key。 */
+    /**
+     * 服务身份与环境
+     */
+    /**
+     * 调用 Xmax 服务使用的 API Key。
+     */
     __publicField(this, "apiKey");
-    /** SDK 连接的服务环境，同时决定日志细项语言：国内为中文，海外为英文。 */
+    /**
+     * SDK 连接的服务环境，同时决定日志细项语言：国内为中文，海外为英文。
+     */
     __publicField(this, "environment");
-    /** SDK 输出的日志类型；默认为不输出日志。 */
+    /**
+     * 日志配置
+     */
+    /**
+     * SDK 输出的日志类型；默认为不输出日志。
+     */
     __publicField(this, "loggerOptions");
     this.apiKey = init.apiKey.trim();
     this.environment = _nullishCoalesce(init.environment, () => ( "china")) /* china */;
@@ -5009,9 +5782,16 @@ var XmaxClient = class {
    * 在实际调用时校验 API Key。
    */
   constructor(configuration) {
-    /** 客户端使用的全局配置。 */
+    /**
+     * 客户端配置
+     */
+    /**
+     * 客户端使用的全局配置。
+     */
     __publicField(this, "configuration");
-    // 服务层组件
+    /**
+     * 服务层组件
+     */
     __publicField(this, "apiService");
     this.configuration = configuration;
     XmaxLogger.configure(
@@ -5057,19 +5837,33 @@ var RealtimeConfiguration = class {
    *
    * @param init.model 实时生成业务使用的模型。
    * @param init.isFrameInterpolationEnabled 是否默认开启远端生成画面的插帧。
+   * @param init.frameInterpolation 插帧开关和显示帧率上限的详细配置。
    */
   constructor(init) {
-    /** 实时生成业务使用的模型。 */
+    /**
+     * 模型配置
+     */
+    /**
+     * 实时生成业务使用的模型。
+     */
     __publicField(this, "model");
-    /** 是否默认请求开启远端生成画面的插帧。 */
+    /**
+     * 远端插帧配置
+     */
+    /**
+     * 是否默认请求开启远端生成画面的插帧。
+     */
     __publicField(this, "isFrameInterpolationEnabled");
+    /**
+     * 已补全默认值的只读插帧配置。
+     */
     __publicField(this, "frameInterpolation");
     this.model = init.model;
-    const targetFrameRate = _nullishCoalesce(_optionalChain([init, 'access', _191 => _191.frameInterpolation, 'optionalAccess', _192 => _192.targetFrameRate]), () => ( 60));
+    const targetFrameRate = _nullishCoalesce(_optionalChain([init, 'access', _186 => _186.frameInterpolation, 'optionalAccess', _187 => _187.targetFrameRate]), () => ( 60));
     if (!Number.isFinite(targetFrameRate) || targetFrameRate < 1 || targetFrameRate > 60) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Interpolation targetFrameRate must be between 1 and 60");
     }
-    this.isFrameInterpolationEnabled = _nullishCoalesce(_nullishCoalesce(_optionalChain([init, 'access', _193 => _193.frameInterpolation, 'optionalAccess', _194 => _194.enabled]), () => ( init.isFrameInterpolationEnabled)), () => ( true));
+    this.isFrameInterpolationEnabled = _nullishCoalesce(_nullishCoalesce(_optionalChain([init, 'access', _188 => _188.frameInterpolation, 'optionalAccess', _189 => _189.enabled]), () => ( init.isFrameInterpolationEnabled)), () => ( false));
     this.frameInterpolation = Object.freeze({ enabled: this.isFrameInterpolationEnabled, targetFrameRate });
   }
 };
@@ -5083,15 +5877,24 @@ var VideoContentMode = /* @__PURE__ */ ((VideoContentMode2) => {
 
 // src/Service/Realtime/RealtimeContext.ts
 var RealtimeContext = class {
-  /** 创建实时生成条件并规范化文本和参考路径。 */
+  /**
+   * 创建实时生成条件并规范化文本和参考路径。
+   */
   constructor(init) {
-    /** 实时生成使用的文本条件。 */
+    /**
+     * 生成条件
+     */
+    /**
+     * 实时生成使用的文本条件。
+     */
     __publicField(this, "prompt");
-    /** 已上传参考图片的可选远端路径。 */
+    /**
+     * 已上传参考图片的可选远端路径。
+     */
     __publicField(this, "referencePath");
     this.prompt = init.prompt.trim();
-    const normalizedReferencePath = _optionalChain([init, 'access', _195 => _195.referencePath, 'optionalAccess', _196 => _196.trim, 'call', _197 => _197()]);
-    this.referencePath = normalizedReferencePath && normalizedReferencePath.length > 0 ? normalizedReferencePath : void 0;
+    const normalizedReferencePath = _optionalChain([init, 'access', _190 => _190.referencePath, 'optionalAccess', _191 => _191.trim, 'call', _192 => _192()]);
+    this.referencePath = normalizedReferencePath || void 0;
   }
 };
 
@@ -7067,7 +7870,7 @@ struct Output { @builtin(position) position: vec4f, @location(0) uv: vec2f }
   out.uv = vec2f((pos[i].x + 1) * 0.5, (1 - pos[i].y) * 0.5);
   return out;
 }`;
-var FrameInterpolationManager = class _FrameInterpolationManager {
+var _FrameInterpolationManager = class _FrameInterpolationManager {
   constructor(device, canvas, size, onFailure) {
     __publicField(this, "device", device);
     __publicField(this, "canvas", canvas);
@@ -7075,7 +7878,7 @@ var FrameInterpolationManager = class _FrameInterpolationManager {
     __publicField(this, "onFailure", onFailure);
     __publicField(this, "runtime");
     __publicField(this, "textures", []);
-    __publicField(this, "current", 0);
+    __publicField(this, "nextOriginal", 0);
     __publicField(this, "capturePipeline");
     __publicField(this, "displayPipeline");
     __publicField(this, "sampler");
@@ -7140,7 +7943,7 @@ var FrameInterpolationManager = class _FrameInterpolationManager {
         throw new Error("Interpolation initialization cancelled");
       }
       this.runtime = runtime;
-      for (let i = 0; i < 3; i++) {
+      for (let i = 0; i < _FrameInterpolationManager.originalSlots + 1; i++) {
         this.textures.push(device.createTexture({
           size: [w, h],
           format: "rgba8unorm",
@@ -7183,21 +7986,21 @@ var FrameInterpolationManager = class _FrameInterpolationManager {
     }
   }
   capture(video) {
-    this.current = 1 - this.current;
-    this.draw(this.capturePipeline, this.device.importExternalTexture({ source: video }), this.textures[this.current].createView());
-  }
-  presentPrevious() {
-    this.present(this.textures[1 - this.current]);
-  }
-  async interpolate() {
-    this.runtime.prepPair(this.textures[1 - this.current], this.textures[this.current]);
-    this.runtime.runT(0.5, this.textures[2]);
+    const slot = this.nextOriginal;
+    this.nextOriginal = (this.nextOriginal + 1) % _FrameInterpolationManager.originalSlots;
+    this.draw(this.capturePipeline, this.device.importExternalTexture({ source: video }), this.textures[slot].createView());
+    return slot;
+  }
+  async interpolate(previous, current) {
+    this.runtime.prepPair(this.textures[previous], this.textures[current]);
+    this.runtime.runT(0.5, this.textures[_FrameInterpolationManager.originalSlots]);
     await this.device.queue.onSubmittedWorkDone();
+    return _FrameInterpolationManager.originalSlots;
   }
-  presentInterpolated() {
-    this.present(this.textures[2]);
+  present(slot) {
+    this.presentTexture(this.textures[slot]);
   }
-  present(texture) {
+  presentTexture(texture) {
     this.draw(this.displayPipeline, texture.createView(), this.context.getCurrentTexture().createView());
   }
   draw(pipeline, source, target) {
@@ -7217,14 +8020,17 @@ var FrameInterpolationManager = class _FrameInterpolationManager {
     if (this.destroyed) return;
     this.destroyed = true;
     this.device.removeEventListener("uncapturederror", this.onGPUError);
-    _optionalChain([this, 'access', _198 => _198.runtime, 'optionalAccess', _199 => _199.destroy, 'call', _200 => _200()]);
+    _optionalChain([this, 'access', _193 => _193.runtime, 'optionalAccess', _194 => _194.destroy, 'call', _195 => _195()]);
     this.runtime = void 0;
     this.textures.forEach((texture) => texture.destroy());
     this.textures = [];
-    _optionalChain([this, 'access', _201 => _201.context, 'optionalAccess', _202 => _202.unconfigure, 'call', _203 => _203()]);
+    _optionalChain([this, 'access', _196 => _196.context, 'optionalAccess', _197 => _197.unconfigure, 'call', _198 => _198()]);
     this.device.destroy();
   }
 };
+/** 原帧环形缓冲的槽位数；插值结果固定在最后一个槽位。 */
+__publicField(_FrameInterpolationManager, "originalSlots", 3);
+var FrameInterpolationManager = _FrameInterpolationManager;
 
 // src/Render/Video/RemoteVideoFramePipeline.ts
 var RemoteVideoFramePipeline = class {
@@ -7236,18 +8042,35 @@ var RemoteVideoFramePipeline = class {
     __publicField(this, "processor");
     __publicField(this, "abort", new AbortController());
     __publicField(this, "callback");
-    __publicField(this, "midpointTimer");
+    __publicField(this, "raf");
     __publicField(this, "stallTimer");
     __publicField(this, "initializationTimer");
-    __publicField(this, "animation");
     __publicField(this, "loading", false);
     __publicField(this, "busy", false);
     __publicField(this, "stopped", false);
-    __publicField(this, "pair", 0);
+    __publicField(this, "generation", 0);
+    /** 播放时钟锚点：最近一次输入帧的媒体时间与对应的 vsync 时刻。 */
+    __publicField(this, "anchor");
+    /** 输出延迟，取最近一次有效源帧间隔，为中间帧留出计算窗口。 */
+    __publicField(this, "delay", 0);
+    __publicField(this, "queue", []);
+    __publicField(this, "displayedTime");
     __publicField(this, "previousTime");
+    __publicField(this, "previousSlot");
     __publicField(this, "previousPresented");
     __publicField(this, "slowPairs", 0);
     __publicField(this, "active", false);
+    /** vsync 显示节拍：弹出到点的帧并显示最新的一张。 */
+    __publicField(this, "tick", (now) => {
+      if (this.stopped) return;
+      this.raf = requestAnimationFrame(this.tick);
+      const position = this.position(now);
+      let frame;
+      while (this.queue.length > 0 && this.queue[0].time <= position) {
+        frame = this.queue.shift();
+      }
+      if (frame) this.present(frame);
+    });
   }
   start() {
     if (this.stopped || this.callback !== void 0) return;
@@ -7259,78 +8082,101 @@ var RemoteVideoFramePipeline = class {
   }
   observe() {
     if (this.stopped) return;
-    this.callback = this.video.requestVideoFrameCallback((_now, metadata) => {
+    this.callback = this.video.requestVideoFrameCallback((now, metadata) => {
       this.callback = void 0;
       if (this.stopped) return;
       try {
-        this.frame(metadata);
+        this.frame(now, metadata);
       } catch (error) {
         this.fail(error);
       }
       this.observe();
     });
   }
-  frame(metadata) {
+  frame(now, metadata) {
     if (typeof document !== "undefined" && document.hidden) {
-      this.resetPair();
+      this.resetTimeline();
       return;
     }
     if (metadata.width !== this.options.size.width || metadata.height !== this.options.size.height) {
-      this.resetPair();
+      this.resetTimeline();
       return;
     }
     if (!this.processor) {
       if (!this.loading) void this.initialize();
       return;
     }
-    if (this.busy) return;
-    const interval = this.previousTime === void 0 ? 0 : (metadata.mediaTime - this.previousTime) * 1e3;
+    const time = metadata.mediaTime * 1e3;
+    if (!Number.isFinite(time) || this.previousTime !== void 0 && time <= this.previousTime) return;
+    const previous = this.previousTime;
+    const interval = previous === void 0 ? 0 : time - previous;
     const consecutive = this.previousPresented === void 0 || metadata.presentedFrames === this.previousPresented + 1;
-    this.clearPresentation();
-    const pair = ++this.pair;
-    this.processor.capture(this.video);
-    this.previousTime = metadata.mediaTime;
+    const previousSlot = this.previousSlot;
+    this.anchor = { media: time, at: now };
+    this.previousTime = time;
     this.previousPresented = metadata.presentedFrames;
-    if (!consecutive || interval <= 0 || interval > 250 || interval < 2e3 / this.options.targetFrameRate - 1) {
-      this.setActive(false);
-      this.canvas.style.visibility = "hidden";
+    const slot = this.processor.capture(this.video);
+    this.previousSlot = slot;
+    if (previous === void 0 || interval > 250) {
+      this.queue = [];
+      this.delay = 0;
+      this.present({ slot, time });
+      this.startTick();
       return;
     }
+    this.delay = interval;
+    this.enqueue({ slot, time });
+    this.startTick();
+    if (!consecutive || interval < 2e3 / this.options.targetFrameRate - 1 || previousSlot === void 0 || this.busy) return;
+    this.interpolate(previousSlot, slot, previous, time, interval);
+  }
+  /** 帧按显示时间升序入队；同一时间的内容后到先出。 */
+  enqueue(frame) {
+    const index = this.queue.findIndex((queued) => queued.time >= frame.time);
+    if (index < 0) this.queue.push(frame);
+    else this.queue.splice(index, 0, frame);
+  }
+  interpolate(previousSlot, currentSlot, previousTime, currentTime, interval) {
+    const generation = this.generation;
+    const midpoint = (previousTime + currentTime) / 2;
     const startedAt = performance.now();
-    this.processor.presentPrevious();
-    this.canvas.style.visibility = "visible";
     this.busy = true;
     this.stallTimer = setTimeout(() => {
       if (this.busy) this.fail(new Error("Interpolation GPU submission timed out"));
-      else this.resetPair();
     }, Math.max(100, interval * 3));
-    void this.processor.interpolate().then(() => {
+    void this.processor.interpolate(previousSlot, currentSlot).then((slot) => {
       if (this.stopped) return;
       this.busy = false;
-      if (pair !== this.pair) return;
+      clearTimeout(this.stallTimer);
+      this.stallTimer = void 0;
+      if (generation !== this.generation) return;
       const elapsed = performance.now() - startedAt;
       this.slowPairs = elapsed > interval / 2 ? this.slowPairs + 1 : 0;
       if (this.slowPairs >= 5) {
         this.fail(new Error("Interpolation exceeded the GPU frame budget for 5 consecutive pairs"));
         return;
       }
-      if (elapsed >= interval) return;
-      this.midpointTimer = setTimeout(() => {
-        this.animation = requestAnimationFrame(() => {
-          this.animation = void 0;
-          if (this.stopped || pair !== this.pair || performance.now() - startedAt >= interval) return;
-          try {
-            this.processor.presentInterpolated();
-            this.setActive(true);
-          } catch (error) {
-            this.fail(error);
-          }
-        });
-      }, Math.max(0, interval / 2 - elapsed));
+      if (this.position(performance.now()) >= midpoint) return;
+      this.enqueue({ slot, time: midpoint });
     }).catch((error) => {
       if (!this.stopped) this.fail(error);
     });
   }
+  /** 显示时钟位置：锚点媒体时间随墙钟推进，整体后移一个源帧间隔。 */
+  position(now) {
+    if (!this.anchor) return -Infinity;
+    return this.anchor.media + (now - this.anchor.at) - this.delay;
+  }
+  startTick() {
+    if (this.raf === void 0) this.raf = requestAnimationFrame(this.tick);
+  }
+  present(frame) {
+    if (this.displayedTime === frame.time) return;
+    this.processor.present(frame.slot);
+    this.displayedTime = frame.time;
+    this.canvas.style.visibility = "visible";
+    this.setActive(true);
+  }
   async initialize() {
     this.loading = true;
     this.initializationTimer = setTimeout(() => this.fail(new Error("Interpolation initialization timed out")), 15e3);
@@ -7357,18 +8203,20 @@ var RemoteVideoFramePipeline = class {
   setActive(active) {
     if (active === this.active) return;
     this.active = active;
-    _optionalChain([this, 'access', _204 => _204.options, 'access', _205 => _205.onActiveChange, 'optionalCall', _206 => _206(active)]);
+    _optionalChain([this, 'access', _199 => _199.options, 'access', _200 => _200.onActiveChange, 'optionalCall', _201 => _201(active)]);
   }
-  clearPresentation() {
-    clearTimeout(this.midpointTimer);
+  resetTimeline() {
+    this.generation++;
+    this.queue = [];
     clearTimeout(this.stallTimer);
-    if (this.animation !== void 0) cancelAnimationFrame(this.animation);
-    this.animation = void 0;
-  }
-  resetPair() {
-    this.pair++;
-    this.clearPresentation();
+    this.stallTimer = void 0;
+    if (this.raf !== void 0) cancelAnimationFrame(this.raf);
+    this.raf = void 0;
+    this.anchor = void 0;
+    this.delay = 0;
+    this.displayedTime = void 0;
     this.previousTime = void 0;
+    this.previousSlot = void 0;
     this.previousPresented = void 0;
     this.canvas.style.visibility = "hidden";
     this.setActive(false);
@@ -7385,8 +8233,8 @@ var RemoteVideoFramePipeline = class {
     if (this.callback !== void 0) this.video.cancelVideoFrameCallback(this.callback);
     this.callback = void 0;
     clearTimeout(this.initializationTimer);
-    this.resetPair();
-    _optionalChain([this, 'access', _207 => _207.processor, 'optionalAccess', _208 => _208.destroy, 'call', _209 => _209()]);
+    this.resetTimeline();
+    _optionalChain([this, 'access', _202 => _202.processor, 'optionalAccess', _203 => _203.destroy, 'call', _204 => _204()]);
     this.processor = void 0;
   }
 };
@@ -7403,27 +8251,48 @@ var XmaxVideoView = class {
    * @param options.videoContentMode 视频内容显示模式，默认 fill。
    */
   constructor(options) {
-    // 视图元素
-    /** 视图根元素（div，内含一个 video 元素）。 */
+    /**
+     * 视图元素
+     */
+    /**
+     * 视图根元素（div，内含一个 video 元素）。
+     */
     __publicField(this, "element");
-    /** @internal 渲染视频帧的元素，供绑定管线使用。 */
+    /**
+     * @internal 渲染视频帧的元素，供绑定管线使用。
+     */
     __publicField(this, "videoElement");
-    // 公共配置
-    /** 首帧实际提交显示时调用（一次性；换轨后重新武装）。 */
+    /**
+     * 公共配置
+     */
+    /**
+     * 首帧实际提交显示时调用（一次性；换轨后重新武装）。
+     */
     __publicField(this, "frameDisplayHandler");
-    // 渲染状态
+    /**
+     * 渲染状态
+     */
     __publicField(this, "currentTrack");
     __publicField(this, "contentMode");
     __publicField(this, "mirrored", false);
+    /**
+     * 首帧显示通知与异步回调版本
+     */
     __publicField(this, "hasNotifiedFrameDisplay", false);
     __publicField(this, "onPlaying");
     __publicField(this, "videoFrameCallbackID");
     __publicField(this, "frameNotificationSequence", 0);
+    /**
+     * 远端插帧配置与渲染资源
+     */
     __publicField(this, "interpolationOptions");
     __publicField(this, "interpolationPipeline");
     __publicField(this, "interpolationCanvas");
+    /**
+     * DOM 挂载状态
+     */
     __publicField(this, "detached", false);
-    this.contentMode = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _210 => _210.videoContentMode]), () => ( "fill")) /* fill */;
+    this.contentMode = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _205 => _205.videoContentMode]), () => ( "fill")) /* fill */;
     this.element = document.createElement("div");
     this.element.style.position = "relative";
     this.element.style.overflow = "hidden";
@@ -7439,10 +8308,15 @@ var XmaxVideoView = class {
     this.applyContentMode();
     this.element.appendChild(this.videoElement);
   }
-  /** 当前显示的视频轨道；切换时自动解绑旧轨道。 */
+  /**
+   * 当前显示的视频轨道；切换时自动解绑旧轨道。
+   */
   get track() {
     return this.currentTrack;
   }
+  /**
+   * 解绑旧轨道后接入新轨道，并为新内容重新启用一次性首帧通知。
+   */
   set track(track) {
     if (this.currentTrack === track) {
       return;
@@ -7454,10 +8328,15 @@ var XmaxVideoView = class {
       this.attachTrack(track);
     }
   }
-  /** 视频内容在容器中的显示模式。 */
+  /**
+   * 视频内容在容器中的显示模式。
+   */
   get videoContentMode() {
     return this.contentMode;
   }
+  /**
+   * 更新视频及插帧画布的内容缩放方式；相同配置不重复应用。
+   */
   set videoContentMode(mode) {
     if (this.contentMode === mode) {
       return;
@@ -7465,10 +8344,15 @@ var XmaxVideoView = class {
     this.contentMode = mode;
     this.applyContentMode();
   }
-  /** 本地预览是否镜像显示（仅影响显示，不影响发布流）。 */
+  /**
+   * 本地预览是否镜像显示（仅影响显示，不影响发布流）。
+   */
   get isMirrored() {
     return this.mirrored;
   }
+  /**
+   * 更新视图镜像变换，仅改变呈现方式，不改动媒体流。
+   */
   set isMirrored(mirrored) {
     if (this.mirrored === mirrored) {
       return;
@@ -7476,7 +8360,9 @@ var XmaxVideoView = class {
     this.mirrored = mirrored;
     this.applyContentMode();
   }
-  /** 挂载到容器元素。 */
+  /**
+   * 挂载到容器元素。
+   */
   attach(to) {
     this.detached = false;
     to.appendChild(this.element);
@@ -7491,14 +8377,18 @@ var XmaxVideoView = class {
       this.armFrameDisplayNotification();
     }
   }
-  /** 从容器元素移除。 */
+  /**
+   * 从容器元素移除。
+   */
   detach() {
     this.detached = true;
     this.stopInterpolation();
     this.cancelFrameDisplayNotification();
     this.element.remove();
   }
-  /** 直接设置渲染用的媒体流（绑定管线和直接渲染共用）。 @internal */
+  /**
+   * 直接设置渲染用的媒体流（绑定管线和直接渲染共用）。 @internal
+   */
   setMediaStream(stream) {
     if (this.videoElement.srcObject === stream) {
       return;
@@ -7512,13 +8402,18 @@ var XmaxVideoView = class {
       this.startInterpolation();
     }
   }
-  /** 由远端绑定注入配置；本地预览不走此管线。 @internal */
+  /**
+   * 由远端绑定注入配置；本地预览不走此管线。 @internal
+   */
   setFrameInterpolation(options) {
     if (options === this.interpolationOptions) return;
     this.stopInterpolation();
     this.interpolationOptions = options;
     this.startInterpolation();
   }
+  /**
+   * 视图已挂载且媒体与配置就绪时创建插帧画布和管线，避免重复启动。
+   */
   startInterpolation() {
     if (this.detached || this.interpolationPipeline || !this.interpolationOptions || !this.videoElement.srcObject) return;
     const canvas = document.createElement("canvas");
@@ -7538,14 +8433,19 @@ var XmaxVideoView = class {
     this.interpolationPipeline = pipeline;
     pipeline.start();
   }
+  /**
+   * 停止并释放插帧管线，移除辅助画布，保留原始视频元素。
+   */
   stopInterpolation() {
     const pipeline = this.interpolationPipeline;
     this.interpolationPipeline = void 0;
-    _optionalChain([pipeline, 'optionalAccess', _211 => _211.stop, 'call', _212 => _212()]);
-    _optionalChain([this, 'access', _213 => _213.interpolationCanvas, 'optionalAccess', _214 => _214.remove, 'call', _215 => _215()]);
+    _optionalChain([pipeline, 'optionalAccess', _206 => _206.stop, 'call', _207 => _207()]);
+    _optionalChain([this, 'access', _208 => _208.interpolationCanvas, 'optionalAccess', _209 => _209.remove, 'call', _210 => _210()]);
     this.interpolationCanvas = void 0;
   }
-  /** 接入轨道画面：优先走注册的渲染绑定，否则按媒体轨直接渲染。 */
+  /**
+   * 接入轨道画面：优先走注册的渲染绑定，否则按媒体轨直接渲染。
+   */
   attachTrack(track) {
     const binding = VideoRenderRegistry.binding(track);
     if (binding) {
@@ -7560,17 +8460,21 @@ var XmaxVideoView = class {
       () => `\u8F68\u9053 ${track.id} \u65E2\u6CA1\u6709\u6E32\u67D3\u7ED1\u5B9A\u4E5F\u6CA1\u6709\u5A92\u4F53\u8F68\uFF0C\u65E0\u6CD5\u663E\u793A`
     );
   }
-  /** 解绑当前轨道并清空渲染内容。 */
+  /**
+   * 解绑当前轨道并清空渲染内容。
+   */
   detachCurrentTrack() {
     const track = this.currentTrack;
     if (track) {
-      _optionalChain([VideoRenderRegistry, 'access', _216 => _216.binding, 'call', _217 => _217(track), 'optionalAccess', _218 => _218.detachHandler, 'call', _219 => _219(this)]);
+      _optionalChain([VideoRenderRegistry, 'access', _211 => _211.binding, 'call', _212 => _212(track), 'optionalAccess', _213 => _213.detachHandler, 'call', _214 => _214(this)]);
     }
     this.setFrameInterpolation(void 0);
     this.cancelFrameDisplayNotification();
     this.videoElement.srcObject = null;
   }
-  /** 首帧提交合成器时通知；旧浏览器回退到 playing 近似判断。 */
+  /**
+   * 首帧提交合成器时通知；旧浏览器回退到 playing 近似判断。
+   */
   armFrameDisplayNotification() {
     this.cancelFrameDisplayNotification();
     const sequence = this.frameNotificationSequence;
@@ -7582,8 +8486,8 @@ var XmaxVideoView = class {
       }
       this.hasNotifiedFrameDisplay = true;
       this.cancelFrameDisplayNotification();
-      _optionalChain([binding, 'optionalAccess', _220 => _220.frameDisplayHandler, 'optionalCall', _221 => _221()]);
-      _optionalChain([this, 'access', _222 => _222.frameDisplayHandler, 'optionalCall', _223 => _223()]);
+      _optionalChain([binding, 'optionalAccess', _215 => _215.frameDisplayHandler, 'optionalCall', _216 => _216()]);
+      _optionalChain([this, 'access', _217 => _217.frameDisplayHandler, 'optionalCall', _218 => _218()]);
     };
     if (typeof this.videoElement.requestVideoFrameCallback === "function") {
       this.videoFrameCallbackID = this.videoElement.requestVideoFrameCallback(notify);
@@ -7597,7 +8501,9 @@ var XmaxVideoView = class {
       queueMicrotask(notify);
     }
   }
-  /** 换流、解绑或卸载时取消观察，防止迟到的首帧归入下一条流。 */
+  /**
+   * 换流、解绑或卸载时取消观察，防止迟到的首帧归入下一条流。
+   */
   cancelFrameDisplayNotification() {
     this.frameNotificationSequence += 1;
     if (this.videoFrameCallbackID !== void 0) {
@@ -7609,7 +8515,9 @@ var XmaxVideoView = class {
       this.onPlaying = void 0;
     }
   }
-  /** 应用显示模式与镜像样式。 */
+  /**
+   * 应用显示模式与镜像样式。
+   */
   applyContentMode() {
     this.videoElement.style.objectFit = OBJECT_FIT[this.contentMode];
     this.videoElement.style.transform = this.mirrored ? "scaleX(-1)" : "";
@@ -7631,19 +8539,27 @@ var XmaxRealtimeVideoView = class {
    * @param options.videoContentMode 本地与远端视频的内容显示模式，默认 fill。
    */
   constructor(options) {
-    // 视图元素
-    /** 视图根元素。 */
+    /**
+     * 视图元素
+     */
+    /**
+     * 视图根元素。
+     */
     __publicField(this, "element");
-    // 视频视图
+    /**
+     * 视频视图
+     */
     __publicField(this, "localVideoView");
     __publicField(this, "remoteVideoView");
-    // 公共配置
+    /**
+     * 公共配置
+     */
     __publicField(this, "currentLocalTrack");
     __publicField(this, "currentRemoteTrack");
     __publicField(this, "contentMode");
-    this.contentMode = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _224 => _224.videoContentMode]), () => ( "fill")) /* fill */;
-    this.currentLocalTrack = _optionalChain([options, 'optionalAccess', _225 => _225.localTrack]);
-    this.currentRemoteTrack = _optionalChain([options, 'optionalAccess', _226 => _226.remoteTrack]);
+    this.contentMode = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _219 => _219.videoContentMode]), () => ( "fill")) /* fill */;
+    this.currentLocalTrack = _optionalChain([options, 'optionalAccess', _220 => _220.localTrack]);
+    this.currentRemoteTrack = _optionalChain([options, 'optionalAccess', _221 => _221.remoteTrack]);
     this.element = document.createElement("div");
     this.element.style.position = "relative";
     this.element.style.overflow = "hidden";
@@ -7658,10 +8574,15 @@ var XmaxRealtimeVideoView = class {
     this.localVideoView.track = this.currentLocalTrack;
     this.updateRemoteTrack();
   }
-  /** 当前显示的本地视频轨道。 */
+  /**
+   * 当前显示的本地视频轨道。
+   */
   get localTrack() {
     return this.currentLocalTrack;
   }
+  /**
+   * 替换本地预览轨道；轨道未变化时保留当前绑定。
+   */
   set localTrack(track) {
     if (this.currentLocalTrack === track) {
       return;
@@ -7676,6 +8597,9 @@ var XmaxRealtimeVideoView = class {
   get remoteTrack() {
     return this.currentRemoteTrack;
   }
+  /**
+   * 替换远端轨道并重新等待首帧渐入；清空轨道时恢复本地预览。
+   */
   set remoteTrack(track) {
     if (this.currentRemoteTrack === track) {
       return;
@@ -7683,10 +8607,15 @@ var XmaxRealtimeVideoView = class {
     this.currentRemoteTrack = track;
     this.updateRemoteTrack();
   }
-  /** 视频内容在容器中的显示模式。 */
+  /**
+   * 视频内容在容器中的显示模式。
+   */
   get videoContentMode() {
     return this.contentMode;
   }
+  /**
+   * 同步调整本地与远端视频在容器中的缩放和裁剪方式。
+   */
   set videoContentMode(mode) {
     if (this.contentMode === mode) {
       return;
@@ -7695,26 +8624,37 @@ var XmaxRealtimeVideoView = class {
     this.localVideoView.videoContentMode = mode;
     this.remoteVideoView.videoContentMode = mode;
   }
-  /** 本地预览是否镜像显示（前置摄像头）。 */
+  /**
+   * 本地预览是否镜像显示（前置摄像头）。
+   */
   get isLocalMirrored() {
     return this.localVideoView.isMirrored;
   }
+  /**
+   * 更新本地预览镜像；不修改采集帧或远端画面。
+   */
   set isLocalMirrored(mirrored) {
     this.localVideoView.isMirrored = mirrored;
   }
-  /** 挂载到容器元素。 */
+  /**
+   * 挂载到容器元素。
+   */
   attach(to) {
     to.appendChild(this.element);
     this.localVideoView.attach(this.element);
     this.remoteVideoView.attach(this.element);
   }
-  /** 从容器元素移除。 */
+  /**
+   * 从容器元素移除。
+   */
   detach() {
     this.localVideoView.detach();
     this.remoteVideoView.detach();
     this.element.remove();
   }
-  /** 更新远端轨道绑定：重置渐入状态，等待首帧提交后再显示远端画面。 */
+  /**
+   * 更新远端轨道绑定：重置渐入状态，等待首帧提交后再显示远端画面。
+   */
   updateRemoteTrack() {
     const remoteTrack = this.currentRemoteTrack;
     this.remoteVideoView.frameDisplayHandler = void 0;
@@ -7733,7 +8673,9 @@ var XmaxRealtimeVideoView = class {
     };
     this.remoteVideoView.track = remoteTrack;
   }
-  /** 远端首帧已提交：渐入远端画面。 */
+  /**
+   * 远端首帧已提交：渐入远端画面。
+   */
   showRemoteVideo() {
     const element = this.remoteVideoView.element;
     if (element.style.visibility === "visible" && element.style.opacity === "1") {
@@ -7776,4 +8718,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.RealtimeModel = RealtimeModel; exports.defaultFrameRate = defaultFrameRate; exports.defaultCameraVideoFormat = defaultCameraVideoFormat; exports.MediaService = MediaService; exports.StoredFile = StoredFile; exports.StorageService = StorageService; exports.CameraPosition = CameraPosition; exports.RealtimeVideoTrack = RealtimeVideoTrack; exports.RealtimeMediaStream = RealtimeMediaStream; exports.RealtimeConnectionState = RealtimeConnectionState; exports.RealtimeReason = RealtimeReason; exports.RealtimeState = RealtimeState; exports.XmaxConfiguration = XmaxConfiguration; exports.XmaxClient = XmaxClient; exports.RealtimeConfiguration = RealtimeConfiguration; exports.VideoContentMode = VideoContentMode; exports.RealtimeContext = RealtimeContext; exports.XmaxVideoView = XmaxVideoView; exports.XmaxRealtimeVideoView = XmaxRealtimeVideoView;
-//# sourceMappingURL=chunk-JJWUZ3AW.cjs.map
+//# sourceMappingURL=chunk-FH3OPC6F.cjs.map