@realsee/live 0.7.3-alpha.0 → 0.7.4

package/dist/index.es.js

@@ -4,12 +4,12 @@ var a = (i, t, e) => cn(i, typeof t != "symbol" ? t + "" : t, e);
 import le from "trtc-js-sdk";
 import { ConsoleLogger as ln, LogLevel as an, DefaultDeviceController as hn, MeetingSessionConfiguration as un, DefaultMeetingSession as dn, DefaultModality as Fe, MeetingSessionStatusCode as fn } from "amazon-chime-sdk-js";
 import gn from "@realsee/jsbridge-x";
-import D, { createContext as pn, useCallback as P } from "react";
+import D, { createContext as pn, useCallback as W } from "react";
 const dt = Symbol("$$REALSEE_LIVE_EVENT$$");
 function $t(i) {
   return i[dt] || (i[dt] = {}), i[dt];
 }
-function Pe(i) {
+function We(i) {
   const t = i[dt];
   if (!t) return;
   Object.keys(t).some((n) => Array.isArray(t[n]) && t[n].length > 0) || delete i[dt];
@@ -63,11 +63,11 @@ class At {
       return;
     }
     if (n[t] || (n[t] = []), e === void 0) {
-      n[t].length = 0, Pe(this);
+      n[t].length = 0, We(this);
       return;
     }
     const s = n[t].findIndex((r) => r[0] === e);
-    s !== -1 && n[t].splice(s, 1), Pe(this);
+    s !== -1 && n[t].splice(s, 1), We(this);
   }
   /**
    * 触发事件
@@ -129,6 +129,13 @@ function Lt() {
   return [tt(), tt(), "4" + tt().substring(0, 3), tt(), tt(), tt() + tt() + tt()].join("-").toLowerCase();
 }
 class mn extends Re {
+  /**
+   * 创建 BrowserRTC 实例
+   * 
+   * @param options 配置选项
+   * @param options.getVoiceSign 获取语音签名的函数，必需
+   * @param options.autoPlayConfirm 自动播放确认回调（可选），用于处理浏览器的自动播放策略
+   */
   constructor(e) {
     super();
     a(this, "type", ct.RealseeBrowserRTC);
@@ -139,8 +146,21 @@ class mn extends Re {
       throw new Error("方法 getVoiceSign 未实现");
     });
     a(this, "_autoPlayConfirm");
+    /**
+     * 检查系统要求
+     * 
+     * 检查浏览器是否满足 TRTC 的系统要求。
+     * 
+     * @returns 系统要求检查结果
+     */
     a(this, "checkRequirement", () => le.checkSystemRequirements());
+    /**
+     * DOM 容器（内部使用）
+     */
     a(this, "$dom", document.createElement("div"));
+    /**
+     * TRTC 实例（内部使用）
+     */
     a(this, "_trtc", {
       client: null,
       stream: null
@@ -242,7 +262,15 @@ class mn extends Re {
     ), (r = this._trtc.client) == null || r.on("error", (o) => this.emit("error", o));
   }
 }
-class We extends Re {
+class Pe extends Re {
+  /**
+   * 创建 BrowserRTC4Chime 实例
+   * 
+   * @param options 配置选项
+   * @param options.getVoiceSign 获取语音签名的函数，必需
+   * @param options.autoPlayConfirm 自动播放确认回调（可选），用于处理浏览器的自动播放策略
+   * @param options.logLevel 日志级别（可选），默认为 LogLevel.INFO
+   */
   constructor(e) {
     super();
     a(this, "type", ct.RealseeBrowserChimeRTC);
@@ -265,13 +293,16 @@ class We extends Re {
     a(this, "$dom", document.createElement("div"));
     a(this, "$audio", document.createElement("audio"));
     /**
-     * 对audio标签初始化
+     * 初始化 DOM 元素（内部方法）
+     * 创建并挂载 audio 标签到页面
      */
     a(this, "_initDom", () => {
       this.$audio.id = `rs-rtc-${Lt()}`, this.$dom.id = `rs-rtc-${Lt()}`, this.$dom.appendChild(this.$audio), document.body.appendChild(this.$dom);
     });
     /**
      * 初始化事件监听器
+     * 
+     * 设置设备变化、音视频事件等监听器
      */
     a(this, "initObservers", () => {
       this.deviceChangeObserver = {
@@ -463,6 +494,13 @@ class We extends Re {
 }
 var ht = /* @__PURE__ */ ((i) => (i[i.Success = 0] = "Success", i[i.Failure = 1] = "Failure", i[i.ReJoin = 2] = "ReJoin", i[i.NoMicroPermission = 3] = "NoMicroPermission", i[i.Unknown = 500] = "Unknown", i))(ht || {});
 class wn extends Re {
+  /**
+   * 创建 VRWebViewRTC 实例
+   * 
+   * @param options 配置选项，包含以下属性：
+   * - jsBridge: JSBridge 实例，必需，用于与原生 App 通信
+   * - getVoiceSign: 获取语音签名的函数，必需
+   */
   constructor({ jsBridge: e, getVoiceSign: n }) {
     super();
     a(this, "type", ct.RealseeVRWebViewRTC);
@@ -475,23 +513,30 @@ class wn extends Re {
     a(this, "_joinOptions", null);
     a(this, "options");
     /**
-     * 处理用户音量
-     * @param userVolumes
+     * 处理用户音量（内部方法）
+     * 
+     * @param userVolumes 用户音量数组
      */
     a(this, "handleUserVolumes", (e) => {
       this.emit("userVolumes", e);
     });
     /**
-     * 处理弱网络情况
-     * @param weakNetwork
+     * 处理弱网络情况（内部方法）
+     * 
+     * @param weakNetwork 是否为弱网络
      */
     a(this, "handleWeakNetwork", (e) => {
       e && this.emit("weakNetwork");
     });
     /**
      * 加入语音房间
-     * @param options
-     * @returns
+     * 
+     * @param options 加入房间的选项
+     * @param options.voiceId 语音房间ID
+     * @param options.userId 用户ID
+     * @param options.roomId 房间ID
+     * @param options.type RTC类型
+     * @returns Promise<boolean> 是否成功加入房间
      */
     a(this, "join", async (e) => {
       this._joinOptions = e, this.emit("joinWillStart");
@@ -655,11 +700,16 @@ class wn extends Re {
     });
     this.options = { jsBridge: e, getVoiceSign: n }, this.jsBridge.webViewType !== "WxMiniProgramWebView" && this.jsBridge.callAndListen("live/userVolumes", this.handleUserVolumes), this.jsBridge.callAndListen("live/weakNetwork", this.handleWeakNetwork), this.on("inner.rtc.fail", this.handleJoinResult);
   }
+  /**
+   * 获取 JSBridge 实例
+   * 
+   * @returns JSBridge 协议实例
+   */
   get jsBridge() {
     return this.options.jsBridge;
   }
 }
-var B = /* @__PURE__ */ ((i) => (i.SelfUserInfo = "SELF_USER_INFO", i.RoomInfo = "ROOM_INFO", i.RTCInfo = "RTC_INFO", i.UserList = "USER_LIST", i.BuiltinMsg = "BUILTIN_MSG", i.CustomEvent = "CUSTOM_EVENT", i.KeyframeSync = "KEYFRAME_SYNC", i.UserKickOut = "USER_KICK_OUT", i))(B || {}), W = /* @__PURE__ */ ((i) => (i.UserChange = "user_change", i.RoomChange = "room_change", i))(W || {}), z = /* @__PURE__ */ ((i) => (i.UserMicroStatus = "change_micro_status", i.UserMicroStatusSync = "sync_micro_status", i.UserPermission = "change_permission", i.UserStatus = "change_status", i.UserInfo = "change_info", i.RoomClose = "close", i))(z || {}), ot = /* @__PURE__ */ ((i) => (i.OPEN = "OPEN", i.CLOSE = "CLOSE", i))(ot || {});
+var B = /* @__PURE__ */ ((i) => (i.SelfUserInfo = "SELF_USER_INFO", i.RoomInfo = "ROOM_INFO", i.RTCInfo = "RTC_INFO", i.UserList = "USER_LIST", i.BuiltinMsg = "BUILTIN_MSG", i.CustomEvent = "CUSTOM_EVENT", i.KeyframeSync = "KEYFRAME_SYNC", i.UserKickOut = "USER_KICK_OUT", i))(B || {}), P = /* @__PURE__ */ ((i) => (i.UserChange = "user_change", i.RoomChange = "room_change", i))(P || {}), z = /* @__PURE__ */ ((i) => (i.UserMicroStatus = "change_micro_status", i.UserMicroStatusSync = "sync_micro_status", i.UserPermission = "change_permission", i.UserStatus = "change_status", i.UserInfo = "change_info", i.RoomClose = "close", i))(z || {}), ot = /* @__PURE__ */ ((i) => (i.OPEN = "OPEN", i.CLOSE = "CLOSE", i))(ot || {});
 function Mr(i) {
   try {
     const t = JSON.parse(i), e = {
@@ -972,62 +1022,80 @@ class Mn extends At {
   }
 }
 class Nn extends At {
+  /**
+   * 创建带看控制器实例
+   * 
+   * 会自动初始化 WebSocket 事件监听器
+   */
   constructor() {
     super();
     /**
-     * ws代理器
+     * WebSocket 代理器（内部使用）
+     * 基于 RobustWebSocket 实现，提供自动重连能力
      */
     a(this, "_ws", new Mn({
       url: "",
       robustOptions: { should1000Reconnect: !0, ignoreConnectivityEvents: !0 }
     }));
     /**
-     * 带看连接状态
+     * 带看连接状态（内部存储）
      */
     a(this, "_state", j.NOTINITIALIZED);
     /**
-     * 添加事件监听
+     * 添加 WebSocket 事件监听（内部方法）
+     * 监听 WebSocket 的各种事件并转换为控制器事件
      */
     a(this, "_addWebSocketEventListeners", () => {
       this._ws.on("close", this._handleCloseEvent), this._ws.on("closing", this._handleClosingEvent), this._ws.on("connecting", this._handleConnectingEvent), this._ws.on("error", this._handleErrorEvent), this._ws.on("message", this._handleMessageEvent), this._ws.on("open", this._handleOpenEvent), this._ws.on("timeout", this._handleTimeoutEvent);
     });
     /**
-     * 移除事件监听
+     * 移除 WebSocket 事件监听（内部方法）
+     * 在销毁实例时调用，清理所有事件监听器
      */
     a(this, "_removeWebSocketEventListeners", () => {
       this._ws.off("close", this._handleCloseEvent), this._ws.off("closing", this._handleClosingEvent), this._ws.off("connecting", this._handleConnectingEvent), this._ws.off("error", this._handleErrorEvent), this._ws.off("message", this._handleMessageEvent), this._ws.off("open", this._handleOpenEvent), this._ws.off("timeout", this._handleTimeoutEvent);
     });
     /**
-     * 处理房间关闭事件
-     * @param event
+     * 处理 WebSocket 关闭事件（内部方法）
+     * 
+     * @param event WebSocket 关闭事件对象
      */
     a(this, "_handleCloseEvent", (e) => {
       m.info(`live room closed bacause of ${e.code}-${e.reason || En(e.code)}`), this.state = j.CLOSED;
     });
     /**
-     * 处理房间正在关闭事件（这个时候可能是断网了）
+     * 处理 WebSocket 正在关闭事件（内部方法）
+     * 
+     * 当连接正在关闭时触发，可能是由于网络断开等原因
      */
     a(this, "_handleClosingEvent", () => {
       var e;
       m.info("live room is closing, onLine:", (e = globalThis == null ? void 0 : globalThis.navigator) == null ? void 0 : e.onLine), this.state = j.CLOSED;
     });
     /**
-     * 连接中
-     * @param event
+     * 处理 WebSocket 连接中事件（内部方法）
+     * 
+     * 当开始连接或重连时触发，如果是重连会触发 reconnecting 事件
+     * 
+     * @param ev WebSocket 连接事件对象
      */
     a(this, "_handleConnectingEvent", (e) => {
       m.info("live room is connecting"), this.state = j.CONNECTING, e.detail.reconnects > 0 && this.emit("reconnecting", e.detail);
     });
     /**
-     * 连接发送异常
-     * @param event
+     * 处理 WebSocket 错误事件（内部方法）
+     * 
+     * @param event 错误事件对象
      */
     a(this, "_handleErrorEvent", (e) => {
       m.error("live room error", e), this.state = j.CLOSED;
     });
     /**
-     * 接收到消息
-     * @param event
+     * 处理 WebSocket 消息事件（内部方法）
+     * 
+     * 解析接收到的消息并触发 message 事件
+     * 
+     * @param event WebSocket 消息事件对象
      */
     a(this, "_handleMessageEvent", (e) => {
       let n = (() => {
@@ -1040,41 +1108,90 @@ class Nn extends At {
       this.emit("message", n);
     });
     /**
-     * 连接建立成功
-     * @param event
+     * 处理 WebSocket 连接成功事件（内部方法）
+     * 
+     * 当连接建立成功时触发，如果是重连成功会触发 reconnected 事件
+     * 
+     * @param event WebSocket 打开事件对象
      */
     a(this, "_handleOpenEvent", (e) => {
       m.info("live room open", e.detail), this.state = j.OPEN, e.detail.reconnects > 0 && this.emit("reconnected", e.detail);
     });
     /**
-     * 处理超时
-     * @param event
+     * 处理 WebSocket 连接超时事件（内部方法）
+     * 
+     * @param event WebSocket 超时事件对象
      */
     a(this, "_handleTimeoutEvent", (e) => {
       m.error("live room connect timeout!", e.detail), this.state = j.CLOSED;
     });
     /**
-     * 释放资源，释放之后需要重新实例化
-     * @returns
+     * 释放控制器资源
+     * 
+     * 移除所有事件监听器并关闭 WebSocket 连接。
+     * 释放后需要重新实例化才能使用。
+     * 
+     * @returns Promise<boolean> 关闭是否成功
+     * @example
+     * ```typescript
+     * await controller.dispose()
+     * ```
      */
     a(this, "dispose", async () => (this._removeWebSocketEventListeners(), await this.close("live room close by controller disposed!")));
     /**
-     * 开启房间链接
-     * @param url  房间链接
-     * @returns
+     * 打开 WebSocket 连接
+     * 
+     * 开始建立与服务器的 WebSocket 连接。
+     * 
+     * @param url WebSocket 连接地址（ws:// 或 wss://）
+     * @example
+     * ```typescript
+     * controller.open('wss://example.com/live?ticket=xxx')
+     * ```
      */
     a(this, "open", (e) => this._ws.open(e));
     /**
-     * 关闭房间
-     * @param code
-     * @param reason
+     * 关闭 WebSocket 连接
+     * 
+     * 关闭与服务器的 WebSocket 连接。
+     * 
+     * @param code 关闭代码（可选），WebSocket 关闭码
+     * @param reason 关闭原因（可选），关闭原因字符串
+     * @returns Promise<boolean> 关闭是否成功
+     * @example
+     * ```typescript
+     * // 正常关闭
+     * await controller.close()
+     * 
+     * // 指定关闭码和原因
+     * await controller.close(1000, '正常关闭')
+     * ```
      */
     a(this, "close", (e, n) => new Promise((s) => {
       this._ws.once("close", () => s(!0)), this._ws.close(e, n);
     }));
     /**
-     * 发送数据
-     * @param data
+     * 发送消息到服务器
+     * 
+     * 只有在连接状态为 OPEN 时才能发送消息。
+     * 消息会被自动序列化为 JSON 字符串。
+     * 
+     * @param data 要发送的数据对象，不能为 undefined 或 null
+     * @returns 发送是否成功
+     * @throws {Error} 如果消息为空或连接未打开，会抛出错误
+     * @example
+     * ```typescript
+     * // 发送消息
+     * controller.sendMessage({
+     *   command: 'test',
+     *   data: { message: 'hello' }
+     * })
+     * 
+     * // 检查连接状态
+     * if (controller.state === LiveState.OPEN) {
+     *   controller.sendMessage({ command: 'ping' })
+     * }
+     * ```
      */
     a(this, "sendMessage", (e = "") => {
       if (e == null)
@@ -1084,17 +1201,38 @@ class Nn extends At {
       return this._ws.send(JSON.stringify(e));
     });
     /**
-     * 准备关闭带看
+     * 准备关闭带看连接
+     * 
+     * 标记连接为显式关闭，防止自动重连。
+     * 通常在用户主动退出时调用。
+     * 
+     * @example
+     * ```typescript
+     * controller.readyClose()
+     * await controller.close()
+     * ```
      */
     a(this, "readyClose", () => {
       this._ws && (this._ws._explicitlyClosed = !0);
     });
     this._addWebSocketEventListeners();
   }
+  /**
+   * 设置连接状态
+   * 
+   * 当状态改变时，会自动触发 stateChange 事件
+   * 
+   * @param state 新的连接状态
+   */
   set state(e) {
     const n = JSON.parse(JSON.stringify(this._state));
     this._state = e, this.emit("stateChange", this.state, n);
   }
+  /**
+   * 获取当前连接状态
+   * 
+   * @returns 当前连接状态
+   */
   get state() {
     return this._state;
   }
@@ -1180,7 +1318,7 @@ class $n {
     this._observers = G();
   }
 }
-const lt = Math.floor, Pt = Math.abs, pi = (i, t) => i < t ? i : t, St = (i, t) => i > t ? i : t, xn = (i) => i !== 0 ? i < 0 : 1 / i < 0, Je = 1, He = 2, he = 4, ue = 8, Bn = 32, _i = 64, Ht = 128, Fn = 31, qe = 63, Ot = 127, Pn = 2147483647, Wn = Number.isInteger || ((i) => typeof i == "number" && isFinite(i) && lt(i) === i), Kn = (i) => i.toLowerCase(), Gn = /^\s*/g, Jn = (i) => i.replace(Gn, ""), Hn = /([A-Z])/g, ze = (i, t) => Jn(i.replace(Hn, (e) => `${t}${Kn(e)}`)), qn = (i) => {
+const lt = Math.floor, Wt = Math.abs, pi = (i, t) => i < t ? i : t, St = (i, t) => i > t ? i : t, xn = (i) => i !== 0 ? i < 0 : 1 / i < 0, Je = 1, He = 2, he = 4, ue = 8, Bn = 32, _i = 64, Ht = 128, Fn = 31, qe = 63, Ot = 127, Wn = 2147483647, Pn = Number.isInteger || ((i) => typeof i == "number" && isFinite(i) && lt(i) === i), Kn = (i) => i.toLowerCase(), Gn = /^\s*/g, Jn = (i) => i.replace(Gn, ""), Hn = /([A-Z])/g, ze = (i, t) => Jn(i.replace(Hn, (e) => `${t}${Kn(e)}`)), qn = (i) => {
   const t = unescape(encodeURIComponent(i)), e = t.length, n = new Uint8Array(e);
   for (let s = 0; s < e; s++)
     n[s] = /** @type {number} */
@@ -1260,7 +1398,7 @@ Tt.encodeInto ? ts : es, De = (i, t) => {
       A(i, 119), ft(i, t);
       break;
     case "number":
-      Wn(t) && Pt(t) <= Pn ? (A(i, 125), Te(i, t)) : rs(t) ? (A(i, 124), is(i, t)) : (A(i, 123), ns(i, t));
+      Pn(t) && Wt(t) <= Wn ? (A(i, 125), Te(i, t)) : rs(t) ? (A(i, 124), is(i, t)) : (A(i, 123), ns(i, t));
       break;
     case "bigint":
       A(i, 122), ss(i, t);
@@ -1308,7 +1446,7 @@ class Xe extends jt {
 const Ze = (i) => {
   i.count > 0 && (Te(i.encoder, i.count === 1 ? i.s : -i.s), i.count > 1 && S(i.encoder, i.count - 2));
 };
-class Wt {
+class Pt {
   constructor() {
     this.encoder = new jt(), this.s = 0, this.count = 0;
   }
@@ -1354,7 +1492,7 @@ class fe {
 }
 class os {
   constructor() {
-    this.sarr = [], this.s = "", this.lensE = new Wt();
+    this.sarr = [], this.s = "", this.lensE = new Pt();
   }
   /**
    * @param {string} string
@@ -1822,7 +1960,7 @@ class Ct extends $n {
     this.emit("destroyed", [!0]), this.emit("destroy", [this]), super.destroy();
   }
 }
-class Ps {
+class Ws {
   constructor() {
     this.restEncoder = Le();
   }
@@ -1844,7 +1982,7 @@ class Ps {
     S(this.restEncoder, t);
   }
 }
-class Ws extends Ps {
+class Ps extends Ws {
   /**
    * @param {ID} id
    */
@@ -1947,7 +2085,7 @@ class Ks {
 }
 class Gs extends Ks {
   constructor() {
-    super(), this.keyMap = /* @__PURE__ */ new Map(), this.keyClock = 0, this.keyClockEncoder = new fe(), this.clientEncoder = new Wt(), this.leftClockEncoder = new fe(), this.rightClockEncoder = new fe(), this.infoEncoder = new Xe(Ce), this.stringEncoder = new os(), this.parentInfoEncoder = new Xe(Ce), this.typeRefEncoder = new Wt(), this.lenEncoder = new Wt();
+    super(), this.keyMap = /* @__PURE__ */ new Map(), this.keyClock = 0, this.keyClockEncoder = new fe(), this.clientEncoder = new Pt(), this.leftClockEncoder = new fe(), this.rightClockEncoder = new fe(), this.infoEncoder = new Xe(Ce), this.stringEncoder = new os(), this.parentInfoEncoder = new Xe(Ce), this.typeRefEncoder = new Pt(), this.lenEncoder = new Pt();
   }
   toUint8Array() {
     const t = Le();
@@ -2263,7 +2401,7 @@ const ci = (i, t) => t.deleteSet.clients.size === 0 && !Un(t.afterState, (e, n)
         y + 1 < w.length && Gt(w, y + 1) > 1 || y > 0 && Gt(w, y);
       }
       if (!e.local && e.afterState.get(n.clientID) !== e.beforeState.get(n.clientID) && (Vs(Ve, Si, "[yjs] ", Ci, Ei, "Changed the client-id because another client seems to be using it."), n.clientID = Ti()), n.emit("afterTransactionCleanup", [e, n]), n._observers.has("update")) {
-        const u = new Ws();
+        const u = new Ps();
         ci(u, e) && n.emit("update", [u.toUint8Array(), e.origin, n, e]);
       }
       if (n._observers.has("updateV2")) {
@@ -2470,7 +2608,7 @@ const rr = (i) => {
 }, ie = (i, t) => {
   if (i._start === null || t === 0 || i._searchMarker === null)
     return null;
-  const e = i._searchMarker.length === 0 ? null : i._searchMarker.reduce((r, o) => Pt(t - r.index) < Pt(t - o.index) ? r : o);
+  const e = i._searchMarker.length === 0 ? null : i._searchMarker.reduce((r, o) => Wt(t - r.index) < Wt(t - o.index) ? r : o);
   let n = i._start, s = 0;
   for (e !== null && (n = e.p, s = e.index, rr(e)); n.right !== null && s < t; ) {
     if (!n.deleted && n.countable) {
@@ -2484,7 +2622,7 @@ const rr = (i) => {
     n = n.left, !n.deleted && n.countable && (s -= n.length);
   for (; n.left !== null && n.left.id.client === n.id.client && n.left.id.clock + n.left.length === n.id.clock; )
     n = n.left, !n.deleted && n.countable && (s -= n.length);
-  return e !== null && Pt(e.index - s) < /** @type {YText|YArray<any>} */
+  return e !== null && Wt(e.index - s) < /** @type {YText|YArray<any>} */
   n.parent.length / Ui ? (ji(e, n, s), e) : or(i._searchMarker, n, s);
 }, Nt = (i, t, e) => {
   for (let n = i.length - 1; n >= 0; n--) {
@@ -2740,9 +2878,9 @@ const $i = (i, t, e) => {
           }
       }
   }), u();
-}, Pi = () => mt("Length exceeded!"), Wi = (i, t, e, n) => {
+}, Wi = () => mt("Length exceeded!"), Pi = (i, t, e, n) => {
   if (e > t._length)
-    throw Pi();
+    throw Wi();
   if (e === 0)
     return t._searchMarker && Nt(t._searchMarker, e, n.length), zt(i, t, null, n);
   const s = e, r = ie(t, e);
@@ -2772,7 +2910,7 @@ const $i = (i, t, e) => {
   for (; n > 0 && c !== null; )
     c.deleted || (n < c.length && nt(i, k(c.id.client, c.id.clock + n)), c.delete(i), n -= c.length), c = c.right;
   if (n > 0)
-    throw Pi();
+    throw Wi();
   t._searchMarker && Nt(
     t._searchMarker,
     s,
@@ -2933,7 +3071,7 @@ class Rt extends M {
    */
   insert(t, e) {
     this.doc !== null ? E(this.doc, (n) => {
-      Wi(
+      Pi(
         n,
         this,
         t,
@@ -4188,7 +4326,7 @@ class wt extends M {
    */
   insert(t, e) {
     this.doc !== null ? E(this.doc, (n) => {
-      Wi(n, this, t, e);
+      Pi(n, this, t, e);
     }) : this._prelimContent.splice(t, 0, ...e);
   }
   /**
@@ -5477,6 +5615,50 @@ const It = (i) => Promise.reject(new Error("unimplemented method GetVoiceSign"))
   window != null && window.__Realsee_Live__ && ((t = (i = window == null ? void 0 : window.__Realsee_Live__) == null ? void 0 : i.dispose) == null || t.call(i), window.__Realsee_Live__ = null);
 };
 class Ir extends At {
+  /**
+   * 创建 Live 带看实例
+   * 
+   * @param opts 带看配置选项，包含以下属性：
+   * - url: WebSocket 连接地址（可选，可在 connect 时提供）
+   * - getTicket: 获取连接票据的函数（可选，可在 connect 时提供）
+   * - rtc: RTC 实例（可选，如果不提供会根据配置自动创建）
+   * - rtcType: 指定内置 RTC 类型（当 rtc 为空时使用）
+   * - useBuiltInRTC: 是否使用内置 RTC（默认根据环境自动选择）
+   * - getVoiceSign: 获取语音签名的函数（使用内置 RTC 时必需）
+   * - jsBridge: JSBridge 实例（可选，用于 App/WebView 环境）
+   * - useBuiltInJsBridge: 是否使用内置 JSBridge（默认 false）
+   * - initialMicroStatus: 麦克风初始状态（默认 OPEN）
+   * - autoPlayConfirm: 自动播放确认回调（使用 BrowserRTC 时可能需要）
+   * - __debug__: 是否开启调试模式（会在控制台打印日志）
+   * 
+   * @example
+   * ```typescript
+   * // 基础用法
+   * const live = new Live({
+   *   url: 'wss://example.com/live',
+   *   getTicket: async () => {
+   *     const response = await fetch('/api/get-ticket')
+   *     return response.json().ticket
+   *   },
+   *   getVoiceSign: async (params) => {
+   *     const response = await fetch('/api/get-voice-sign', {
+   *       method: 'POST',
+   *       body: JSON.stringify(params)
+   *     })
+   *     return response.json()
+   *   },
+   *   useBuiltInRTC: true
+   * })
+   * 
+   * // 使用自定义 RTC
+   * const customRTC = new MyCustomRTC()
+   * const live = new Live({
+   *   rtc: customRTC,
+   *   url: 'wss://example.com/live',
+   *   getTicket: async () => 'ticket'
+   * })
+   * ```
+   */
   constructor(e) {
     super();
     /**
@@ -5484,20 +5666,40 @@ class Ir extends At {
      */
     a(this, "_options", {});
     /**
-     * 帧数据监听
+     * 帧数据监听器
+     * 
+     * 用于监听特定键的帧数据变化。当其他用户发送帧数据更新时，会触发对应键的事件。
+     * 
+     * @example
+     * ```typescript
+     * // 监听 camera 帧数据的变化
+     * live.keyframes.on('camera', (nextFrame, prevFrame, frontRequestId) => {
+     *   console.log('相机位置更新:', nextFrame)
+     * })
+     * ```
      */
     a(this, "keyframes", new At());
     /**
-     * 带看的 yDoc
+     * 带看的 Yjs 文档实例（用于帧数据同步）
      */
     a(this, "_yDoc");
     /**
-     * 内置的一些数据
+     * 内置的一些数据（用户信息、房间信息、帧数据等）
      */
     a(this, "_buildInData");
+    /**
+     * 初始化帧数据观察者（内部方法）
+     * 用于监听 Yjs Map 的变化并同步到其他用户
+     */
     a(this, "_initializeKeyframesObservers", () => {
       this._yDoc.getMap("keyframes").observe(this._handleKeyframesChange);
     });
+    /**
+     * 处理帧数据变化（内部方法）
+     * 当本地或远程帧数据发生变化时，会触发此方法进行同步
+     * 
+     * @param event Yjs Map 事件对象
+     */
     a(this, "_handleKeyframesChange", (e) => {
       var o;
       const { transaction: n, target: s, changes: r } = e;
@@ -5524,16 +5726,51 @@ class Ir extends At {
           }), r.keys.size !== 0 && this.emit("keyframes", this.snapshot, n.origin.frontRequestId);
     });
     /**
-     * 根据键值取帧数据
+     * 根据键值获取对应的帧数据
+     * 
+     * @template Key 帧数据的键类型
      * @param key 帧数据的键值
-     * @returns
+     * @returns 对应键的帧数据，如果不存在则返回 undefined
+     * @example
+     * ```typescript
+     * // 获取相机帧数据
+     * const cameraFrame = live.getFramesByKey('camera')
+     * if (cameraFrame) {
+     *   console.log('相机位置:', cameraFrame.position)
+     * }
+     * ```
      */
     a(this, "getFramesByKey", (e) => this.snapshot[e]);
     /**
      * 发送帧数据（需要能够被序列化）
+     * 
+     * 将帧数据同步到其他用户。帧数据必须是可序列化的 JSON 对象。
+     * 只有在连接状态为 OPEN 时才能发送。
+     * 
+     * @template Key 帧数据的键类型
      * @param key 帧数据键值
-     * @param frame 帧数据本体
-     * @returns 发送结果，成功返回true，失败返回false或Error
+     * @param frame 帧数据本体，必须可序列化
+     * @returns 发送结果，成功返回 true，连接未打开返回 false，其他错误返回 Error
+     * @example
+     * ```typescript
+     * // 发送相机位置更新
+     * const result = live.sendKeyframe('camera', {
+     *   position: [1, 2, 3],
+     *   rotation: [0, 0, 0]
+     * })
+     * 
+     * if (result === true) {
+     *   console.log('发送成功')
+     * } else {
+     *   console.error('发送失败:', result)
+     * }
+     * 
+     * // 发送标注更新
+     * live.sendKeyframe('annotation', {
+     *   text: '这是一个标注',
+     *   position: [100, 200]
+     * })
+     * ```
      */
     a(this, "sendKeyframe", (e, n) => {
       var s;
@@ -5548,22 +5785,41 @@ class Ir extends At {
       ), !0);
     });
     /**
-     * 带看控制器
+     * 带看控制器（内部使用）
      */
     a(this, "_controller", new Nn());
+    /**
+     * 初始化配置选项（内部方法）
+     * @param opts 配置选项
+     */
     a(this, "_initializeOptions", (e) => {
       var n;
       this._options = Object.assign({ initialMicroStatus: ot.OPEN }, e), this._options.jsBridge = this._initializeJsBridge(e), this._options.getVoiceSign = (n = e.getVoiceSign) != null ? n : It, this._options.autoPlayConfirm = e.autoPlayConfirm, this._options.rtc = this._initializeRTC(e);
     });
+    /**
+     * 初始化 JSBridge 实例（内部方法）
+     * @param opts 配置选项
+     * @returns JSBridge 实例或 undefined
+     */
     a(this, "_initializeJsBridge", (e) => {
       if (e.jsBridge) return e.jsBridge;
       if (e.useBuiltInJsBridge) return new gn();
     });
+    /**
+     * 初始化 RTC 实例（内部方法）
+     * @param opts 配置选项
+     * @returns RTC 实例或 undefined
+     */
     a(this, "_initializeRTC", (e) => {
       if (e.rtc) return e.rtc;
       if (e.rtcType) return this._createBuiltInRTC(e);
       if (e.useBuiltInRTC) return this._createDefaultRTC(e);
     });
+    /**
+     * 创建内置 RTC 实例（内部方法）
+     * @param opts 配置选项
+     * @returns RTC 实例或 undefined
+     */
     a(this, "_createBuiltInRTC", (e) => {
       var n;
       if (!e.getVoiceSign) {
@@ -5574,7 +5830,7 @@ class Ir extends At {
         case ct.RealseeVRWebViewRTC:
           return this._createVRWebViewRTC();
         case ct.RealseeBrowserChimeRTC:
-          return new We({
+          return new Pe({
             getVoiceSign: (n = this._options.getVoiceSign) != null ? n : It,
             logLevel: e.__debug__ ? 0 : 1
           });
@@ -5585,6 +5841,10 @@ class Ir extends At {
           return;
       }
     });
+    /**
+     * 创建 VRWebView RTC 实例（内部方法）
+     * @returns RTC 实例或 undefined
+     */
     a(this, "_createVRWebViewRTC", () => {
       var e;
       if (this._options.jsBridge)
@@ -5594,6 +5854,10 @@ class Ir extends At {
         });
       m.error("JsBridge instance must be passed when using built-in VRWebViewRTC instances");
     });
+    /**
+     * 创建浏览器 RTC 实例（内部方法）
+     * @returns RTC 实例或 undefined
+     */
     a(this, "_createBrowserRTC", () => {
       var e;
       if (!this._options.autoPlayConfirm) {
@@ -5605,14 +5869,28 @@ class Ir extends At {
         autoPlayConfirm: this._options.autoPlayConfirm
       });
     });
+    /**
+     * 创建默认 RTC 实例（内部方法）
+     * 根据环境自动选择合适的 RTC 实现
+     * @param opts 配置选项
+     * @returns RTC 实例或 undefined
+     */
     a(this, "_createDefaultRTC", (e) => {
       var s;
       const n = (s = this._options.getVoiceSign) != null ? s : It;
-      return !this._options.jsBridge || !Ge && !Ke ? e.builtInRTCType === fi.RealseeXChimeRTC ? new We({ getVoiceSign: n }) : this._createBrowserRTC() : Ge && (vn || In) || Ke ? this._createVRWebViewRTC() : this._createBrowserRTC();
+      return !this._options.jsBridge || !Ge && !Ke ? e.builtInRTCType === fi.RealseeXChimeRTC ? new Pe({ getVoiceSign: n }) : this._createBrowserRTC() : Ge && (vn || In) || Ke ? this._createVRWebViewRTC() : this._createBrowserRTC();
     });
+    /**
+     * 自动连接（内部方法）
+     * 如果配置中已提供 url 和 getTicket，则自动连接
+     */
     a(this, "_autoConnect", () => {
       this._options.url && this._options.getTicket && this.connect();
     });
+    /**
+     * 调试模式设置（内部方法）
+     * 在调试模式下，将实例挂载到 window 对象上
+     */
     a(this, "_debugSetup", () => {
       this._options.__debug__ && Object.assign(window, { $liveController: this._controller, $live: this });
     });
@@ -5715,7 +5993,7 @@ class Ir extends At {
             }
             case B.BuiltinMsg: {
               const p = u;
-              this.emit("builtinEvent", p), p.event_type === W.UserChange && this.emit("userChange", p), p.event_type === W.RoomChange && this.emit("roomChange", p), p.event_type === W.UserChange && p.action === z.UserMicroStatus && await this.toggleMicro(p.data.status === ot.OPEN), p.event_type === W.RoomChange && p.action === z.RoomClose && await this._exit();
+              this.emit("builtinEvent", p), p.event_type === P.UserChange && this.emit("userChange", p), p.event_type === P.RoomChange && this.emit("roomChange", p), p.event_type === P.UserChange && p.action === z.UserMicroStatus && await this.toggleMicro(p.data.status === ot.OPEN), p.event_type === P.RoomChange && p.action === z.RoomClose && await this._exit();
               break;
             }
             case B.UserKickOut: {
@@ -5736,9 +6014,46 @@ class Ir extends At {
       this._buildInData.keyframes.clear(), this._buildInData = { keyframes: this._yDoc.getMap("keyframes") };
     });
     /**
-     * 连接带看
-     * @param options 连接选项
-     * @returns 连接结果，成功返回true，失败返回Error
+     * 连接带看房间
+     * 
+     * 建立 WebSocket 连接并加入带看房间。如果配置中已提供 url 和 getTicket，
+     * 可以在创建实例后自动连接，也可以手动调用此方法。
+     * 
+     * @param options 连接选项，包含以下属性：
+     * - url: WebSocket 连接地址（可选，会覆盖构造函数中的配置）
+     * - getTicket: 获取连接票据的函数（可选，会覆盖构造函数中的配置）
+     * - rtcMicStatus: 麦克风初始状态（可选，会覆盖构造函数中的配置）
+     * - force: 是否强制连接（如果已有连接，会先关闭再连接）
+     * @returns 连接结果，成功返回 true，失败返回 Error
+     * @example
+     * ```typescript
+     * // 在创建实例时已配置 url 和 getTicket
+     * const live = new Live({
+     *   url: 'wss://example.com/live',
+     *   getTicket: async () => 'ticket'
+     * })
+     * 
+     * // 手动连接
+     * const result = await live.connect()
+     * if (result === true) {
+     *   console.log('连接成功')
+     * } else {
+     *   console.error('连接失败:', result.message)
+     * }
+     * 
+     * // 在连接时提供配置
+     * await live.connect({
+     *   url: 'wss://example.com/live',
+     *   getTicket: async () => {
+     *     const res = await fetch('/api/ticket')
+     *     return res.json().ticket
+     *   },
+     *   rtcMicStatus: MicroStatus.OPEN
+     * })
+     * 
+     * // 强制重连
+     * await live.connect({ force: true })
+     * ```
      */
     a(this, "connect", async (e = {}) => {
       var s, r, o, c;
@@ -5764,8 +6079,10 @@ class Ir extends At {
       }
     });
     /**
-     * 退出带看
-     * @returns
+     * 退出带看（内部方法）
+     * 清理数据并关闭连接，但不发送房间关闭消息
+     * 
+     * @returns Promise<boolean> 关闭是否成功
      */
     a(this, "_exit", async () => {
       var e;
@@ -5778,13 +6095,37 @@ class Ir extends At {
       return this.state !== j.OPEN ? !0 : await this._controller.close();
     });
     /**
-     * 退出带看
-     * @returns
+     * 退出带看房间
+     * 
+     * 这是 close 方法的别名，用于保持 API 的一致性。
+     * 
+     * @returns Promise<void>
+     * @example
+     * ```typescript
+     * // 退出带看
+     * await live.exit()
+     * ```
      */
     a(this, "exit", async () => this.close());
     /**
      * 关闭带看房间
-     * @returns 关闭结果
+     * 
+     * 关闭 WebSocket 连接、退出 RTC 房间，并发送房间关闭消息。
+     * 与 exit 方法不同的是，此方法会通知服务器房间已关闭。
+     * 
+     * @returns Promise<void>
+     * @example
+     * ```typescript
+     * // 关闭房间
+     * await live.close()
+     * 
+     * // 在组件卸载时关闭
+     * useEffect(() => {
+     *   return () => {
+     *     live.close()
+     *   }
+     * }, [])
+     * ```
      */
     a(this, "close", async () => {
       var e;
@@ -5794,11 +6135,27 @@ class Ir extends At {
       } catch (n) {
         m.warn(n);
       }
-      await this.updateStatus(W.RoomChange, z.RoomClose, {});
+      await this.updateStatus(P.RoomChange, z.RoomClose, {});
     });
     /**
-     * 销毁带看
-     * @returns
+     * 销毁带看实例
+     * 
+     * 完全销毁实例，清理所有资源，包括事件监听、Yjs 文档等。
+     * 销毁后实例不能再使用，需要重新创建。
+     * 
+     * @returns Promise<void>
+     * @example
+     * ```typescript
+     * // 销毁实例
+     * await live.dispose()
+     * 
+     * // 在组件卸载时销毁
+     * useEffect(() => {
+     *   return () => {
+     *     live.dispose()
+     *   }
+     * }, [])
+     * ```
      */
     a(this, "dispose", async () => {
       this._removeLiveControllerEventListeners();
@@ -5811,16 +6168,62 @@ class Ir extends At {
     });
     /**
      * 设置自己的用户信息
-     * @param userInfo
-     * @returns
+     * 
+     * 更新当前用户在房间中的信息，如昵称、头像等。
+     * 
+     * @param userInfo 用户信息的部分更新对象
+     * @returns Promise<boolean> 是否更新成功
+     * @example
+     * ```typescript
+     * // 更新昵称和头像
+     * await live.setSelfInfo({
+     *   extension: {
+     *     nickname: '新昵称',
+     *     avatar: 'https://example.com/avatar.jpg'
+     *   }
+     * })
+     * ```
      */
-    a(this, "setSelfInfo", async (e) => await this.updateStatus(W.UserChange, z.UserInfo, e));
+    a(this, "setSelfInfo", async (e) => await this.updateStatus(P.UserChange, z.UserInfo, e));
     /**
-     * 自定义广播
-     * @param request 广播请求的数据
-     * @param toUserIds
-     * @param timeout
-     * @returns
+     * 自定义广播消息
+     * 
+     * 向指定用户发送自定义消息，并等待响应。如果设置了超时时间，
+     * 超时后会拒绝 Promise。
+     * 
+     * @template Request 请求数据类型
+     * @template Response 响应数据类型
+     * @param request 广播请求的数据对象
+     * @param toUserIds 目标用户ID，可以是单个字符串或字符串数组，空数组表示广播给所有人
+     * @param timeout 超时时间（毫秒），0 表示不超时
+     * @returns Promise<Response> 响应数据，连接未打开返回 false，发送失败返回 Error
+     * @example
+     * ```typescript
+     * // 发送自定义消息并等待响应
+     * try {
+     *   const response = await live.broadcast(
+     *     { type: 'ping', data: 'hello' },
+     *     ['user-id-1', 'user-id-2'],
+     *     5000 // 5秒超时
+     *   )
+     *   console.log('收到响应:', response)
+     * } catch (error) {
+     *   console.error('广播失败或超时:', error)
+     * }
+     * 
+     * // 广播给所有人
+     * const response = await live.broadcast(
+     *   { type: 'announcement', message: '大家好' },
+     *   [],
+     *   0 // 不超时
+     * )
+     * 
+     * // 监听广播消息
+     * live.on('broadcast', (data, frontRequestId) => {
+     *   console.log('收到广播:', data)
+     *   // 可以在这里响应广播
+     * })
+     * ```
      */
     a(this, "broadcast", (e, n, s) => this.state !== j.OPEN ? !1 : new Promise((r, o) => {
       const c = we(B.CustomEvent, e, n), l = c.front_request_id, h = s ? setTimeout(() => {
@@ -5835,13 +6238,38 @@ class Ir extends At {
         o(d);
       }
     }));
-    // 仅用于用户自己的麦克风控制
+    /**
+     * 切换自己的麦克风状态
+     * 
+     * 开启或关闭自己的麦克风。只有拥有 control_own_micro 权限的用户才能操作。
+     * 
+     * @param microStatus 麦克风状态，true 表示开启，false 表示关闭
+     * @returns Promise<boolean> 是否操作成功，无权限返回 false
+     * @example
+     * ```typescript
+     * // 开启麦克风
+     * const result = await live.toggleMicro(true)
+     * if (result) {
+     *   console.log('麦克风已开启')
+     * }
+     * 
+     * // 关闭麦克风
+     * await live.toggleMicro(false)
+     * 
+     * // 检查权限
+     * if (live.selfInfo?.permission?.control_own_micro) {
+     *   await live.toggleMicro(true)
+     * } else {
+     *   console.log('没有权限控制麦克风')
+     * }
+     * ```
+     */
     a(this, "toggleMicro", async (e) => {
       var s, r, o;
       if (!((r = (s = this.selfInfo) == null ? void 0 : s.permission) != null && r.control_own_micro)) return !1;
       const n = await ((o = this.$RTC) == null ? void 0 : o.toggleMicro(e));
       return n && await this.updateStatus(
-        W.UserChange,
+        P.UserChange,
         z.UserMicroStatus,
         {
           status: e ? ot.OPEN : ot.CLOSE
@@ -5850,15 +6278,31 @@ class Ir extends At {
       ), n;
     });
     /**
-     * 控制别人的麦
-     * @param microStatus
-     * @param toUserIds
-     * @returns
+     * 控制其他用户的麦克风状态
+     * 
+     * 开启或关闭指定用户的麦克风。只有拥有 control_other_micro 权限的用户才能操作。
+     * 
+     * @param microStatus 麦克风状态（MicroStatus.OPEN 或 MicroStatus.CLOSE）
+     * @param toUserIds 目标用户ID，可以是单个字符串或字符串数组
+     * @returns Promise<boolean> 是否操作成功，无权限或权限检查失败返回 false
+     * @example
+     * ```typescript
+     * // 关闭某个用户的麦克风
+     * await live.forbidMicro(MicroStatus.CLOSE, 'user-id-1')
+     * 
+     * // 开启多个用户的麦克风
+     * await live.forbidMicro(MicroStatus.OPEN, ['user-id-1', 'user-id-2'])
+     * 
+     * // 检查权限
+     * if (live.selfInfo?.permission?.control_other_micro) {
+     *   await live.forbidMicro(MicroStatus.CLOSE, 'user-id-1')
+     * }
+     * ```
      */
     a(this, "forbidMicro", async (e, n) => {
       var s, r;
       return typeof this._options.canForbidUserMicro == "function" && !this._options.canForbidUserMicro(n) || !((r = (s = this.selfInfo) == null ? void 0 : s.permission) != null && r.control_other_micro) ? !1 : await this.updateStatus(
-        W.UserChange,
+        P.UserChange,
         z.UserMicroStatus,
         {
           status: e
@@ -5867,29 +6311,56 @@ class Ir extends At {
       );
     });
     /**
-     * 控制别人的同步全量帧数据权限
-     * @param sync
-     * @param toUserIds
-     * @returns
+     * 控制其他用户的帧数据同步权限
+     * 
+     * 允许或禁止指定用户同步全量帧数据。只有拥有 control_other_sync 权限的用户才能操作。
+     * 
+     * @param sync 是否允许同步，true 表示允许，false 表示禁止
+     * @param toUserIds 目标用户ID，可以是单个字符串或字符串数组
+     * @returns Promise<boolean> 是否操作成功，无权限或权限检查失败返回 false
+     * @example
+     * ```typescript
+     * // 禁止某个用户同步帧数据
+     * await live.forbidSync(false, 'user-id-1')
+     * 
+     * // 允许多个用户同步帧数据
+     * await live.forbidSync(true, ['user-id-1', 'user-id-2'])
+     * ```
      */
     a(this, "forbidSync", async (e, n) => {
       var s, r;
       return typeof this._options.canForbidUserSync == "function" && !this._options.canForbidUserSync(n) || !((r = (s = this.selfInfo) == null ? void 0 : s.permission) != null && r.control_other_sync) ? !1 : await this.updateStatus(
-        W.UserChange,
+        P.UserChange,
         z.UserPermission,
         { sync_frame: e },
         n
       );
     });
     /**
-     * 把用户踢出带看
-     * @param toUserIds
-     * @returns
+     * 将用户踢出带看房间
+     * 
+     * 强制将指定用户从房间中移除。只有拥有 change_other_status 权限的用户才能操作。
+     * 
+     * @param toUserIds 目标用户ID，可以是单个字符串或字符串数组
+     * @returns Promise<boolean> 是否操作成功，无权限或权限检查失败返回 false
+     * @example
+     * ```typescript
+     * // 踢出单个用户
+     * await live.kick('user-id-1')
+     * 
+     * // 踢出多个用户
+     * await live.kick(['user-id-1', 'user-id-2'])
+     * 
+     * // 检查权限
+     * if (live.selfInfo?.permission?.change_other_status) {
+     *   await live.kick('user-id-1')
+     * }
+     * ```
      */
     a(this, "kick", async (e) => {
       var n, s;
       return typeof this._options.canForbidUserKick == "function" && !this._options.canForbidUserKick(e) || !((s = (n = this.selfInfo) == null ? void 0 : n.permission) != null && s.change_other_status) ? !1 : await this.updateStatus(
-        W.UserChange,
+        P.UserChange,
         z.UserStatus,
         {
           status: "KICK_OUT"
@@ -5898,7 +6369,17 @@ class Ir extends At {
       );
     });
     /**
-     * 获取当前某个 keyframe 的数据快照
+     * 获取指定键的帧数据快照
+     * 
+     * 这是 getFramesByKey 方法的别名，用于保持 API 的一致性。
+     * 
+     * @template Key 帧数据的键类型
+     * @param key 帧数据的键值
+     * @returns 对应键的帧数据，如果不存在则返回 undefined
+     * @example
+     * ```typescript
+     * const cameraFrame = live.getSnapshotForKey('camera')
+     * ```
      */
     a(this, "getSnapshotForKey", (e) => this.snapshot[e]);
     m.info("Initializing Live instance with options:", e), this._addLiveControllerEventListeners(), this._yDoc = new Ct({
@@ -5907,11 +6388,16 @@ class Ir extends At {
       keyframes: this._yDoc.getMap("keyframes")
     }, this._initializeKeyframesObservers(), this._initializeOptions(e), this._autoConnect(), this._debugSetup();
   }
+  /**
+   * 获取带看的配置选项（只读）
+   * @returns 冻结的配置选项对象
+   */
   get options() {
     return Object.freeze(this._options || {});
   }
   /**
-   * 带看状态
+   * 获取当前带看连接状态
+   * @returns 当前连接状态
    */
   get state() {
     return this._controller.state;
@@ -5919,6 +6405,7 @@ class Ir extends At {
   /**
    * 兼容老逻辑
    * @deprecated 请直接读取 state 属性字段，未来将移除该属性
+   * @returns 当前连接状态
    */
   get readyState() {
     return this._controller.state;
@@ -5926,53 +6413,122 @@ class Ir extends At {
   /**
    * 获取当前WebSocket连接的URL。(注意：这个是WebSocket连接的完整连接，附带一些query参数)。
    * @deprecated 带看不需要关注底层ws的相关信息，未来将移除
+   * @returns WebSocket 连接 URL，如果未设置则返回 undefined
    */
   get url() {
     return this.options.url;
   }
   /**
-   * 获取当前live使用的RTC实例
+   * 获取当前 live 实例使用的 RTC 实例
+   * @returns RTC 协议实例，用于语音通信
    */
   get $RTC() {
     return this._options.rtc;
   }
   /**
-   * 获取当前live使用的jsBridge实例
+   * 获取当前 live 实例使用的 jsBridge 实例
+   * @returns JSBridge 协议实例，用于与原生 App 通信
    */
   get jsBridge() {
     return this._options.jsBridge;
   }
   /**
-   * 当前帧数据快照
+   * 获取当前所有帧数据的快照
+   * 
+   * @returns 当前帧数据的部分快照对象
+   * @example
+   * ```typescript
+   * const snapshot = live.snapshot
+   * console.log('当前相机位置:', snapshot.camera)
+   * console.log('当前标注:', snapshot.annotation)
+   * ```
    */
   get snapshot() {
     return this._buildInData.keyframes.toJSON();
   }
   /**
-   * 当前用户信息
+   * 获取当前用户信息
+   * 
+   * @returns 当前用户信息对象，如果尚未获取则返回 undefined
+   * @example
+   * ```typescript
+   * const selfInfo = live.selfInfo
+   * if (selfInfo) {
+   *   console.log('用户ID:', selfInfo.id)
+   *   console.log('麦克风状态:', selfInfo.micro_status)
+   *   console.log('用户权限:', selfInfo.permission)
+   * }
+   * ```
    */
   get selfInfo() {
     return this._buildInData.selfInfo;
   }
   /**
-   * 当前用户列表
+   * 获取当前房间内的用户列表
+   * 
+   * @returns 用户信息数组，如果尚未获取则返回空数组
+   * @example
+   * ```typescript
+   * const users = live.userList
+   * console.log(`房间内有 ${users.length} 个用户`)
+   * users.forEach(user => {
+   *   console.log(`用户 ${user.id} 在线状态: ${user.current_ws_online}`)
+   * })
+   * ```
    */
   get userList() {
     return this._buildInData.userList || [];
   }
   /**
-   * 当前带看房间信息
+   * 获取当前带看房间信息
+   * 
+   * @returns 房间信息对象，如果尚未获取则返回 undefined
+   * @example
+   * ```typescript
+   * const roomInfo = live.roomInfo
+   * if (roomInfo) {
+   *   console.log('房间代码:', roomInfo.info.room_code)
+   *   console.log('房间状态:', roomInfo.info.status)
+   * }
+   * ```
    */
   get roomInfo() {
     return this._buildInData.roomInfo;
   }
   /**
-   * 修改状态
-   * @param evtType
-   * @param atnType
-   * @param status
-   * @param toUserIds
-   * @returns
+   * 更新带看状态
+   * 
+   * 发送内置消息来更新用户或房间的状态。只有在连接状态为 OPEN 时才能发送。
+   * 
+   * @param evtType 事件类型（用户变化或房间变化）
+   * @param atnType 操作类型（如用户信息、麦克风状态、房间关闭等）
+   * @param status 状态数据对象
+   * @param toUserIds 目标用户ID（可选，不传则广播给所有人）
+   * @returns 是否发送成功，连接未打开或发送失败返回 false
+   * @example
+   * ```typescript
+   * // 更新用户信息
+   * await live.updateStatus(
+   *   BuiltinEventType.UserChange,
+   *   BuiltinActionType.UserInfo,
+   *   { nickname: '新昵称', avatar: 'https://example.com/avatar.jpg' }
+   * )
+   * 
+   * // 关闭房间（仅管理员可用）
+   * await live.updateStatus(
+   *   BuiltinEventType.RoomChange,
+   *   BuiltinActionType.RoomClose,
+   *   {}
+   * )
+   * 
+   * // 向特定用户发送状态更新
+   * await live.updateStatus(
+   *   BuiltinEventType.UserChange,
+   *   BuiltinActionType.UserMicroStatus,
+   *   { status: MicroStatus.CLOSE },
+   *   ['user-id-1', 'user-id-2']
+   * )
+   * ```
    */
   async updateStatus(e, n, s, r) {
     if (this.state !== j.OPEN) return !1;
@@ -5996,52 +6552,52 @@ function Nr(i) {
     return D.useEffect(() => (b.keyframes.on(f, C), T), I), T;
   }
   function d() {
-    const f = r(), C = P(
+    const f = r(), C = W(
       async (O) => {
         await f.connect(O);
       },
       [f]
-    ), R = P(
+    ), R = W(
       (O) => {
         f.toggleMicro(O);
       },
       [f]
-    ), b = P(
+    ), b = W(
       async (O, H, ce = 0) => {
         await f.broadcast(O, H, ce);
       },
       [f]
-    ), I = P(async () => {
+    ), I = W(async () => {
       await f.exit();
-    }, [f]), T = P(
+    }, [f]), T = W(
       async (O) => {
         await f.kick(O);
       },
       [f]
-    ), F = P(
+    ), F = W(
       async (O, H = []) => {
         await f.forbidMicro(O, H);
       },
       [f]
-    ), rt = P(
+    ), rt = W(
       (O, H = []) => {
         f.forbidSync(O, H);
       },
       [f]
-    ), oe = P(
+    ), oe = W(
       (O) => f.getFramesByKey(O),
       [f]
-    ), en = P(
+    ), en = W(
       (O, H) => {
         f.sendKeyframe(O, H);
       },
       [f]
-    ), nn = P(
+    ), nn = W(
       (O) => {
         f.setSelfInfo(O);
       },
       [f]
-    ), sn = P(
+    ), sn = W(
       (O, H, ce, rn) => {
         f.updateStatus(O, H, ce, rn);
       },
@@ -6139,15 +6695,15 @@ function Nr(i) {
 }
 const ye = globalThis.__REALSEE_LIVE_BADGE_LOG__;
 (ye == null || ye) && console.log(
-  "%c@realsee/live@0.7.3-alpha.0 (9/18/2025, 4:04:20 PM)",
+  "%c@realsee/live@0.7.4 (12/4/2025, 11:27:14 AM)",
   "background: linear-gradient(to right, #1890ff, #52c41a); color: white; padding: 3px 6px; border-radius: 4px; font-weight: bold; text-shadow: 0 1px 0 rgba(0,0,0,0.2);"
 );
 export {
   mn as BrowserRTC,
-  We as BrowserRTC4Chime,
+  Pe as BrowserRTC4Chime,
   fi as BuiltInRTCType,
   z as BuiltinActionType,
-  W as BuiltinEventType,
+  P as BuiltinEventType,
   B as Command,
   Re as CoreRTC,
   Ir as Live,
@@ -6156,6 +6712,7 @@ export {
   ot as MicroStatus,
   ht as RTCJoinedInfoCodeEnum,
   ct as RTCType,
+  At as Subscribe,
   yn as UserStatus,
   wn as VRWebViewRTC,
   Cn as WebSocketCloseError,