@spatialwalk/avatarkit 1.0.0-beta.68 → 1.0.0-beta.69

package/dist/{index-CF8Fvg7k.js → index-BT9yxWW8.js}

@@ -2,6 +2,12 @@ var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 class Avatar {
+  /**
+   * 构造函数（内部使用）
+   * @param id 数字人 ID
+   * @param characterMeta 角色元数据
+   * @param resources 资源数据
+   */
   constructor(id, characterMeta, resources) {
     __publicField(this, "id");
     __publicField(this, "characterMeta");
@@ -10,15 +16,27 @@ class Avatar {
     this.characterMeta = characterMeta;
     this.resources = resources;
   }
+  /**
+   * Get character metadata
+   * @returns Character metadata, including all configuration information (version, resource URLs, camera config, etc.)
+   */
   getCharacterMeta() {
     return this.characterMeta;
   }
+  /**
+   * 更新角色元数据（内部使用）
+   * @internal
+   */
   updateCharacterMeta(newMeta) {
     this.characterMeta = newMeta;
     if (this.resources.characterSettings !== newMeta.characterSettings) {
       this.resources.characterSettings = newMeta.characterSettings;
     }
   }
+  /**
+   * 获取资源数据（内部使用）
+   * @internal
+   */
   getResources() {
     return this.resources;
   }
@@ -346,6 +364,9 @@ class BinaryWriter {
     this.chunks = [];
     this.buf = [];
   }
+  /**
+   * Return all bytes written and reset this writer.
+   */
   finish() {
     if (this.buf.length) {
       this.chunks.push(new Uint8Array(this.buf));
@@ -363,12 +384,22 @@ class BinaryWriter {
     this.chunks = [];
     return bytes;
   }
+  /**
+   * Start a new fork for length-delimited data like a message
+   * or a packed repeated field.
+   *
+   * Must be joined later with `join()`.
+   */
   fork() {
     this.stack.push({ chunks: this.chunks, buf: this.buf });
     this.chunks = [];
     this.buf = [];
     return this;
   }
+  /**
+   * Join the last fork. Write its length and bytes, then
+   * return to the previous state.
+   */
   join() {
     let chunk = this.finish();
     let prev = this.stack.pop();
@@ -379,9 +410,19 @@ class BinaryWriter {
     this.uint32(chunk.byteLength);
     return this.raw(chunk);
   }
+  /**
+   * Writes a tag (field number and wire type).
+   *
+   * Equivalent to `uint32( (fieldNo << 3 | type) >>> 0 )`.
+   *
+   * Generated code should compute the tag ahead of time and call `uint32()`.
+   */
   tag(fieldNo, type) {
     return this.uint32((fieldNo << 3 | type) >>> 0);
   }
+  /**
+   * Write a chunk of raw bytes.
+   */
   raw(chunk) {
     if (this.buf.length) {
       this.chunks.push(new Uint8Array(this.buf));
@@ -390,6 +431,9 @@ class BinaryWriter {
     this.chunks.push(chunk);
     return this;
   }
+  /**
+   * Write a `uint32` value, an unsigned 32 bit varint.
+   */
   uint32(value) {
     assertUInt32(value);
     while (value > 127) {
@@ -399,75 +443,117 @@ class BinaryWriter {
     this.buf.push(value);
     return this;
   }
+  /**
+   * Write a `int32` value, a signed 32 bit varint.
+   */
   int32(value) {
     assertInt32(value);
     varint32write(value, this.buf);
     return this;
   }
+  /**
+   * Write a `bool` value, a variant.
+   */
   bool(value) {
     this.buf.push(value ? 1 : 0);
     return this;
   }
+  /**
+   * Write a `bytes` value, length-delimited arbitrary data.
+   */
   bytes(value) {
     this.uint32(value.byteLength);
     return this.raw(value);
   }
+  /**
+   * Write a `string` value, length-delimited data converted to UTF-8 text.
+   */
   string(value) {
     let chunk = this.encodeUtf8(value);
     this.uint32(chunk.byteLength);
     return this.raw(chunk);
   }
+  /**
+   * Write a `float` value, 32-bit floating point number.
+   */
   float(value) {
     assertFloat32(value);
     let chunk = new Uint8Array(4);
     new DataView(chunk.buffer).setFloat32(0, value, true);
     return this.raw(chunk);
   }
+  /**
+   * Write a `double` value, a 64-bit floating point number.
+   */
   double(value) {
     let chunk = new Uint8Array(8);
     new DataView(chunk.buffer).setFloat64(0, value, true);
     return this.raw(chunk);
   }
+  /**
+   * Write a `fixed32` value, an unsigned, fixed-length 32-bit integer.
+   */
   fixed32(value) {
     assertUInt32(value);
     let chunk = new Uint8Array(4);
     new DataView(chunk.buffer).setUint32(0, value, true);
     return this.raw(chunk);
   }
+  /**
+   * Write a `sfixed32` value, a signed, fixed-length 32-bit integer.
+   */
   sfixed32(value) {
     assertInt32(value);
     let chunk = new Uint8Array(4);
     new DataView(chunk.buffer).setInt32(0, value, true);
     return this.raw(chunk);
   }
+  /**
+   * Write a `sint32` value, a signed, zigzag-encoded 32-bit varint.
+   */
   sint32(value) {
     assertInt32(value);
     value = (value << 1 ^ value >> 31) >>> 0;
     varint32write(value, this.buf);
     return this;
   }
+  /**
+   * Write a `fixed64` value, a signed, fixed-length 64-bit integer.
+   */
   sfixed64(value) {
     let chunk = new Uint8Array(8), view = new DataView(chunk.buffer), tc = protoInt64.enc(value);
     view.setInt32(0, tc.lo, true);
     view.setInt32(4, tc.hi, true);
     return this.raw(chunk);
   }
+  /**
+   * Write a `fixed64` value, an unsigned, fixed-length 64 bit integer.
+   */
   fixed64(value) {
     let chunk = new Uint8Array(8), view = new DataView(chunk.buffer), tc = protoInt64.uEnc(value);
     view.setInt32(0, tc.lo, true);
     view.setInt32(4, tc.hi, true);
     return this.raw(chunk);
   }
+  /**
+   * Write a `int64` value, a signed 64-bit varint.
+   */
   int64(value) {
     let tc = protoInt64.enc(value);
     varint64write(tc.lo, tc.hi, this.buf);
     return this;
   }
+  /**
+   * Write a `sint64` value, a signed, zig-zag-encoded 64-bit varint.
+   */
   sint64(value) {
     const tc = protoInt64.enc(value), sign = tc.hi >> 31, lo2 = tc.lo << 1 ^ sign, hi2 = (tc.hi << 1 | tc.lo >>> 31) ^ sign;
     varint64write(lo2, hi2, this.buf);
     return this;
   }
+  /**
+   * Write a `uint64` value, an unsigned 64-bit varint.
+   */
   uint64(value) {
     const tc = protoInt64.uEnc(value);
     varint64write(tc.lo, tc.hi, this.buf);
@@ -484,12 +570,21 @@ class BinaryReader {
     this.pos = 0;
     this.view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
   }
+  /**
+   * Reads a tag - field number and wire type.
+   */
   tag() {
     let tag = this.uint32(), fieldNo = tag >>> 3, wireType = tag & 7;
     if (fieldNo <= 0 || wireType < 0 || wireType > 5)
       throw new Error("illegal tag: field no " + fieldNo + " wire type " + wireType);
     return [fieldNo, wireType];
   }
+  /**
+   * Skip one element and return the skipped data.
+   *
+   * When skipping StartGroup, provide the tags field number to check for
+   * matching field number in the EndGroup tag.
+   */
   skip(wireType, fieldNo) {
     let start = this.pos;
     switch (wireType) {
@@ -524,23 +619,41 @@ class BinaryReader {
     this.assertBounds();
     return this.buf.subarray(start, this.pos);
   }
+  /**
+   * Throws error if position in byte array is out of range.
+   */
   assertBounds() {
     if (this.pos > this.len)
       throw new RangeError("premature EOF");
   }
+  /**
+   * Read a `int32` field, a signed 32 bit varint.
+   */
   int32() {
     return this.uint32() | 0;
   }
+  /**
+   * Read a `sint32` field, a signed, zigzag-encoded 32-bit varint.
+   */
   sint32() {
     let zze = this.uint32();
     return zze >>> 1 ^ -(zze & 1);
   }
+  /**
+   * Read a `int64` field, a signed 64-bit varint.
+   */
   int64() {
     return protoInt64.dec(...this.varint64());
   }
+  /**
+   * Read a `uint64` field, an unsigned 64-bit varint.
+   */
   uint64() {
     return protoInt64.uDec(...this.varint64());
   }
+  /**
+   * Read a `sint64` field, a signed, zig-zag-encoded 64-bit varint.
+   */
   sint64() {
     let [lo2, hi2] = this.varint64();
     let s2 = -(lo2 & 1);
@@ -548,34 +661,61 @@ class BinaryReader {
     hi2 = hi2 >>> 1 ^ s2;
     return protoInt64.dec(lo2, hi2);
   }
+  /**
+   * Read a `bool` field, a variant.
+   */
   bool() {
     let [lo2, hi2] = this.varint64();
     return lo2 !== 0 || hi2 !== 0;
   }
+  /**
+   * Read a `fixed32` field, an unsigned, fixed-length 32-bit integer.
+   */
   fixed32() {
     return this.view.getUint32((this.pos += 4) - 4, true);
   }
+  /**
+   * Read a `sfixed32` field, a signed, fixed-length 32-bit integer.
+   */
   sfixed32() {
     return this.view.getInt32((this.pos += 4) - 4, true);
   }
+  /**
+   * Read a `fixed64` field, an unsigned, fixed-length 64 bit integer.
+   */
   fixed64() {
     return protoInt64.uDec(this.sfixed32(), this.sfixed32());
   }
+  /**
+   * Read a `fixed64` field, a signed, fixed-length 64-bit integer.
+   */
   sfixed64() {
     return protoInt64.dec(this.sfixed32(), this.sfixed32());
   }
+  /**
+   * Read a `float` field, 32-bit floating point number.
+   */
   float() {
     return this.view.getFloat32((this.pos += 4) - 4, true);
   }
+  /**
+   * Read a `double` field, a 64-bit floating point number.
+   */
   double() {
     return this.view.getFloat64((this.pos += 8) - 8, true);
   }
+  /**
+   * Read a `bytes` field, length-delimited arbitrary data.
+   */
   bytes() {
     let len = this.uint32(), start = this.pos;
     this.pos += len;
     this.assertBounds();
     return this.buf.subarray(start, start + len);
   }
+  /**
+   * Read a `string` field, length-delimited data converted to UTF-8 text.
+   */
   string() {
     return this.decodeUtf8(this.bytes());
   }
@@ -1266,6 +1406,7 @@ function getPostHogConfig(_environment) {
     host: POSTHOG_HOST_INTL,
     apiKey: POSTHOG_API_KEY_INTL,
     disableCompression: false
+    // 国外官方 PostHog 支持压缩，保持启用
   };
 }
 function hasDebugParam() {
@@ -1279,6 +1420,7 @@ function isDebugMode() {
   return hasDebugParam();
 }
 const APP_CONFIG = {
+  // Dynamic debug mode check (includes URL parameter)
   get debug() {
     return isDebugMode();
   },
@@ -1291,10 +1433,14 @@ const APP_CONFIG = {
   },
   animation: {
     fps: 25
+    // 动画帧率（从 CharacterMeta 加载动画资源）
   },
   audio: {
     sampleRate: 16e3
+    // 音频采样率（后端要求 16kHz）
   },
+  // FLAME 全局模板资源 CDN
+  // 这些资源是所有角色共享的基础模板
   flame: {
     cdnBaseUrl: "https://cdn.spatialwalk.top/public",
     resources: {
@@ -1316,6 +1462,7 @@ function convertProtoFlameToWasmParams(protoFlame) {
     eyelid: protoFlame.eyeLid || [0, 0],
     expr_params: protoFlame.expression || [],
     shape_params: [],
+    // Realtime doesn't provide shape params, use default
     has_eyelid: (((_a = protoFlame.eyeLid) == null ? void 0 : _a.length) || 0) > 0
   };
 }
@@ -5965,6 +6112,12 @@ function requireStackframe() {
     var CHROME_IE_STACK_REGEXP = /^\s*at .*(\S+:\d+|\(native\))/m;
     var SAFARI_NATIVE_CODE_REGEXP = /^(eval@)?(\[native code])?$/;
     return {
+      /**
+       * Given an Error object, extract the most information from it.
+       *
+       * @param {Error} error object
+       * @return {Array} of StackFrames
+       */
       parse: function ErrorStackParser$$parse(error) {
         if (typeof error.stacktrace !== "undefined" || typeof error["opera#sourceloc"] !== "undefined") {
           return this.parseOpera(error);
@@ -5976,6 +6129,7 @@ function requireStackframe() {
           throw new Error("Cannot parse given Error object");
         }
       },
+      // Separate line and column numbers from a string of the form: (URI:Line:Column)
       extractLocation: function ErrorStackParser$$extractLocation(urlLike) {
         if (urlLike.indexOf(":") === -1) {
           return [urlLike];
@@ -6078,6 +6232,7 @@ function requireStackframe() {
         }
         return result2;
       },
+      // Opera 10.65+ Error.stack very similar to FF/Safari
       parseOpera11: function ErrorStackParser$$parseOpera11(error) {
         var filtered = error.stack.split("\n").filter(function(line) {
           return !!line.match(FIREFOX_SAFARI_STACK_REGEXP) && !line.match(/^Error created at/);
@@ -6964,6 +7119,7 @@ function createLogg(context) {
         column: stacks[0].column
       });
     },
+    // Placeholder implementations, will be overridden below
     debug: () => {
     },
     verbose: () => {
@@ -6976,6 +7132,7 @@ function createLogg(context) {
     },
     warn: () => {
     },
+    // TODO: remove in next major release
     withTimeFormat: (_2) => {
       const logger2 = logObj.child();
       return logger2;
@@ -7115,10 +7272,22 @@ var ResourceType = /* @__PURE__ */ ((ResourceType2) => {
 function extractResourceUrls(meta) {
   var _a, _b, _c, _d, _e2, _f, _g, _h, _i2, _j, _k;
   return {
-    ["camera"]: ((_b = (_a = meta.camera) == null ? void 0 : _a.resource) == null ? void 0 : _b.remote) || null,
-    ["frameIdle"]: ((_e2 = (_d = (_c = meta.animations) == null ? void 0 : _c.frameIdle) == null ? void 0 : _d.resource) == null ? void 0 : _e2.remote) || null,
-    ["shape"]: ((_h = (_g = (_f = meta.models) == null ? void 0 : _f.shape) == null ? void 0 : _g.resource) == null ? void 0 : _h.remote) || null,
-    ["gsStandard"]: ((_k = (_j = (_i2 = meta.models) == null ? void 0 : _i2.gsStandard) == null ? void 0 : _j.resource) == null ? void 0 : _k.remote) || null
+    [
+      "camera"
+      /* CAMERA */
+    ]: ((_b = (_a = meta.camera) == null ? void 0 : _a.resource) == null ? void 0 : _b.remote) || null,
+    [
+      "frameIdle"
+      /* ANIMATION_IDLE */
+    ]: ((_e2 = (_d = (_c = meta.animations) == null ? void 0 : _c.frameIdle) == null ? void 0 : _d.resource) == null ? void 0 : _e2.remote) || null,
+    [
+      "shape"
+      /* MODEL_SHAPE */
+    ]: ((_h = (_g = (_f = meta.models) == null ? void 0 : _f.shape) == null ? void 0 : _g.resource) == null ? void 0 : _h.remote) || null,
+    [
+      "gsStandard"
+      /* MODEL_GS */
+    ]: ((_k = (_j = (_i2 = meta.models) == null ? void 0 : _i2.gsStandard) == null ? void 0 : _j.resource) == null ? void 0 : _k.remote) || null
   };
 }
 var Environment = /* @__PURE__ */ ((Environment2) => {
@@ -7313,6 +7482,7 @@ class IdManager {
     });
     this.ids.clientId = getOrCreateClientId();
   }
+  // ========== 全局 ID ==========
   getClientId() {
     return this.ids.clientId;
   }
@@ -7334,10 +7504,17 @@ class IdManager {
   getSessionToken() {
     return this.ids.sessionToken;
   }
+  // ========== 连接级别 ID ==========
+  /**
+   * 生成新的 connectionId（用于 WebSocket 连接）
+   */
   generateConnectionId() {
     this.ids.connectionId = generateConversationId();
     return this.ids.connectionId;
   }
+  /**
+   * 设置 connectionId（用于从服务器接收到的 connectionId）
+   */
   setConnectionId(connectionId) {
     this.ids.connectionId = connectionId;
   }
@@ -7347,6 +7524,10 @@ class IdManager {
   clearConnectionId() {
     this.ids.connectionId = null;
   }
+  // ========== 会话级别 ID ==========
+  /**
+   * 生成新的 conversationId（用于每次对话）
+   */
   generateNewConversationId() {
     this.ids.conversationId = generateConversationId();
     return this.ids.conversationId;
@@ -7360,9 +7541,16 @@ class IdManager {
   clearConversationId() {
     this.ids.conversationId = null;
   }
+  // ========== 批量获取（用于 PostHog 日志）==========
+  /**
+   * 获取所有 ID（用于日志上报）
+   */
   getAllIds() {
     return { ...this.ids };
   }
+  /**
+   * 获取公共日志参数（包含所有必要的 ID）
+   */
   getLogContext() {
     return {
       client_id: this.ids.clientId,
@@ -7372,6 +7560,9 @@ class IdManager {
       ...this.ids.conversationId && { conversation_id: this.ids.conversationId }
     };
   }
+  /**
+   * 清理所有 ID（用于测试或重置）
+   */
   clear() {
     this.ids.userId = null;
     this.ids.appId = null;
@@ -7413,10 +7604,15 @@ function initializePostHog(environment, version) {
       api_host: host,
       person_profiles: "identified_only",
       capture_pageview: false,
+      // SDK 不需要自动捕获页面浏览
       capture_pageleave: false,
+      // SDK 不需要自动捕获页面离开
       disable_compression: disableCompression,
+      // 根据环境配置压缩：国内禁用，国外启用
       disable_session_recording: true,
+      // 禁用 Session Recording，避免额外的请求和错误
       autocapture: false,
+      // 禁用自动捕获，只上报 SDK 自定义事件
       loaded: (posthogInstance) => {
         logger.log(`[PostHog] Initialized successfully - environment: ${environment}, host: ${host}, instance: ${SDK_POSTHOG_INSTANCE_NAME}`);
         isInitialized = true;
@@ -7502,15 +7698,19 @@ function trackEvent(event, level = "info", contents = {}) {
   try {
     const logContext = idManager.getLogContext();
     const properties = {
+      // 基础属性
       service_module: "sdk",
       platform: "Web",
       sdk_version: sdkVersion,
       level,
       environment: currentEnvironment || "unknown",
+      // ID 信息
       app_id: logContext.app_id,
       user_id: logContext.user_id,
       client_id: logContext.client_id,
+      // 时间戳
       timestamp: Date.now(),
+      // 自定义内容
       ...contents
     };
     if (logContext.connection_id) {
@@ -7572,6 +7772,10 @@ const _AnimationPlayer = class _AnimationPlayer {
     __publicField(this, "onEndedCallback");
     __publicField(this, "useStreaming", false);
   }
+  /**
+   * 解锁音频上下文（Safari 自动播放策略）
+   * 必须在用户交互事件（如 click）中调用
+   */
   static async unlockAudioContext() {
     if (_AnimationPlayer.audioUnlocked) {
       return;
@@ -7589,6 +7793,9 @@ const _AnimationPlayer = class _AnimationPlayer {
       logger.warn("⚠️ Failed to unlock audio context:", err);
     }
   }
+  /**
+   * Initialize with HTMLAudioElement (traditional way)
+   */
   async initialize(audioUrl, onEnded) {
     this.onEndedCallback = onEnded;
     this.useStreaming = false;
@@ -7604,6 +7811,10 @@ const _AnimationPlayer = class _AnimationPlayer {
       this.audio.load();
     });
   }
+  /**
+   * Initialize with StreamingAudioPlayer (streaming way)
+   * @deprecated 使用 prepareStreamingPlayer() 代替
+   */
   async initializeStreaming(streamingPlayer, onEnded) {
     this.streamingPlayer = streamingPlayer;
     this.onEndedCallback = onEnded;
@@ -7614,17 +7825,27 @@ const _AnimationPlayer = class _AnimationPlayer {
       (_a = this.onEndedCallback) == null ? void 0 : _a.call(this);
     });
   }
+  /**
+   * 检查流式播放器是否已准备好
+   */
   isStreamingReady() {
     return this.useStreaming && this.streamingPlayer !== null;
   }
+  /**
+   * 获取流式播放器实例
+   */
   getStreamingPlayer() {
     return this.streamingPlayer;
   }
+  /**
+   * 创建并初始化流式播放器
+   * 在服务连接建立时调用
+   */
   async createAndInitializeStreamingPlayer() {
     if (this.streamingPlayer) {
       return;
     }
-    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-DrTBMLSq.js");
+    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-DiIRp5nx.js");
     const { AvatarSDK: AvatarSDK2 } = await Promise.resolve().then(() => AvatarSDK$1);
     const audioFormat = AvatarSDK2.getAudioFormat();
     this.streamingPlayer = new StreamingAudioPlayer({
@@ -7645,6 +7866,10 @@ const _AnimationPlayer = class _AnimationPlayer {
     }
     this.useStreaming = true;
   }
+  /**
+   * 准备流式播放器（如果未创建则创建并初始化）
+   * 停止之前的播放并更新结束回调
+   */
   async prepareStreamingPlayer(onEnded) {
     if (!this.streamingPlayer) {
       await this.createAndInitializeStreamingPlayer();
@@ -7705,6 +7930,9 @@ const _AnimationPlayer = class _AnimationPlayer {
     const currentTime = this.getCurrentTime();
     return Math.floor(currentTime * this.fps);
   }
+  /**
+   * Get current playback time
+   */
   getCurrentTime() {
     var _a, _b;
     if (this.useStreaming) {
@@ -7712,6 +7940,9 @@ const _AnimationPlayer = class _AnimationPlayer {
     }
     return ((_b = this.audio) == null ? void 0 : _b.currentTime) ?? 0;
   }
+  /**
+   * 添加音频块（仅用于流式播放）
+   */
   addAudioChunk(audio, isLast = false) {
     if (this.useStreaming && this.streamingPlayer) {
       this.streamingPlayer.addChunk(audio, isLast);
@@ -7719,6 +7950,9 @@ const _AnimationPlayer = class _AnimationPlayer {
       logger.warn("[AnimationPlayer] Cannot add audio chunk - streaming player not ready");
     }
   }
+  /**
+   * 暂停播放
+   */
   pause() {
     var _a;
     if (this.useStreaming) {
@@ -7729,6 +7963,9 @@ const _AnimationPlayer = class _AnimationPlayer {
       }
     }
   }
+  /**
+   * 继续播放
+   */
   async resume() {
     var _a;
     if (this.useStreaming) {
@@ -7739,6 +7976,11 @@ const _AnimationPlayer = class _AnimationPlayer {
       }
     }
   }
+  /**
+   * 设置音量 (0.0 - 1.0)
+   * 注意：这仅控制数字人音频播放器的音量，不影响系统音量
+   * @param volume 音量值，范围 0.0 到 1.0（0.0 为静音，1.0 为最大音量）
+   */
   setVolume(volume) {
     if (this.useStreaming && this.streamingPlayer) {
       this.streamingPlayer.setVolume(volume);
@@ -7748,6 +7990,10 @@ const _AnimationPlayer = class _AnimationPlayer {
       }
     }
   }
+  /**
+   * 获取当前音量
+   * @returns 当前音量值 (0.0 - 1.0)
+   */
   getVolume() {
     var _a;
     if (this.useStreaming && this.streamingPlayer) {
@@ -7793,6 +8039,7 @@ async function fetchSdkConfig(version) {
       logger.log(`[SdkConfigLoader] Fetching SDK config from: ${configUrl}`);
       const response = await fetch(configUrl, {
         method: "GET"
+        // GET 请求不需要 Content-Type header，避免触发 CORS 预检
       });
       if (!response.ok) {
         throw new Error(`HTTP ${response.status} ${response.statusText}`);
@@ -7852,6 +8099,9 @@ class AvatarCoreMemoryManager {
     this.allocatedPointers = /* @__PURE__ */ new Set();
     this.structPointers = /* @__PURE__ */ new Map();
   }
+  /**
+   * 分配 WASM 内存并复制数据 - 纯 API 方式
+   */
   allocateAndCopy(arrayBuffer) {
     const size = arrayBuffer.byteLength;
     const ptr = this.module._malloc(size);
@@ -7863,6 +8113,9 @@ class AvatarCoreMemoryManager {
     this.allocatedPointers.add(ptr);
     return { ptr, size };
   }
+  /**
+   * 创建 AvatarTemplateConfig 结构体
+   */
   createTemplateConfig(resources) {
     const structSize = 10 * 4;
     const configPtr = this.module._malloc(structSize);
@@ -7909,6 +8162,9 @@ class AvatarCoreMemoryManager {
     this.structPointers.set("template_config", configPtr);
     return configPtr;
   }
+  /**
+   * 创建 AvatarCharacterData 结构体 - 新版 Emscripten 方式
+   */
   createCharacterData(shapeBuffer, plyBuffer, characterId) {
     const structSize = 4 * 4;
     const dataPtr = this.module._malloc(structSize);
@@ -7930,6 +8186,10 @@ class AvatarCoreMemoryManager {
     this.structPointers.set(key, dataPtr);
     return { dataPtr, shapePtr: shape.ptr, plyPtr: ply.ptr };
   }
+  /**
+   * 读取 AvatarFlameParams 结构体数据
+   * Used to extract current animation frame parameters from WASM memory
+   */
   readFlameParams(paramsPtr) {
     let byteOffset = 0;
     const shape_params = [];
@@ -7985,6 +8245,9 @@ class AvatarCoreMemoryManager {
       has_eyelid
     };
   }
+  /**
+   * 创建 AvatarFlameParams 结构体 - 新版 Emscripten 方式
+   */
   createFlameParams(params) {
     var _a, _b, _c, _d, _e2, _f, _g, _h;
     const structSize = (300 + 100 + 3 + 3 + 3 + 3 + 6 + 2 + 1) * 4;
@@ -8037,6 +8300,21 @@ class AvatarCoreMemoryManager {
     byteOffset += 4;
     return paramsPtr;
   }
+  /**
+   * 读取 AvatarSplatPointFlatArray 结构体数据（预计算协方差）
+   *
+   * 结构体布局:
+   * - AvatarSplatPointFlat* points (0-3, 32位指针)
+   * - uint32_t point_count (4-7)
+   * - float compute_time_ms (8-11)
+   *
+   * 每个点布局 (52 bytes):
+   * - position[3]   (12 bytes)
+   * - color[4]      (16 bytes, RGBA)
+   * - covariance[6] (24 bytes, 预计算好的协方差矩阵上三角)
+   *
+   * ⚠️ 使用 getValue 逐个读取，避免动态内存的 HEAPF32 detachment 问题
+   */
   readSplatPointFlatArray(arrayPtr) {
     if (!arrayPtr) {
       throw new Error("Invalid array pointer");
@@ -8053,6 +8331,9 @@ class AvatarCoreMemoryManager {
     flatData.set(this.module.HEAPF32.subarray(floatOffset, floatOffset + totalFloats));
     return flatData;
   }
+  /**
+   * 读取AvatarMeshData结构体数据
+   */
   readMeshData(outputPtr) {
     const verticesPtr = this.module.getValue(outputPtr + 0, "*");
     const vertexCount = this.module.getValue(outputPtr + 4, "i32");
@@ -8090,12 +8371,18 @@ class AvatarCoreMemoryManager {
       computeTime
     };
   }
+  /**
+   * 释放指定指针的内存
+   */
   free(ptr) {
     if (ptr && this.allocatedPointers.has(ptr)) {
       this.module._free(ptr);
       this.allocatedPointers.delete(ptr);
     }
   }
+  /**
+   * 释放结构体内存
+   */
   freeStruct(name) {
     const ptr = this.structPointers.get(name);
     if (ptr) {
@@ -8103,6 +8390,9 @@ class AvatarCoreMemoryManager {
       this.structPointers.delete(name);
     }
   }
+  /**
+   * 清理所有分配的内存
+   */
   cleanup() {
     for (const ptr of this.allocatedPointers) {
       this.module._free(ptr);
@@ -8113,6 +8403,9 @@ class AvatarCoreMemoryManager {
     }
     this.structPointers.clear();
   }
+  /**
+   * 获取内存使用统计
+   */
   getMemoryStats() {
     return {
       allocatedPointers: this.allocatedPointers.size,
@@ -8123,22 +8416,36 @@ class AvatarCoreMemoryManager {
 }
 class AvatarCoreAdapter {
   constructor(options = {}) {
+    // 配置
     __publicField(this, "options");
     __publicField(this, "wasmConfig");
+    // 核心组件
+    // eslint-disable-next-line ts/no-explicit-any
     __publicField(this, "wasmModule");
     __publicField(this, "memoryManager");
+    // Avatar Core handles
     __publicField(this, "coreHandle");
+    // Support multiple character handles (key: characterId, value: handle)
     __publicField(this, "characterHandles", /* @__PURE__ */ new Map());
+    // Animation handles per character (key: characterId, value: { handle, totalFrames })
     __publicField(this, "animationHandles", /* @__PURE__ */ new Map());
+    // Legacy single character support (deprecated, kept for backward compatibility)
     __publicField(this, "characterHandle");
     __publicField(this, "animationHandle");
     __publicField(this, "totalFrames");
+    // 状态管理
     __publicField(this, "isInitialized");
     __publicField(this, "isCharacterLoaded");
+    // C API 函数包装
+    // eslint-disable-next-line ts/no-explicit-any
     __publicField(this, "api");
+    // 性能监控
     __publicField(this, "performanceMetrics");
     __publicField(this, "wasmTime", 0);
+    // 最近一次 WASM 计算耗时
+    // 错误码映射
     __publicField(this, "errorCodes");
+    // 模型信息
     __publicField(this, "flameInfo");
     __publicField(this, "characterInfo");
     this.options = {
@@ -8178,6 +8485,19 @@ class AvatarCoreAdapter {
       6: "AVATAR_ERROR_COMPUTATION_FAILED"
     };
   }
+  /**
+   * 加载 WASM 模块并设置 API
+   * 每次都创建全新的 WASM 实例，确保 C++ 内存是干净的
+   * 
+   * 注意：这里使用动态 import() 导入 WASM 模块。
+   * Vite 在构建时会自动为 WASM 文件和 JS glue 代码添加 hash（如 avatar_core_wasm-CxWuw7eS.wasm），
+   * 确保浏览器缓存与版本一致，不会有缓存问题。
+   * 
+   * Hash 的作用机制：
+   * - WASM 文件内容变化 → hash 自动变化 → URL 变化 → 浏览器拉取新版本
+   * - WASM 文件内容不变 → hash 保持不变 → URL 不变 → 浏览器使用缓存
+   * - Emscripten 生成的 JS 内部会使用 hard-coded 的 hash 路径加载 .wasm 文件
+   */
   async loadWASMModule() {
     try {
       const { default: AvatarCoreModule } = await import("./avatar_core_wasm-Dv943JJl.js");
@@ -8195,6 +8515,9 @@ class AvatarCoreAdapter {
       throw new Error(`Failed to load WASM module: ${errorMessage}`);
     }
   }
+  /**
+   * 验证 WASM 模块功能
+   */
   validateWASMModule() {
     const requiredFunctions = ["cwrap", "_malloc", "_free", "setValue", "getValue", "writeArrayToMemory"];
     for (const funcName of requiredFunctions) {
@@ -8204,6 +8527,9 @@ class AvatarCoreAdapter {
     }
     this.initializeMemoryViews();
   }
+  /**
+   * 初始化内存视图
+   */
   initializeMemoryViews() {
     try {
       const testPtr = this.wasmModule._malloc(4);
@@ -8222,32 +8548,57 @@ class AvatarCoreAdapter {
       throw new Error(`Memory system initialization failed: ${errorMessage}`);
     }
   }
+  /**
+   * 设置 C API 函数包装
+   */
   setupCAPIFunctions() {
     this.api = {
+      // 核心系统管理
       initialize: this.wasmModule.cwrap("avatar_core_initialize", "number", ["number"]),
+      // 返回 handle
       release: this.wasmModule.cwrap("avatar_core_release", null, ["number"]),
       getVersion: this.wasmModule.cwrap("avatar_core_get_version", "string", []),
       getErrorString: this.wasmModule.cwrap("avatar_core_get_error_string", "string", ["number"]),
       resetProcessorForReuse: this.wasmModule.cwrap("avatar_core_reset_processor_for_reuse", null, ["number"]),
+      // 角色管理
       loadCharacter: this.wasmModule.cwrap("avatar_core_load_character", "number", ["number", "number"]),
+      // 返回 handle
       removeCharacter: this.wasmModule.cwrap("avatar_core_remove_character", null, ["number", "number"]),
       getCharacterInfo: this.wasmModule.cwrap("avatar_core_get_character_info", "number", ["number", "number", "number"]),
       getCharacterShapeParams: this.wasmModule.cwrap("avatar_core_get_character_shape_params", "number", ["number", "number"]),
+      // characterHandle, outputPtr
+      // 动画管理
       loadAnimation: this.wasmModule.cwrap("avatar_core_load_animation", "number", ["number", "number"]),
       parseAnimationFramesFromFile: this.wasmModule.cwrap("avatar_core_parse_animation_frames_from_file", "number", ["number", "number", "number"]),
       getAnimationFrameCount: this.wasmModule.cwrap("avatar_core_get_animation_frame_count", "number", ["number", "number"]),
       getFrameFromAnimation: this.wasmModule.cwrap("avatar_core_get_frame_from_animation", "number", ["number", "number", "number"]),
       removeAnimation: this.wasmModule.cwrap("avatar_core_remove_animation", null, ["number", "number"]),
+      // 帧计算 (Flat 格式 - GPU 优化版本，协方差预计算)
       computeFrameFlat: this.wasmModule.cwrap("avatar_core_compute_frame_as_splat_points_flat", "number", ["number", "number", "number", "number"]),
+      // 返回错误码
       freeSplatPointsFlat: this.wasmModule.cwrap("avatar_core_free_splat_points_flat", null, ["number"]),
+      // Mesh 计算（用于传统 mesh 渲染）
       computeFrameAsMesh: this.wasmModule.cwrap("avatar_core_compute_frame_as_mesh", "number", ["number", "number", "number", "number"]),
+      // 返回错误码
       freeMeshData: this.wasmModule.cwrap("avatar_core_free_mesh_data", null, ["number"]),
+      // 眼部追踪（高级功能）
       setEyeTrackingConfig: this.wasmModule.cwrap("avatar_core_set_eye_tracking_config", "number", ["number", "number", "number"]),
+      // core, character, config
       setGazeTarget: this.wasmModule.cwrap("avatar_core_set_gaze_target", "number", ["number", "number", "number", "number", "number"]),
+      // core, character, x, y, z
       resetEyeTracking: this.wasmModule.cwrap("avatar_core_reset_eye_tracking", "number", ["number"]),
+      // FLAME 信息查询
       getFlameInfo: this.wasmModule.cwrap("avatar_core_get_flame_info", "number", ["number", "number", "number", "number"])
     };
   }
+  /**
+   * 读取当前动画帧的 FlameParams（用于过渡或调试）
+   */
+  /**
+   * Get current frame parameters
+   * @param frameIndex Frame index
+   * @param characterId Optional character ID for multi-character support
+   */
   async getCurrentFrameParams(frameIndex = 0, characterId) {
     const paramsPtr = await this.getAnimationFrameParams(frameIndex, characterId);
     try {
@@ -8257,6 +8608,9 @@ class AvatarCoreAdapter {
       this.wasmModule._free(paramsPtr);
     }
   }
+  /**
+   * 初始化 Avatar Core 核心
+   */
   async initializeAvatarCore(templateResources) {
     try {
       const configPtr = this.memoryManager.createTemplateConfig(templateResources);
@@ -8271,6 +8625,9 @@ class AvatarCoreAdapter {
       throw new Error(`Failed to initialize Avatar Core: ${errorMessage}`);
     }
   }
+  /**
+   * 加载模板资源（从预加载的 ArrayBuffers）
+   */
   async loadTemplateResourcesFromBuffers(templateResources) {
     const formattedResources = {
       flameModel: templateResources.flameModel || templateResources["model.pb"] || new ArrayBuffer(0),
@@ -8294,6 +8651,16 @@ class AvatarCoreAdapter {
       throw new Error(`Template resources loading failed: ${errorMessage}`);
     }
   }
+  /**
+   * 加载角色数据（从预加载的 ArrayBuffers）
+   */
+  /**
+   * Load character from buffers and return handle
+   * @param shapeBuffer Shape data buffer
+   * @param pointCloudBuffer Point cloud data buffer
+   * @param characterId Optional character ID for multi-character support
+   * @returns Character handle
+   */
   async loadCharacterFromBuffers(shapeBuffer, pointCloudBuffer, characterId) {
     if (!this.isInitialized) {
       throw new Error("Avatar Core not initialized");
@@ -8347,6 +8714,12 @@ class AvatarCoreAdapter {
     }
     return handle;
   }
+  /**
+   * Load animation from ArrayBuffer (for CDN-based dynamic loading)
+   * @param animData Animation data buffer
+   * @param characterId Optional character ID for multi-character support
+   * @returns Animation handle
+   */
   async loadAnimationFromBuffer(animData, characterId) {
     if (!this.isInitialized) {
       throw new Error("Avatar Core not initialized");
@@ -8388,6 +8761,10 @@ class AvatarCoreAdapter {
       throw new Error(`Failed to switch animation: ${errorMessage}`);
     }
   }
+  /**
+   * 获取动画总帧数
+   * @param animationHandle Optional animation handle (for multi-character support)
+   */
   async getAnimationTotalFrames(animationHandle) {
     const handle = animationHandle || this.animationHandle;
     if (!handle) {
@@ -8413,6 +8790,11 @@ class AvatarCoreAdapter {
       throw new Error(`Failed to get animation frame count: ${errorMessage}`);
     }
   }
+  /**
+   * 从动画中获取指定帧的参数
+   * @param frameIndex Frame index
+   * @param characterId Optional character ID for multi-character support
+   */
   async getAnimationFrameParams(frameIndex = 0, characterId) {
     const id = characterId || "default";
     const animInfo = this.animationHandles.get(id);
@@ -8449,6 +8831,11 @@ class AvatarCoreAdapter {
       throw new Error(`Failed to get animation frame ${frameIndex}: ${errorMessage}`);
     }
   }
+  /**
+   * 设置眼部追踪配置（对齐 app 实现）
+   * @param config Eye tracking configuration
+   * @param characterId Optional character ID for multi-character support
+   */
   async setEyeTrackingConfig(config, characterId) {
     if (!this.isCharacterLoaded) {
       throw new Error("Character not loaded");
@@ -8473,6 +8860,13 @@ class AvatarCoreAdapter {
       throw new Error(`Failed to set eye tracking config: ${errorMessage}`);
     }
   }
+  /**
+   * 设置眼部追踪目标（高级功能）
+   * @param x Target X coordinate
+   * @param y Target Y coordinate
+   * @param z Target Z coordinate
+   * @param characterId Optional character ID for multi-character support
+   */
   async setGazeTarget(x2, y2, z2, characterId) {
     if (!this.isCharacterLoaded) {
       throw new Error("Character not loaded");
@@ -8492,6 +8886,9 @@ class AvatarCoreAdapter {
       throw new Error(`Failed to set gaze target: ${errorMessage}`);
     }
   }
+  /**
+   * 重置眼部追踪
+   */
   async resetEyeTracking() {
     if (!this.isCharacterLoaded) {
       throw new Error("Character not loaded");
@@ -8506,6 +8903,9 @@ class AvatarCoreAdapter {
       throw new Error(`Failed to reset eye tracking: ${errorMessage}`);
     }
   }
+  /**
+   * 查询 FLAME 模型信息
+   */
   async queryFlameInfo() {
     try {
       const vertexCountPtr = this.wasmModule._malloc(4);
@@ -8530,6 +8930,9 @@ class AvatarCoreAdapter {
       logger.errorWithError("Failed to query model info:", errorMessage);
     }
   }
+  /**
+   * 查询角色信息
+   */
   async queryCharacterInfo() {
     try {
       const pointCountPtr = this.wasmModule._malloc(4);
@@ -8550,6 +8953,9 @@ class AvatarCoreAdapter {
       logger.errorWithError("❌ Failed to query character info:", errorMessage);
     }
   }
+  /**
+   * 检查错误码并抛出异常
+   */
   checkError(errorCode, functionName) {
     if (errorCode !== 0) {
       const errorName = this.errorCodes[errorCode] || `UNKNOWN_ERROR_${errorCode}`;
@@ -8558,11 +8964,17 @@ class AvatarCoreAdapter {
       throw new Error(`${functionName} failed: ${errorName} - ${errorMessage}`);
     }
   }
+  /**
+   * 更新进度回调
+   */
   async updateProgress(callback, message, progress) {
     if (callback && typeof callback === "function") {
       callback({ message, progress });
     }
   }
+  /**
+   * 获取性能指标
+   */
   getPerformanceMetrics() {
     var _a, _b;
     return {
@@ -8572,6 +8984,11 @@ class AvatarCoreAdapter {
       version: ((_b = (_a = this.api).getVersion) == null ? void 0 : _b.call(_a)) || "unknown"
     };
   }
+  /**
+   * 获取角色的点云数量
+   * @param characterHandle 角色 handle（可选，默认使用当前角色）
+   * @returns 点云数量，如果角色未加载则返回 null
+   */
   getPointCount(characterHandle) {
     if (!this.isCharacterLoaded) {
       return null;
@@ -8598,6 +9015,14 @@ class AvatarCoreAdapter {
       return null;
     }
   }
+  /**
+   * 释放当前角色和动画资源（但保留 core）
+   */
+  /**
+   * Remove a specific character by handle
+   * @param characterHandle Character handle to remove
+   * @param characterId Optional character ID for cleanup
+   */
   removeCharacter(characterHandle, characterId) {
     try {
       if (!this.coreHandle) {
@@ -8621,11 +9046,18 @@ class AvatarCoreAdapter {
       logger.errorWithError("❌ Failed to remove character:", error);
     }
   }
+  /**
+   * Release current character (legacy method, kept for backward compatibility)
+   * @deprecated Use removeCharacter() instead for multi-character support
+   */
   releaseCurrentCharacter() {
     if (this.characterHandle) {
       this.removeCharacter(this.characterHandle);
     }
   }
+  /**
+   * 释放所有资源（包括 core）
+   */
   release() {
     try {
       this.releaseCurrentCharacter();
@@ -8648,12 +9080,31 @@ class AvatarCoreAdapter {
       logger.errorWithError("❌ Failed to release resources:", error);
     }
   }
+  /**
+   * 兼容性接口：提供与 FlameComplete3DGSManager 相同的接口
+   */
+  // 兼容 loadFlameModel
+  // eslint-disable-next-line ts/no-explicit-any
   async loadFlameModel(_modelData) {
     return true;
   }
+  // 兼容 load3DGSData
+  // eslint-disable-next-line ts/no-explicit-any
   async load3DGSData(_original3DGSPoints, _binding, _flameFaces) {
     return true;
   }
+  /**
+   * 计算帧并返回 GPU 友好的 flat 格式（零拷贝，协方差预计算）
+   * 🚀 性能优化版本：
+   * - C++ 预计算协方差矩阵
+   * - 零拷贝直接访问 WASM 内存http://localhost:3000/us/
+   * - 直接输出 GPU 格式 [pos3, color4, cov6]
+   */
+  /**
+   * Compute complete frame from animation
+   * @param params Frame parameters
+   * @param characterHandle Optional character handle (for multi-character support)
+   */
   async computeCompleteFrameFlat(params, characterHandle) {
     if (!this.isCharacterLoaded) {
       throw new Error("Character not loaded");
@@ -8709,6 +9160,15 @@ class AvatarCoreAdapter {
       }
     }
   }
+  /**
+   * 计算帧并返回 GPU 友好的 flat 格式（从 FLAME 参数）
+   * 🔑 用于 Realtime: 接受自定义 FLAME 参数并计算 Splat
+   */
+  /**
+   * Compute frame from Flame parameters
+   * @param flameParams Flame parameters
+   * @param characterHandle Optional character handle (for multi-character support)
+   */
   async computeFrameFlatFromParams(flameParams, characterHandle) {
     if (!this.isCharacterLoaded) {
       throw new Error("Character not loaded");
@@ -8751,6 +9211,10 @@ class AvatarCoreAdapter {
       }
     }
   }
+  /**
+   * 获取 WASM 内存使用情况（MB）
+   * @returns WASM 内存使用量（MB），如果模块未加载则返回 null
+   */
   getWASMMemoryMB() {
     if (!this.wasmModule) {
       return null;
@@ -8769,6 +9233,11 @@ class AvatarCoreAdapter {
   }
 }
 class AvatarSDK {
+  /**
+   * Initialize SDK
+   * @param appId Application ID to be included in both HTTP Headers and WebSocket Headers
+   * @param configuration Configuration parameters
+   */
   static async initialize(appId, configuration) {
     var _a;
     try {
@@ -8815,6 +9284,9 @@ class AvatarSDK {
       throw error;
     }
   }
+  /**
+   * 初始化WASM模块（跟随整个SDK生命周期）
+   */
   static async initializeWASMModule() {
     try {
       logger.log("[AvatarSDK] Initializing WASM module...");
@@ -8825,12 +9297,15 @@ class AvatarSDK {
         baseAssetsPath: "",
         wasmPath: "./avatar_core_wasm.js",
         wasmConfig: {
+          // Print function for debugging WASM output
           print: (text) => {
             logger.log(`[WASM] ${text}`);
           },
           printErr: (text) => {
             logger.error(`[WASM ERROR] ${text}`);
           },
+          // 配置 locateFile 以确保能找到 WASM 文件
+          // WASM 文件与 Emscripten JS 文件在同一目录（dist/ 根目录）
           locateFile: (path, prefix) => {
             if (path.startsWith("data:") || path.startsWith("http://") || path.startsWith("https://")) {
               return path;
@@ -8846,6 +9321,10 @@ class AvatarSDK {
       throw new Error(`WASM module initialization failed: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
+  /**
+   * 初始化模板资源（在SDK初始化时加载）
+   * 从全局 CDN 加载模板资源，失败时直接抛出错误，阻止SDK初始化
+   */
   static async initializeTemplateResources() {
     if (!this._avatarCore) {
       throw new Error("AvatarCore not available");
@@ -8871,12 +9350,22 @@ class AvatarSDK {
       throw new Error(`SDK initialization failed: Template resources loading failed - ${errorMessage}`);
     }
   }
+  /**
+   * Set sessionToken
+   * Developer Client -> Developer Server -> AvatarKit Server -> return sessionToken (max 1 hour validity)
+   * Include in WebSocket Headers for avatar WebSocket service authentication
+   */
   static setSessionToken(token) {
     idManager.setSessionToken(token);
   }
+  /**
+   * Set userId
+   * Optional interface for developers, SDK includes this in telemetry logs
+   */
   static setUserId(userId) {
     idManager.setUserId(userId);
   }
+  // 只读属性
   static get isInitialized() {
     return this._isInitialized;
   }
@@ -8895,17 +9384,32 @@ class AvatarSDK {
   static get version() {
     return this._version;
   }
+  /**
+   * 获取播放模式（根据 drivingServiceMode）
+   * @internal
+   */
   static getPlaybackMode() {
     var _a;
     return ((_a = this._configuration) == null ? void 0 : _a.drivingServiceMode) ?? DrivingServiceMode.sdk;
   }
+  /**
+   * 获取音频格式配置（带默认值）
+   * @internal
+   */
   static getAudioFormat() {
     var _a;
     return ((_a = this._configuration) == null ? void 0 : _a.audioFormat) ?? { channelCount: 1, sampleRate: 16e3 };
   }
+  /**
+   * 获取AvatarCore实例（仅供 SDK 内部使用）
+   * @internal
+   */
   static getAvatarCore() {
     return this._avatarCore;
   }
+  /**
+   * Cleanup resources
+   */
   static cleanup() {
     if (!this._isInitialized) {
       return;
@@ -8926,6 +9430,9 @@ class AvatarSDK {
       logger.error("Failed to cleanup AvatarSDK:", error instanceof Error ? error.message : String(error));
     }
   }
+  /**
+   * 从远程配置接口获取SDK配置（已简化，逻辑移到 config/sdk-config-loader.ts）
+   */
   static async _fetchSdkConfig() {
     try {
       this._dynamicSdkConfig = await fetchSdkConfig(this._version);
@@ -8937,6 +9444,10 @@ class AvatarSDK {
       });
     }
   }
+  /**
+   * 获取环境配置（对齐 web 应用的 region-config）
+   * @internal
+   */
   static getEnvironmentConfig() {
     if (!this._configuration) {
       throw new Error("AvatarSDK not initialized");
@@ -8961,10 +9472,10 @@ class AvatarSDK {
 }
 __publicField(AvatarSDK, "_isInitialized", false);
 __publicField(AvatarSDK, "_configuration", null);
-__publicField(AvatarSDK, "_version", "1.0.0-beta.68");
+__publicField(AvatarSDK, "_version", "1.0.0-beta.69");
 __publicField(AvatarSDK, "_avatarCore", null);
 __publicField(AvatarSDK, "_dynamicSdkConfig", null);
-const AvatarSDK$1 = Object.freeze(Object.defineProperty({
+const AvatarSDK$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
   __proto__: null,
   AvatarSDK
 }, Symbol.toStringTag, { value: "Module" }));
@@ -9936,6 +10447,7 @@ class EventEmitter {
       }
     }
   }
+  // eslint-disable-next-line ts/no-explicit-any
   emit(event, ...args) {
     const handlers = this.events.get(event);
     if (handlers) {
@@ -9951,6 +10463,7 @@ class EventEmitter {
   }
 }
 class AnimationWebSocketClient extends EventEmitter {
+  // v2 协议：标记会话是否已配置
   constructor(options) {
     super();
     __publicField(this, "wsUrl");
@@ -9971,6 +10484,9 @@ class AnimationWebSocketClient extends EventEmitter {
     this.appId = options.appId;
     this.clientId = options.clientId;
   }
+  /**
+   * 连接WebSocket
+   */
   async connect(characterId) {
     if (this.ws && this.ws.readyState === WebSocket.OPEN) {
       logger.log("[AnimationWebSocketClient] Already connected");
@@ -9996,6 +10512,9 @@ class AnimationWebSocketClient extends EventEmitter {
       throw error;
     }
   }
+  /**
+   * 断开连接
+   */
   disconnect() {
     if (this.ws) {
       this.ws.close(1e3, "Normal closure");
@@ -10013,6 +10532,10 @@ class AnimationWebSocketClient extends EventEmitter {
     }
     logger.log("[AnimationWebSocketClient] Disconnected");
   }
+  /**
+   * 发送音频数据
+   * @param conversationId - 会话ID（在 protobuf 协议中映射为 reqId 字段）
+   */
   sendAudioData(conversationId, audioData, end) {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
       logger.error("[AnimationWebSocketClient] WebSocket not connected");
@@ -10048,15 +10571,26 @@ class AnimationWebSocketClient extends EventEmitter {
       return false;
     }
   }
+  /**
+   * 生成会话ID
+   * 使用统一的会话ID生成规则：YYYYMMDDHHmmss_nanoid
+   */
   generateConversationId() {
     return idManager.generateNewConversationId();
   }
+  /**
+   * 获取连接状态
+   */
   isConnected() {
     return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
   }
+  /**
+   * 获取当前角色ID
+   */
   getCurrentCharacterId() {
     return this.currentCharacterId;
   }
+  // ========== 私有方法 ==========
   buildWebSocketUrl(characterId) {
     const url = new URL(this.wsUrl);
     url.searchParams.set("id", characterId);
@@ -10183,6 +10717,9 @@ class AnimationWebSocketClient extends EventEmitter {
       }
     });
   }
+  /**
+   * 清理 URL 用于日志记录（隐藏敏感信息）
+   */
   sanitizeUrlForLog(url) {
     try {
       const urlObj = new URL(url);
@@ -10199,6 +10736,9 @@ class AnimationWebSocketClient extends EventEmitter {
       return url.length > 100 ? `${url.substring(0, 100)}...` : url;
     }
   }
+  /**
+   * v2 协议：配置会话（发送采样率等参数）
+   */
   configureSession() {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
       logger.error("[AnimationWebSocketClient] Cannot configure session: WebSocket not open");
@@ -10211,6 +10751,7 @@ class AnimationWebSocketClient extends EventEmitter {
         clientConfigureSession: {
           sampleRate: audioFormatConfig.sampleRate,
           bitrate: 0,
+          // 根据实际需求设置
           audioFormat: AudioFormat.AUDIO_FORMAT_PCM_S16LE,
           transportCompression: TransportCompression.TRANSPORT_COMPRESSION_NONE
         }
@@ -10285,13 +10826,18 @@ class NetworkLayer {
   constructor(dataController) {
     __publicField(this, "wsClient");
     __publicField(this, "dataController");
+    // 组合播放层
     __publicField(this, "currentConversationId", null);
     __publicField(this, "audioMetrics", this.createAudioMetrics());
     __publicField(this, "isFallbackMode", false);
+    // 连接超时降级模式标记
     __publicField(this, "isConnecting", false);
+    // 避免并发连接
+    // 驱动服务心跳检测相关
     __publicField(this, "heartbeatTimer", null);
     __publicField(this, "visibilityChangeHandler", null);
     __publicField(this, "heartbeatFailureCount", 0);
+    // 心跳失败计数
     __publicField(this, "HEARTBEAT_INTERVAL", 12e4);
     this.dataController = dataController;
     const config = AvatarSDK.getEnvironmentConfig();
@@ -10305,10 +10851,17 @@ class NetworkLayer {
     this.setupWebSocketListeners();
     this.startHeartbeatCheck();
   }
+  // 每2分钟检查一次
+  /**
+   * 获取音频字节每秒（根据配置的采样率动态计算）
+   */
   getAudioBytesPerSecond() {
     const audioFormat = AvatarSDK.getAudioFormat();
     return audioFormat.sampleRate * 2;
   }
+  /**
+   * 连接服务
+   */
   async connect(characterId) {
     var _a, _b, _c, _d;
     if (this.isConnecting) {
@@ -10352,9 +10905,17 @@ class NetworkLayer {
       this.isConnecting = false;
     }
   }
+  /**
+   * 检查是否可以发送音频数据（包括降级模式）
+   * @internal
+   */
   canSend() {
     return this.isFallbackMode || this.dataController.connected;
   }
+  /**
+   * 发送音频数据到服务器
+   * 注意：打断逻辑由 AvatarController.send() 统一处理，这里只负责网络通信
+   */
   sendAudioData(audioData, isLast) {
     var _a, _b;
     if (!this.currentConversationId) {
@@ -10400,6 +10961,9 @@ class NetworkLayer {
       return;
     }
   }
+  /**
+   * 断开连接
+   */
   disconnect() {
     this.isFallbackMode = false;
     this.isConnecting = false;
@@ -10409,13 +10973,23 @@ class NetworkLayer {
     idManager.clearConnectionId();
     this.currentConversationId = null;
   }
+  /**
+   * 获取当前会话ID
+   */
   getCurrentConversationId() {
     return this.currentConversationId;
   }
+  /**
+   * 重置会话ID（用于打断后清理）
+   */
   resetConversationId() {
     this.currentConversationId = null;
     this.resetAudioMetrics();
   }
+  /**
+   * 设置 WebSocket 事件监听器
+   * Safety: Remove existing listeners before adding new ones to prevent duplicates
+   */
   setupWebSocketListeners() {
     this.wsClient.removeAllListeners();
     this.wsClient.on("sessionConfirmed", (connectionId) => {
@@ -10450,6 +11024,9 @@ class NetworkLayer {
       this.handleMessage(message);
     });
   }
+  /**
+   * 处理接收到的消息
+   */
   handleMessage(message) {
     try {
       switch (message.type) {
@@ -10465,6 +11042,9 @@ class NetworkLayer {
       logger.error("[NetworkLayer] Failed to handle message:", message2);
     }
   }
+  /**
+   * 处理动画消息
+   */
   handleAnimationMessage(message) {
     if (!message.serverResponseAnimation) {
       logger.error("[NetworkLayer] Invalid animation message");
@@ -10514,6 +11094,9 @@ class NetworkLayer {
       });
     }
   }
+  /**
+   * 处理错误消息
+   */
   handleErrorMessage(message) {
     var _a, _b;
     if (!message.serverError) {
@@ -10558,6 +11141,9 @@ class NetworkLayer {
       this.dataController.yieldKeyframes([], conversationId);
     }
   }
+  /**
+   * 创建音频指标
+   */
   createAudioMetrics() {
     return {
       accumulatedBytes: 0,
@@ -10569,9 +11155,16 @@ class NetworkLayer {
       didReportLatency: false
     };
   }
+  /**
+   * 重置音频指标
+   */
   resetAudioMetrics() {
     this.audioMetrics = this.createAudioMetrics();
   }
+  /**
+   * 上报 driving_service_latency 事件
+   * 每轮会话只上报一次（在收到首帧时）
+   */
   reportDrivingServiceLatency(conversationId) {
     if (!conversationId) {
       return;
@@ -10580,12 +11173,21 @@ class NetworkLayer {
     logEvent("driving_service_latency", "info", {
       req_id: conversationId,
       dsm: "sdk",
+      // 写死 sdk
       tap_0: metrics.startTimestamp || 0,
+      // 必须有非零值
       tap_1: metrics.tap1Timestamp || 0,
+      // 缺省值为 0
       tap_2: metrics.tap2Timestamp || 0,
+      // 缺省值为 0
       tap_f: metrics.recvFirstFlameTimestamp || 0
+      // 必须有非零值
     });
   }
+  /**
+   * 启动驱动服务心跳检测（每2分钟检查一次连接状态）
+   * @private
+   */
   startHeartbeatCheck() {
     this.stopHeartbeatCheck();
     this.heartbeatTimer = window.setInterval(() => {
@@ -10595,6 +11197,10 @@ class NetworkLayer {
     }, this.HEARTBEAT_INTERVAL);
     this.setupVisibilityListener();
   }
+  /**
+   * 停止驱动服务心跳检测
+   * @private
+   */
   stopHeartbeatCheck() {
     if (this.heartbeatTimer !== null) {
       clearInterval(this.heartbeatTimer);
@@ -10603,6 +11209,11 @@ class NetworkLayer {
     this.removeVisibilityListener();
     this.heartbeatFailureCount = 0;
   }
+  /**
+   * 执行心跳检查：检测 WebSocket 连接状态
+   * 如果连接失败 3 次，上报 heartbeat_failed 事件
+   * @private
+   */
   performHeartbeatCheck() {
     try {
       const isConnected = this.wsClient.isConnected();
@@ -10631,6 +11242,10 @@ class NetworkLayer {
       }
     }
   }
+  /**
+   * 设置页面可见性监听器（用于页面重新可见时立即执行心跳检查）
+   * @private
+   */
   setupVisibilityListener() {
     if (typeof window === "undefined" || typeof document === "undefined") {
       return;
@@ -10643,6 +11258,10 @@ class NetworkLayer {
     };
     document.addEventListener("visibilitychange", this.visibilityChangeHandler);
   }
+  /**
+   * 移除页面可见性监听器
+   * @private
+   */
   removeVisibilityListener() {
     if (typeof window === "undefined" || typeof document === "undefined" || !this.visibilityChangeHandler) {
       return;
@@ -10652,35 +11271,56 @@ class NetworkLayer {
   }
 }
 class AvatarController {
+  // 16kHz * 2 bytes per sample
   constructor(avatar, options) {
+    // ========== Configuration and Composition ==========
     __publicField(this, "networkLayer");
     __publicField(this, "playbackMode");
     __publicField(this, "avatar");
+    // ========== Player Management ==========
     __publicField(this, "animationPlayer", null);
     __publicField(this, "currentKeyframes", []);
     __publicField(this, "pendingAudioChunks", []);
     __publicField(this, "isPlaying", false);
     __publicField(this, "isStartingPlayback", false);
+    // 防止重复调用 startStreamingPlayback
+    // ========== State Management ==========
     __publicField(this, "isConnected", false);
     __publicField(this, "currentState", AvatarState.idle);
+    // ========== Conversation ID Management (for host mode) ==========
     __publicField(this, "currentConversationId", null);
     __publicField(this, "reqEnd", false);
+    // ========== Event System ==========
     __publicField(this, "onConnectionState", null);
     __publicField(this, "onConversationState", null);
     __publicField(this, "onError", null);
     __publicField(this, "eventListeners", /* @__PURE__ */ new Map());
+    // ========== Callbacks ==========
     __publicField(this, "renderCallback");
     __publicField(this, "characterHandle", null);
+    // Character handle for multi-character support
     __publicField(this, "characterId", null);
+    // Character ID for multi-character support (used for eye tracking)
+    // ========== Post-processing Configuration ==========
     __publicField(this, "postProcessingConfig", null);
+    // ========== Playback Loop ==========
     __publicField(this, "playbackLoopId", null);
     __publicField(this, "lastRenderedFrameIndex", -1);
     __publicField(this, "keyframesOffset", 0);
+    // Offset to track how many frames were removed from the beginning
     __publicField(this, "MAX_KEYFRAMES", 5e3);
+    // Maximum keyframes to keep in memory during playback
     __publicField(this, "KEYFRAMES_CLEANUP_THRESHOLD", 3e3);
+    // Cleanup threshold (keep some buffer)
+    // 日志控制：避免刷屏
     __publicField(this, "lastSyncLogTime", 0);
+    // 上次同步状态日志时间
     __publicField(this, "lastOutOfBoundsState", false);
+    // 上次是否超出范围的状态
+    // ========== Audio Only Mode ==========
     __publicField(this, "isAudioOnlyMode", false);
+    // 音频独立播放模式标志
+    // ========== Playback Stuck Detection ==========
     __publicField(this, "playbackStuckCheckState", {
       audioTimeZeroCount: 0,
       lastAudioTime: 0,
@@ -10688,8 +11328,12 @@ class AvatarController {
       reported: false
     });
     __publicField(this, "MAX_AUDIO_TIME_ZERO_COUNT", 60);
+    // 约 1 秒（60fps）
     __publicField(this, "MAX_AUDIO_TIME_STUCK_COUNT", 60);
+    // 约 1 秒（60fps）
     __publicField(this, "AUDIO_TIME_STUCK_THRESHOLD", 1e-3);
+    // 1ms，小于此值视为卡住
+    // ========== Host Mode Latency Metrics ==========
     __publicField(this, "hostModeMetrics", {
       accumulatedBytes: 0,
       startTimestamp: 0,
@@ -10706,21 +11350,46 @@ class AvatarController {
       this.networkLayer = new NetworkLayer(this);
     }
   }
+  // ========== Internal Accessors (for NetworkLayer and AvatarView) ==========
+  /**
+   * Get Avatar ID (for NetworkLayer use)
+   * @internal
+   */
   getAvatarId() {
     return this.avatar.id;
   }
+  /**
+   * Get playback state (for NetworkLayer use)
+   * @internal
+   */
   getIsPlaying() {
     return this.isPlaying;
   }
+  /**
+   * Set connection state (for NetworkLayer use)
+   * @internal
+   */
   setConnected(connected) {
     this.isConnected = connected;
   }
+  /**
+   * Get connection state
+   * @internal
+   */
   get connected() {
     return this.isConnected;
   }
+  /**
+   * Get current state
+   * @internal
+   */
   get state() {
     return this.currentState;
   }
+  /**
+   * 将内部 AvatarState 映射到外部 ConversationState
+   * @internal
+   */
   mapToConversationState(avatarState) {
     switch (avatarState) {
       case AvatarState.idle:
@@ -10735,12 +11404,35 @@ class AvatarController {
         return ConversationState.idle;
     }
   }
+  /**
+   * Get animation player instance
+   * @internal
+   */
   getAnimationPlayer() {
     return this.animationPlayer;
   }
+  /**
+   * Get current conversation ID
+   * Returns the current conversation ID for the active audio session
+   * @returns Current conversation ID, or null if no active session
+   */
   getCurrentConversationId() {
     return this.getEffectiveConversationId();
   }
+  // ========== Audio Context Initialization ==========
+  /**
+   * Initialize audio context (must be called in user gesture context)
+   * 
+   * This method must be called before any audio operations (send, yieldAudioData, etc.)
+   * to ensure AudioContext is created and initialized in a user gesture context.
+   * 
+   * @example
+   * // In user click handler
+   * button.addEventListener('click', async () => {
+   *   await avatarView.controller.initializeAudioContext()
+   *   // Now you can safely use send() or yieldAudioData()
+   * })
+   */
   async initializeAudioContext() {
     var _a;
     if ((_a = this.animationPlayer) == null ? void 0 : _a.isStreamingReady()) {
@@ -10773,6 +11465,10 @@ class AvatarController {
       }
     }
   }
+  /**
+   * Check if audio context is initialized
+   * @throws AvatarError if audio context is not initialized
+   */
   checkAudioContextInitialized() {
     var _a;
     if (!((_a = this.animationPlayer) == null ? void 0 : _a.isStreamingReady())) {
@@ -10782,6 +11478,10 @@ class AvatarController {
       );
     }
   }
+  // ========== SDK Mode Interface ==========
+  /**
+   * Start service (SDK mode only)
+   */
   async start() {
     if (!this.networkLayer) {
       throw new AvatarError(
@@ -10792,6 +11492,11 @@ class AvatarController {
     this.checkAudioContextInitialized();
     await this.networkLayer.connect(this.avatar.id);
   }
+  /**
+   * Send audio to server (SDK mode only)
+   * Also cache to data layer for playback
+   * @returns conversationId - Conversation ID for this audio session
+   */
   send(audioData, end = false) {
     var _a, _b, _c, _d;
     try {
@@ -10827,6 +11532,9 @@ class AvatarController {
     }
     return this.networkLayer.getCurrentConversationId();
   }
+  /**
+   * Close service (SDK mode only)
+   */
   close() {
     var _a;
     if (this.isPlaying || this.currentState === AvatarState.paused) {
@@ -10842,6 +11550,15 @@ class AvatarController {
     this.isConnected = false;
     (_a = this.onConnectionState) == null ? void 0 : _a.call(this, ConnectionState.disconnected);
   }
+  // ========== Host Mode Interface ==========
+  /**
+   * Playback existing audio and animation data (host mode)
+   * Starts a new conversation by generating a new conversation ID and interrupting any existing conversation
+   * @param initialAudioChunks - Existing audio chunks to playback
+   * @param initialKeyframes - Existing animation keyframes to playback
+   * @returns conversationId - New conversation ID for this conversation session
+   * @internal
+   */
   async playback(initialAudioChunks, initialKeyframes) {
     this.checkAudioContextInitialized();
     if (this.isPlaying || this.currentConversationId) {
@@ -10875,6 +11592,11 @@ class AvatarController {
     }
     return this.currentConversationId;
   }
+  /**
+   * Send audio data (host mode)
+   * Stream additional audio data after playback()
+   * @returns conversationId - Conversation ID for this audio session
+   */
   yieldAudioData(data, isLast = false) {
     var _a, _b, _c;
     try {
@@ -10923,6 +11645,15 @@ class AvatarController {
     }
     return this.currentConversationId;
   }
+  /**
+   * Send animation keyframes (host mode or SDK mode)
+   * Stream additional animation data after playback()
+   * 
+   * Public API: accepts binary data array (protobuf encoded Message array)
+   * @param keyframesDataArray - Animation keyframes binary data array (each element is a protobuf encoded Message) or empty array to trigger audio-only mode
+   * @param conversationId - Conversation ID (required). If conversationId doesn't match current conversationId, keyframes will be discarded.
+   *                Use getCurrentConversationId() to get the current conversationId.
+   */
   yieldFramesData(keyframesDataArray, conversationId) {
     var _a, _b;
     if (!keyframesDataArray || keyframesDataArray.length === 0) {
@@ -10963,6 +11694,18 @@ class AvatarController {
     }
     this.yieldKeyframes(allKeyframes, conversationId);
   }
+  /**
+   * Send animation keyframes (host mode)
+   * Stream animation keyframes data after yieldAudioData()
+   * 
+   * ⚠️ **Not recommended**: Prefer using `yieldFramesData()` method, which accepts binary data (protobuf encoded Message) with better performance.
+   * This method is only for scenarios where you already have decoded KeyframeData arrays.
+   * 
+   * Public API: accepts decoded keyframes
+   * @param keyframes - Animation keyframes array (KeyframeData[]) or empty array to trigger audio-only mode
+   * @param conversationId - Conversation ID (required). If conversationId doesn't match current conversationId, keyframes will be discarded.
+   *                Use getCurrentConversationId() to get the current conversationId.
+   */
   yieldKeyframes(keyframes, conversationId) {
     if (!conversationId || typeof conversationId !== "string") {
       logger.error(`[AvatarController] yieldKeyframes requires a valid conversationId. Use getCurrentConversationId() to get the current conversationId.`);
@@ -11003,8 +11746,9 @@ class AvatarController {
       this.enableAudioOnlyMode();
       return;
     }
+    const flameKeyframes = keyframes;
     if (this.currentKeyframes.length === 0) {
-      this.currentKeyframes = keyframes;
+      this.currentKeyframes = flameKeyframes;
       if (this.playbackMode === DrivingServiceMode.host && !this.hostModeMetrics.didRecvFirstFlame) {
         this.hostModeMetrics.didRecvFirstFlame = true;
         this.hostModeMetrics.recvFirstFlameTimestamp = Date.now();
@@ -11014,7 +11758,7 @@ class AvatarController {
         }
       }
     } else {
-      this.currentKeyframes.push(...keyframes);
+      this.currentKeyframes.push(...flameKeyframes);
     }
     this.emit("keyframesUpdate", this.currentKeyframes);
     if (!this.isPlaying && !this.isStartingPlayback && this.pendingAudioChunks.length > 0 && this.currentKeyframes.length > 0) {
@@ -11026,6 +11770,11 @@ class AvatarController {
       });
     }
   }
+  // ========== Common Interface ==========
+  /**
+   * Pause playback (can be resumed later)
+   * Pause audio playback and stop render loop, but preserve all state (keyframes, audio buffers, etc.)
+   */
   pause() {
     var _a, _b;
     if (!this.isPlaying || this.currentState === AvatarState.paused) {
@@ -11038,6 +11787,11 @@ class AvatarController {
     (_b = this.onConversationState) == null ? void 0 : _b.call(this, this.mapToConversationState(AvatarState.paused));
     logger.log("[AvatarController] Playback paused");
   }
+  /**
+   * Resume playback (from paused state)
+   * Resume audio playback and restart render loop
+   * Animation will continue from paused frame (because animation time base comes from audio, will auto-sync)
+   */
   async resume() {
     var _a, _b;
     if (!this.isPlaying || this.currentState !== AvatarState.paused) {
@@ -11050,6 +11804,9 @@ class AvatarController {
     (_b = this.onConversationState) == null ? void 0 : _b.call(this, this.mapToConversationState(AvatarState.playing));
     logger.log("[AvatarController] Playback resumed");
   }
+  /**
+   * Interrupt current playback
+   */
   interrupt() {
     var _a;
     if (this.currentState === AvatarState.paused) {
@@ -11062,6 +11819,9 @@ class AvatarController {
     this.resetConversationIdState();
     this.isAudioOnlyMode = false;
   }
+  /**
+   * Clear all data and resources
+   */
   clear() {
     var _a, _b;
     if (this.isPlaying) {
@@ -11079,6 +11839,11 @@ class AvatarController {
     }
     this.reqEnd = false;
   }
+  /**
+   * Dispose controller, clean up all callbacks to avoid memory leaks
+   * Should be called when AvatarView.dispose()
+   * @internal
+   */
   dispose() {
     this.onConnectionState = null;
     this.onConversationState = null;
@@ -11086,6 +11851,11 @@ class AvatarController {
     this.renderCallback = void 0;
     this.eventListeners.clear();
   }
+  // ========== Internal Helper Methods ==========
+  /**
+   * Generate new conversation ID and log conversation started event
+   * @private
+   */
   generateAndLogNewConversationId() {
     const conversationId = idManager.generateNewConversationId();
     logEvent("character_manager", "info", {
@@ -11095,6 +11865,10 @@ class AvatarController {
     });
     return conversationId;
   }
+  /**
+   * Clear playback data (keyframes, audio chunks, and playback state)
+   * @private
+   */
   clearPlaybackData() {
     this.currentKeyframes = [];
     this.pendingAudioChunks = [];
@@ -11115,6 +11889,10 @@ class AvatarController {
       };
     }
   }
+  /**
+   * Reset conversation ID state (for both network and external modes)
+   * @private
+   */
   resetConversationIdState() {
     if (this.networkLayer) {
       this.networkLayer.resetConversationId();
@@ -11135,6 +11913,10 @@ class AvatarController {
       };
     }
   }
+  /**
+   * Get effective conversation ID (handles both SDK and host modes)
+   * @private
+   */
   getEffectiveConversationId() {
     var _a;
     if (this.playbackMode === DrivingServiceMode.sdk) {
@@ -11143,18 +11925,35 @@ class AvatarController {
       return this.currentConversationId;
     }
   }
+  // ========== Internal Methods (for NetworkLayer and AvatarView use) ==========
+  /**
+   * Start streaming playback (internal method, called by NetworkLayer or playback())
+   * @internal
+   */
   startStreamingPlayback() {
     return this.startStreamingPlaybackInternal();
   }
+  /**
+   * Set render callback (called by AvatarView)
+   * @internal
+   */
   setRenderCallback(callback, characterHandle) {
     this.renderCallback = callback;
     if (characterHandle !== void 0) {
       this.characterHandle = characterHandle;
     }
   }
+  /**
+   * Set character ID (for multi-character support, used for eye tracking)
+   * @internal
+   */
   setCharacterId(characterId) {
     this.characterId = characterId;
   }
+  /**
+   * Get point cloud count of the current avatar
+   * @returns Point cloud count, or null if avatar is not loaded
+   */
   getPointCount() {
     const avatarCore = AvatarSDK.getAvatarCore();
     if (!avatarCore || !this.characterHandle) {
@@ -11162,6 +11961,11 @@ class AvatarController {
     }
     return avatarCore.getPointCount(this.characterHandle);
   }
+  /**
+   * Set post-processing configuration
+   * These parameters will be applied in real-time to animation parameters returned by the server
+   * @param config Post-processing configuration, or null to clear
+   */
   setPostProcessingConfig(config) {
     this.postProcessingConfig = config;
     if (config == null ? void 0 : config.eyefocus) {
@@ -11173,6 +11977,10 @@ class AvatarController {
       this.rerenderCurrentFrame();
     }
   }
+  /**
+   * 设置完整的 eye tracking 配置到 C++
+   * @private
+   */
   async setEyeTrackingConfig(eyefocus) {
     const avatarCore = AvatarSDK.getAvatarCore();
     if (!avatarCore || !this.characterId) {
@@ -11196,6 +12004,10 @@ class AvatarController {
       logger.warn("[AvatarController] Failed to set eye tracking config:", error instanceof Error ? error.message : String(error));
     }
   }
+  /**
+   * 重新渲染当前帧（用于暂停状态下更新后处理参数或相机配置）
+   * @internal
+   */
   async rerenderCurrentFrameIfPaused() {
     if (this.currentState !== AvatarState.paused || !this.renderCallback) {
       return;
@@ -11228,9 +12040,17 @@ class AvatarController {
       logger.error("[AvatarController] Failed to rerender current frame:", error instanceof Error ? error.message : String(error));
     }
   }
+  /**
+   * 重新渲染当前帧（用于暂停状态下更新后处理参数）
+   * @private
+   */
   async rerenderCurrentFrame() {
     await this.rerenderCurrentFrameIfPaused();
   }
+  /**
+   * Transition complete notification (called by AvatarView)
+   * @internal
+   */
   onTransitionComplete() {
     var _a;
     const streamingPlayer = (_a = this.animationPlayer) == null ? void 0 : _a.getStreamingPlayer();
@@ -11238,6 +12058,11 @@ class AvatarController {
       streamingPlayer.play();
     }
   }
+  /**
+   * Set audio playback volume
+   * Note: This only controls the avatar audio player volume, not the system volume
+   * @param volume Volume value, range from 0.0 to 1.0 (0.0 = mute, 1.0 = max volume)
+   */
   setVolume(volume) {
     var _a;
     if (volume < 0 || volume > 1) {
@@ -11251,10 +12076,18 @@ class AvatarController {
       volume
     });
   }
+  /**
+   * Get current audio playback volume
+   * @returns Current volume value (0.0 - 1.0)
+   */
   getVolume() {
     var _a;
     return ((_a = this.animationPlayer) == null ? void 0 : _a.getVolume()) ?? 1;
   }
+  /**
+   * Provide interface for AvatarView to register internal events
+   * @internal
+   */
   setupInternalEventListeners(callbacks) {
     if (callbacks.onKeyframesUpdate) {
       this.registerEventListener("keyframesUpdate", callbacks.onKeyframesUpdate);
@@ -11269,6 +12102,10 @@ class AvatarController {
       this.registerEventListener("interrupt", callbacks.onInterrupt);
     }
   }
+  // ========== Private Methods ==========
+  /**
+   * Start streaming playback (internal implementation)
+   */
   async startStreamingPlaybackInternal() {
     var _a, _b, _c;
     this.checkAudioContextInitialized();
@@ -11336,6 +12173,18 @@ class AvatarController {
       this.isStartingPlayback = false;
     }
   }
+  /**
+   * Playback loop: Calculate animation frame based on audio time, notify render layer to render
+   */
+  /**
+   * 检测播放是否卡住（在过渡动画完成后）
+   * 注意：AudioContext suspended 的情况现在由 StreamingAudioPlayer 自动处理，不再作为触发条件
+   * 此函数主要用于检测其他原因导致的播放卡住（如网络问题、音频数据问题等）
+   * 
+   * @param audioTime 当前音频时间
+   * @returns true 如果检测到卡住并已上报，false 否则
+   * @internal
+   */
   checkPlaybackStuck(audioTime) {
     var _a, _b, _c, _d, _e2, _f;
     const streamingPlayer = (_a = this.animationPlayer) == null ? void 0 : _a.getStreamingPlayer();
@@ -11378,6 +12227,7 @@ class AvatarController {
         event: "playback_stuck_after_transition",
         avatar_id: this.avatar.id,
         conversationId: ((_e2 = this.networkLayer) == null ? void 0 : _e2.getCurrentConversationId()) || void 0,
+        // 诊断信息（包含 audioContextState 用于诊断，但不作为触发条件）
         audioContextState,
         audioTime,
         audioTimeZero: audioTime === 0,
@@ -11488,12 +12338,22 @@ class AvatarController {
     };
     this.playbackLoopId = requestAnimationFrame(playLoop);
   }
+  /**
+   * Stop playback loop
+   */
   stopPlaybackLoop() {
     if (this.playbackLoopId) {
       cancelAnimationFrame(this.playbackLoopId);
       this.playbackLoopId = null;
     }
   }
+  // ========== Audio Only Mode ==========
+  /**
+   * 启用音频独立播放模式（当服务器错误或超时时调用）
+   * 此模式下，音频会独立播放，不依赖动画数据
+   * 一旦启用，本次会话后续的动画数据将被忽略
+   * @private
+   */
   enableAudioOnlyMode() {
     if (this.isAudioOnlyMode) {
       return;
@@ -11507,6 +12367,10 @@ class AvatarController {
       });
     }
   }
+  /**
+   * 音频独立播放（完全独立的逻辑，不影响正常播放流程）
+   * @private
+   */
   async startAudioOnlyPlayback() {
     var _a, _b;
     if (!this.animationPlayer) {
@@ -11553,6 +12417,11 @@ class AvatarController {
       throw error;
     }
   }
+  /**
+   * 音频监控循环（仅用于音频独立模式）
+   * 只检测音频是否结束，不进行动画渲染
+   * @private
+   */
   startAudioMonitoringLoop() {
     if (this.playbackLoopId) {
       return;
@@ -11571,6 +12440,9 @@ class AvatarController {
     };
     this.playbackLoopId = requestAnimationFrame(monitorLoop);
   }
+  /**
+   * Stop playback
+   */
   stopPlayback() {
     var _a;
     this.stopPlaybackLoop();
@@ -11585,12 +12457,19 @@ class AvatarController {
     this.currentState = AvatarState.idle;
     (_a = this.onConversationState) == null ? void 0 : _a.call(this, this.mapToConversationState(AvatarState.idle));
   }
+  /**
+   * Clean up players
+   */
   cleanupPlayers() {
     if (this.animationPlayer) {
       this.animationPlayer.dispose();
       this.animationPlayer = null;
     }
   }
+  /**
+   * Add audio chunk to buffer
+   * Note: animationPlayer should already be initialized before calling this method
+   */
   addAudioChunkToBuffer(data, isLast) {
     if (!this.animationPlayer) {
       logger.warn("[AvatarController] animationPlayer is null in addAudioChunkToBuffer, this should not happen");
@@ -11603,18 +12482,29 @@ class AvatarController {
       this.pendingAudioChunks.push({ data, isLast });
     }
   }
+  /**
+   * Event system
+   */
   registerEventListener(event, callback) {
     if (!this.eventListeners.has(event)) {
       this.eventListeners.set(event, /* @__PURE__ */ new Set());
     }
     this.eventListeners.get(event).add(callback);
   }
+  /**
+   * Emit event
+   */
   emit(event, data) {
     const listeners = this.eventListeners.get(event);
     if (listeners) {
       listeners.forEach((callback) => callback(data));
     }
   }
+  /**
+   * Apply post-processing parameters to a Flame (proto format)
+   * Used for transition animations
+   * @internal
+   */
   applyPostProcessingToFlame(flame) {
     if (!this.postProcessingConfig) {
       return flame;
@@ -11623,6 +12513,10 @@ class AvatarController {
     wasmParams = this.applyPostProcessingToParams(wasmParams);
     return convertWasmParamsToProtoFlame(wasmParams);
   }
+  /**
+   * Apply post-processing parameters to animation parameters
+   * @private
+   */
   applyPostProcessingToParams(baseParams) {
     if (!this.postProcessingConfig) {
       return baseParams;
@@ -11696,6 +12590,11 @@ class AvatarController {
     }
     return result2;
   }
+  /**
+   * 上报 driving_service_latency 事件（Host 模式）
+   * 每轮会话只上报一次（在收到首帧时）
+   * @private
+   */
   reportDrivingServiceLatency(conversationId) {
     if (!conversationId || this.playbackMode !== DrivingServiceMode.host) {
       return;
@@ -11704,10 +12603,15 @@ class AvatarController {
     logEvent("driving_service_latency", "info", {
       req_id: conversationId,
       dsm: "host",
+      // Host 模式
       tap_0: metrics.startTimestamp || 0,
+      // 必须有非零值
       tap_1: metrics.tap1Timestamp || 0,
+      // 缺省值为 0
       tap_2: metrics.tap2Timestamp || 0,
+      // 缺省值为 0
       tap_f: metrics.recvFirstFlameTimestamp || 0
+      // 必须有非零值
     });
   }
 }
@@ -11731,12 +12635,21 @@ function errorToMessage(err) {
   return String(err);
 }
 const _PwaCacheManager = class _PwaCacheManager {
+  /**
+   * 检查是否支持 Cache API
+   */
   static isSupported() {
     return typeof caches !== "undefined";
   }
+  /**
+   * 获取角色缓存名称
+   */
   static getCharacterCacheName(characterId) {
     return `${_PwaCacheManager.CHARACTER_CACHE_PREFIX}${characterId}${_PwaCacheManager.CHARACTER_CACHE_SUFFIX}`;
   }
+  /**
+   * 从角色缓存获取资源
+   */
   static async getCharacterResource(characterId, url) {
     if (!_PwaCacheManager.isSupported()) {
       return null;
@@ -11756,6 +12669,9 @@ const _PwaCacheManager = class _PwaCacheManager {
       return null;
     }
   }
+  /**
+   * 将角色资源写入缓存
+   */
   static async putCharacterResource(characterId, url, data) {
     if (!_PwaCacheManager.isSupported()) {
       return;
@@ -11775,6 +12691,9 @@ const _PwaCacheManager = class _PwaCacheManager {
       logger.warn(`[PwaCacheManager] Failed to put character resource to cache:`, error);
     }
   }
+  /**
+   * 从模板缓存获取资源
+   */
   static async getTemplateResource(url) {
     if (!_PwaCacheManager.isSupported()) {
       return null;
@@ -11793,6 +12712,10 @@ const _PwaCacheManager = class _PwaCacheManager {
       return null;
     }
   }
+  /**
+   * 将模板资源写入缓存
+   * 模板资源不设置数量限制，永久保留直到版本更新
+   */
   static async putTemplateResource(url, data) {
     if (!_PwaCacheManager.isSupported()) {
       return;
@@ -11805,6 +12728,9 @@ const _PwaCacheManager = class _PwaCacheManager {
       logger.warn(`[PwaCacheManager] Failed to put template resource to cache:`, error);
     }
   }
+  /**
+   * 清理角色缓存
+   */
   static async clearCharacterCache(characterId) {
     if (!_PwaCacheManager.isSupported()) {
       return;
@@ -11817,6 +12743,11 @@ const _PwaCacheManager = class _PwaCacheManager {
       logger.warn(`[PwaCacheManager] Failed to clear character cache:`, error);
     }
   }
+  /**
+   * 检查模板缓存版本，如果版本变化则清理
+   * 使用独立的模板资源版本号（不依赖 SDK 版本），这样不同 SDK 版本可以共享相同模板资源的缓存
+   * @returns true 如果版本变化并清理了缓存，false 否则
+   */
   static async checkTemplateCacheVersion() {
     if (!_PwaCacheManager.isSupported()) {
       return false;
@@ -11841,14 +12772,17 @@ const _PwaCacheManager = class _PwaCacheManager {
     }
   }
 };
+// 模板缓存版本（独立于 SDK 版本，当模板资源更新时需要手动更新此版本号）
 __publicField(_PwaCacheManager, "TEMPLATE_RESOURCE_VERSION", "1.0.0");
 __publicField(_PwaCacheManager, "TEMPLATE_CACHE_NAME", `spatialwalk-sdk-template-cache-${_PwaCacheManager.TEMPLATE_RESOURCE_VERSION}`);
 __publicField(_PwaCacheManager, "TEMPLATE_VERSION_STORAGE_KEY", "spatialwalk-sdk-template-cache-version");
+// 角色缓存前缀和后缀
 __publicField(_PwaCacheManager, "CHARACTER_CACHE_PREFIX", "spatialwalk-sdk-character-");
 __publicField(_PwaCacheManager, "CHARACTER_CACHE_SUFFIX", "-cache");
+// 角色缓存 LRU 限制：最多 1000 个资源条目（支持约 250 个角色，每个角色 4 个资源）
 __publicField(_PwaCacheManager, "MAX_CHARACTER_CACHE_ENTRIES", 1e3);
 let PwaCacheManager = _PwaCacheManager;
-const pwaCacheManager = Object.freeze(Object.defineProperty({
+const pwaCacheManager = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
   __proto__: null,
   PwaCacheManager
 }, Symbol.toStringTag, { value: "Module" }));
@@ -11943,6 +12877,11 @@ class AvatarDownloader {
     __publicField(this, "baseAssetsPath");
     this.baseAssetsPath = baseAssetsPath;
   }
+  /**
+   * Load template resources from CharacterMeta flame CDN URLs
+   * Falls back to global CDN config if not provided by API
+   * @internal
+   */
   async loadTemplateResources(flameResources, progressCallback = null) {
     var _a, _b, _c, _d;
     await PwaCacheManager.checkTemplateCacheVersion();
@@ -12000,6 +12939,11 @@ class AvatarDownloader {
     await Promise.all(promises);
     return templateResources;
   }
+  /**
+   * Load global FLAME template resources from CDN
+   * Uses centralized FLAME CDN config (shared across all characters)
+   * @internal 供内部使用（测试、调试等场景），SDK 初始化默认使用本地打包的资源
+   */
   async loadGlobalFlameResources(progressCallback = null) {
     var _a;
     await PwaCacheManager.checkTemplateCacheVersion();
@@ -12065,6 +13009,10 @@ class AvatarDownloader {
       throw error;
     }
   }
+  /**
+   * Load camera settings from CharacterMeta (optional)
+   * @internal
+   */
   async loadCameraSettings(characterMeta) {
     var _a, _b;
     const cameraUrl = (_b = (_a = characterMeta.camera) == null ? void 0 : _a.resource) == null ? void 0 : _b.remote;
@@ -12087,6 +13035,10 @@ class AvatarDownloader {
       return void 0;
     }
   }
+  /**
+   * Load character data from CharacterMeta (iOS compatible)
+   * @internal
+   */
   async loadCharacterData(characterMeta, options) {
     var _a, _b, _c, _d, _e2, _f, _g, _h, _i2, _j;
     const { progressCallback = null } = options || {};
@@ -12189,6 +13141,10 @@ class AvatarDownloader {
     });
     return characterData;
   }
+  /**
+   * Preload all resources (template + character data + camera info + settings)
+   * @internal
+   */
   async preloadResources(characterMeta, options) {
     const { progressCallback = null } = options || {};
     const [characterData, preloadCameraSettings] = await Promise.all([
@@ -12210,6 +13166,13 @@ class AvatarDownloader {
       characterSettings: characterMeta.characterSettings
     };
   }
+  // ============ API Client Methods ============
+  /**
+   * Get AvatarKit SDK API Client (api.open.spatialwalk.top for cn, api.intl.spatialwalk.cloud for intl)
+   * Used for: character details and resource URLs (public endpoints, no auth required)
+   * Note: This endpoint does not require authentication, so we don't add X-App-Id or Authorization headers
+   * to avoid CORS preflight requests for simple GET requests
+   */
   getSdkApiClient() {
     return {
       async request(url, options = {}) {
@@ -12255,6 +13218,13 @@ class AvatarDownloader {
       }
     };
   }
+  /**
+   * Get single character by ID from AvatarKit SDK API (v2, iOS compatible)
+   * Domain: api.open.spatialwalk.top (cn) / api.intl.spatialwalk.cloud (intl)
+   * Auth: Public endpoint, no authentication required
+   * Returns CharacterMeta with nested resource structure
+   * @internal
+   */
   async getCharacterById(characterId) {
     var _a;
     const startTime = Date.now();
@@ -12288,7 +13258,7 @@ class AvatarDownloader {
     }
   }
 }
-const AvatarDownloader$1 = Object.freeze(Object.defineProperty({
+const AvatarDownloader$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
   __proto__: null,
   AvatarDownloader
 }, Symbol.toStringTag, { value: "Module" }));
@@ -12297,15 +13267,25 @@ const _AvatarManager = class _AvatarManager {
     __publicField(this, "avatarDownloader", null);
     __publicField(this, "avatarCache", /* @__PURE__ */ new Map());
     __publicField(this, "loadingPromises", /* @__PURE__ */ new Map());
+    // 下载队列：确保资源下载串行执行
     __publicField(this, "downloadQueue", []);
     __publicField(this, "isDownloading", false);
   }
+  /**
+   * Access via global singleton
+   */
   static get shared() {
     if (!this._instance) {
       this._instance = new _AvatarManager();
     }
     return this._instance;
   }
+  /**
+   * Load avatar
+   * @param id Avatar ID
+   * @param onProgress Progress callback
+   * @returns Promise<Avatar>
+   */
   async load(id, onProgress) {
     const loadingPromise = this.loadingPromises.get(id);
     if (loadingPromise) {
@@ -12354,6 +13334,9 @@ const _AvatarManager = class _AvatarManager {
     this.processDownloadQueue();
     return loadPromise;
   }
+  /**
+   * 处理下载队列（确保串行执行）
+   */
   async processDownloadQueue() {
     if (this.isDownloading || this.downloadQueue.length === 0) {
       return;
@@ -12371,6 +13354,9 @@ const _AvatarManager = class _AvatarManager {
       this.processDownloadQueue();
     }
   }
+  /**
+   * 执行实际的加载逻辑（私有方法）
+   */
   async doLoad(id, characterMeta, onProgress) {
     try {
       logger.log("[AvatarManager] Step 1: Downloading resources...");
@@ -12401,22 +13387,31 @@ const _AvatarManager = class _AvatarManager {
       throw error;
     }
   }
+  /**
+   * Get cached avatar
+   * @param id Avatar ID
+   * @returns Avatar instance, or undefined if not in cache
+   */
   retrieve(id) {
     return this.avatarCache.get(id);
   }
+  /**
+   * Clear cached avatar for specified ID
+   * @param id Avatar ID
+   */
   clear(id) {
     const removed = this.avatarCache.delete(id);
     if (removed) {
       logger.log(`[AvatarManager] Cleared avatar cache for id: ${id}`);
     }
   }
+  /**
+   * Clear all avatar cache and resource loader cache
+   */
   clearAll() {
     this.avatarCache.clear();
     logger.log("[AvatarManager] Cleared all avatar cache");
   }
-  clearCache() {
-    this.clearAll();
-  }
 };
 __publicField(_AvatarManager, "_instance", null);
 let AvatarManager = _AvatarManager;
@@ -12523,11 +13518,14 @@ class WebGLRenderer {
     __publicField(this, "splatCount");
     __publicField(this, "isInitialized");
     __publicField(this, "splatBufferSize");
+    // 跟踪当前 buffer 大小
+    // Render texture framebuffer
     __publicField(this, "framebuffer", null);
     __publicField(this, "renderTexture", null);
     __publicField(this, "depthBuffer", null);
     __publicField(this, "framebufferWidth", 0);
     __publicField(this, "framebufferHeight", 0);
+    // Blit shader for drawing render texture to screen
     __publicField(this, "blitShaderProgram", null);
     __publicField(this, "blitUniformLocations", { offset: null, scale: null, texture: null });
     __publicField(this, "blitAttributeLocations", { position: 0, texCoord: 0 });
@@ -12548,11 +13546,15 @@ class WebGLRenderer {
     this.splatBufferSize = 0;
     this.alpha = alpha;
   }
+  /**
+   * 初始化 WebGL 渲染器
+   */
   async initialize() {
     try {
       this.gl = this.canvas.getContext("webgl2", {
         antialias: false,
         alpha: this.alpha,
+        // 根据 isOpaque 设置透明度
         premultipliedAlpha: true,
         powerPreference: "high-performance",
         preserveDrawingBuffer: false
@@ -12572,6 +13574,9 @@ class WebGLRenderer {
       throw error;
     }
   }
+  /**
+   * 设置着色器位置
+   */
   setupShaderLocations() {
     const gl = this.gl;
     if (!gl)
@@ -12587,12 +13592,20 @@ class WebGLRenderer {
     };
     this.attributeLocations = {
       quadVertex: 0,
+      // a_quadVertex (共享四边形顶点)
       position: 1,
+      // a_position (实例化)
       color: 2,
+      // a_color (实例化)
       covA: 3,
+      // a_covA (实例化)
       covB: 4
+      // a_covB (实例化)
     };
   }
+  /**
+   * 设置 WebGL 渲染状态
+   */
   setupWebGLState() {
     const gl = this.gl;
     if (!gl)
@@ -12608,6 +13621,9 @@ class WebGLRenderer {
       this.backgroundColor[3]
     );
   }
+  /**
+   * 创建渲染缓冲区
+   */
   createBuffers() {
     const gl = this.gl;
     if (!gl)
@@ -12616,6 +13632,9 @@ class WebGLRenderer {
     this.splatBuffer = gl.createBuffer();
     this.createQuadVertexBuffer();
   }
+  /**
+   * 创建四边形顶点缓冲区（实例化渲染用）
+   */
   createQuadVertexBuffer() {
     const gl = this.gl;
     if (!gl)
@@ -12623,17 +13642,29 @@ class WebGLRenderer {
     const quadVertices = new Float32Array([
       -1,
       -1,
+      // 左下
       -1,
       1,
+      // 左上
       1,
       -1,
+      // 右下
       1,
       1
+      // 右上
     ]);
     this.quadVertexBuffer = gl.createBuffer();
     gl.bindBuffer(gl.ARRAY_BUFFER, this.quadVertexBuffer);
     gl.bufferData(gl.ARRAY_BUFFER, quadVertices, gl.STATIC_DRAW);
   }
+  /**
+   * 从已打包数据加载（零拷贝，GPU 优化路径）
+   * 🚀 性能优化版本：直接使用 WASM 输出的 packed 数据
+   * 🚀 Buffer 复用：避免每帧重新分配，使用 bufferSubData 更新
+   * @param packedData Float32Array [pos3, color4, cov6] x N 个点
+   * @param pointCount 点数
+   * @param _sortOrder WebGL 忽略此参数（已在 RenderSystem 中重排序）
+   */
   loadSplatsFromPackedData(packedData, pointCount, _sortOrder) {
     if (!this.isInitialized) {
       throw new Error("Renderer not initialized");
@@ -12641,6 +13672,9 @@ class WebGLRenderer {
     this.splatCount = pointCount;
     this.uploadToGPU(packedData);
   }
+  /**
+   * 上传数据到 GPU
+   */
   uploadToGPU(packedData) {
     const gl = this.gl;
     if (!gl)
@@ -12653,6 +13687,9 @@ class WebGLRenderer {
       gl.bufferSubData(gl.ARRAY_BUFFER, 0, packedData);
     }
   }
+  /**
+   * 设置实例化渲染顶点属性
+   */
   setupVertexAttributes() {
     const gl = this.gl;
     if (!gl)
@@ -12713,6 +13750,9 @@ class WebGLRenderer {
     );
     gl.vertexAttribDivisor(this.attributeLocations.covB, 1);
   }
+  /**
+   * 渲染一帧
+   */
   render(viewMatrix, projectionMatrix, screenSize, transform) {
     if (!this.isInitialized || this.splatCount === 0) {
       return;
@@ -12736,6 +13776,9 @@ class WebGLRenderer {
       this.render3DGS(gl, viewMatrix, projectionMatrix, screenSize, width, height);
     }
   }
+  /**
+   * 创建着色器程序
+   */
   createShaderProgram(gl) {
     const vertexShader = gl.createShader(gl.VERTEX_SHADER);
     if (!vertexShader)
@@ -12780,6 +13823,9 @@ class WebGLRenderer {
     gl.deleteShader(fragmentShader);
     return program;
   }
+  /**
+   * 更新背景颜色
+   */
   updateBackgroundColor(backgroundColor) {
     this.backgroundColor = backgroundColor;
     if (this.gl) {
@@ -12791,6 +13837,9 @@ class WebGLRenderer {
       );
     }
   }
+  /**
+   * 渲染 3DGS 场景（公共方法，用于直接渲染和渲染到 framebuffer）
+   */
   render3DGS(gl, viewMatrix, projectionMatrix, screenSize, width, height) {
     gl.viewport(0, 0, width, height);
     gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
@@ -12806,6 +13855,9 @@ class WebGLRenderer {
     this.setupVertexAttributes();
     gl.drawArraysInstanced(gl.TRIANGLE_STRIP, 0, 4, this.splatCount);
   }
+  /**
+   * 创建 framebuffer 和 render texture
+   */
   createFramebuffer(width, height) {
     const gl = this.gl;
     if (!gl)
@@ -12848,6 +13900,9 @@ class WebGLRenderer {
     this.framebufferWidth = width;
     this.framebufferHeight = height;
   }
+  /**
+   * 创建 blit shader（用于绘制 render texture 到屏幕）
+   */
   createBlitShader(gl) {
     const vertexShader = gl.createShader(gl.VERTEX_SHADER);
     if (!vertexShader)
@@ -12905,22 +13960,27 @@ class WebGLRenderer {
     this.blitVAO = gl.createVertexArray();
     gl.bindVertexArray(this.blitVAO);
     const quadData = new Float32Array([
+      // position (x, y), texCoord (u, v)
       -1,
       -1,
       0,
       0,
+      // 左下
       -1,
       1,
       0,
       1,
+      // 左上
       1,
       -1,
       1,
       0,
+      // 右下
       1,
       1,
       1,
       1
+      // 右上
     ]);
     this.blitQuadBuffer = gl.createBuffer();
     gl.bindBuffer(gl.ARRAY_BUFFER, this.blitQuadBuffer);
@@ -12931,6 +13991,9 @@ class WebGLRenderer {
     gl.vertexAttribPointer(this.blitAttributeLocations.texCoord, 2, gl.FLOAT, false, 16, 8);
     gl.bindVertexArray(null);
   }
+  /**
+   * 将 render texture 绘制到屏幕（应用 transform）
+   */
   blitToScreen(transform) {
     const gl = this.gl;
     if (!gl || !this.blitShaderProgram || !this.renderTexture || !this.blitVAO) {
@@ -12959,6 +14022,9 @@ class WebGLRenderer {
       gl.enable(gl.BLEND);
     }
   }
+  /**
+   * 清理资源
+   */
   dispose() {
     if (!this.gl)
       return;
@@ -13006,21 +14072,26 @@ class WebGPURenderer {
     __publicField(this, "context", null);
     __publicField(this, "renderPipeline", null);
     __publicField(this, "renderTexturePipeline", null);
+    // 用于渲染到 render texture
     __publicField(this, "quadVertexBuffer", null);
     __publicField(this, "uniformBuffer", null);
     __publicField(this, "uniformBindGroup", null);
+    // 🚀 间接索引渲染 buffers
     __publicField(this, "sortIndexBuffer", null);
     __publicField(this, "splatDataBuffer", null);
     __publicField(this, "storageBindGroup", null);
     __publicField(this, "bindGroupNeedsUpdate", false);
+    // 标记 bind group 是否需要更新
     __publicField(this, "splatCount", 0);
     __publicField(this, "presentationFormat", "bgra8unorm");
     __publicField(this, "alpha");
+    // Render texture framebuffer
     __publicField(this, "renderTexture", null);
     __publicField(this, "renderTextureView", null);
     __publicField(this, "depthTexture", null);
     __publicField(this, "framebufferWidth", 0);
     __publicField(this, "framebufferHeight", 0);
+    // Blit pipeline for drawing render texture to screen
     __publicField(this, "blitPipeline", null);
     __publicField(this, "blitUniformBuffer", null);
     __publicField(this, "blitQuadBuffer", null);
@@ -13029,6 +14100,9 @@ class WebGPURenderer {
     this.backgroundColor = backgroundColor || [0, 0, 0, 0];
     this.alpha = alpha;
   }
+  /**
+   * 初始化 WebGPU 渲染器
+   */
   async initialize() {
     const adapter = await navigator.gpu.requestAdapter({
       powerPreference: "high-performance"
@@ -13052,6 +14126,9 @@ class WebGPURenderer {
     await this.createRenderPipeline();
     await this.createBlitPipeline();
   }
+  /**
+   * 创建 Uniform Buffer
+   */
   createUniformBuffer() {
     if (!this.device)
       return;
@@ -13062,18 +14139,25 @@ class WebGPURenderer {
       usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
     });
   }
+  /**
+   * 创建四边形顶点缓冲区（实例化渲染用）
+   */
   createQuadVertexBuffer() {
     if (!this.device)
       return;
     const quadVertices = new Float32Array([
       -1,
       -1,
+      // 左下
       -1,
       1,
+      // 左上
       1,
       -1,
+      // 右下
       1,
       1
+      // 右上
     ]);
     this.quadVertexBuffer = this.device.createBuffer({
       label: "Quad Vertex Buffer",
@@ -13084,6 +14168,9 @@ class WebGPURenderer {
     new Float32Array(this.quadVertexBuffer.getMappedRange()).set(quadVertices);
     this.quadVertexBuffer.unmap();
   }
+  /**
+   * 创建 Render Pipeline
+   */
   async createRenderPipeline() {
     if (!this.device)
       return;
@@ -13106,11 +14193,13 @@ class WebGPURenderer {
       entries: [
         {
           binding: 0,
+          // sortIndices
           visibility: GPUShaderStage.VERTEX,
           buffer: { type: "read-only-storage" }
         },
         {
           binding: 1,
+          // splatData
           visibility: GPUShaderStage.VERTEX,
           buffer: { type: "read-only-storage" }
         }
@@ -13121,12 +14210,15 @@ class WebGPURenderer {
       bindGroupLayouts: [uniformBindGroupLayout, storageBindGroupLayout]
     });
     const vertexBufferLayouts = [
+      // Buffer 0: Quad vertices (per-vertex)
       {
         arrayStride: 8,
+        // 2 floats
         stepMode: "vertex",
         attributes: [
           {
             shaderLocation: 0,
+            // quadVertex
             offset: 0,
             format: "float32x2"
           }
@@ -13148,6 +14240,7 @@ class WebGPURenderer {
           {
             format: this.presentationFormat,
             blend: {
+              // 预乘 alpha 混合（匹配 alphaMode: 'premultiplied'）
               color: {
                 srcFactor: "one",
                 dstFactor: "one-minus-src-alpha",
@@ -13167,6 +14260,7 @@ class WebGPURenderer {
         stripIndexFormat: void 0
       },
       depthStencil: void 0
+      // 3DGS 不使用深度测试
     });
     this.uniformBindGroup = this.device.createBindGroup({
       label: "Uniform Bind Group",
@@ -13192,6 +14286,7 @@ class WebGPURenderer {
         targets: [
           {
             format: "rgba16float",
+            // 使用 16-bit float 格式
             blend: {
               color: {
                 srcFactor: "one",
@@ -13214,10 +14309,15 @@ class WebGPURenderer {
       depthStencil: {
         format: "depth24plus",
         depthWriteEnabled: false,
+        // 不写入深度
         depthCompare: "always"
+        // 总是通过深度测试（实际上不使用）
       }
     });
   }
+  /**
+   * 创建 Blit Pipeline（用于绘制 render texture 到屏幕）
+   */
   async createBlitPipeline() {
     if (!this.device)
       return;
@@ -13235,6 +14335,7 @@ class WebGPURenderer {
       entries: [
         {
           binding: 0,
+          // Uniforms
           visibility: GPUShaderStage.VERTEX,
           buffer: { type: "uniform" }
         }
@@ -13245,11 +14346,13 @@ class WebGPURenderer {
       entries: [
         {
           binding: 0,
+          // Texture
           visibility: GPUShaderStage.FRAGMENT,
           texture: {}
         },
         {
           binding: 1,
+          // Sampler
           visibility: GPUShaderStage.FRAGMENT,
           sampler: {}
         }
@@ -13265,22 +14368,27 @@ class WebGPURenderer {
       minFilter: "linear"
     });
     const quadData = new Float32Array([
+      // position (x, y), texCoord (u, v)
       -1,
       -1,
       0,
       0,
+      // 左下
       -1,
       1,
       0,
       1,
+      // 左上
       1,
       -1,
       1,
       0,
+      // 右下
       1,
       1,
       1,
       1
+      // 右上
     ]);
     this.blitQuadBuffer = this.device.createBuffer({
       label: "Blit Quad Buffer",
@@ -13299,6 +14407,7 @@ class WebGPURenderer {
         buffers: [
           {
             arrayStride: 16,
+            // 4 floats (2 position + 2 texCoord)
             stepMode: "vertex",
             attributes: [
               {
@@ -13321,6 +14430,7 @@ class WebGPURenderer {
         targets: [
           {
             format: this.presentationFormat,
+            // render texture 已经是最终渲染结果，直接覆盖，不需要混合
             blend: void 0
           }
         ]
@@ -13330,6 +14440,9 @@ class WebGPURenderer {
       }
     });
   }
+  /**
+   * 创建 render texture 和 depth texture
+   */
   createRenderTexture(width, height) {
     if (!this.device)
       return;
@@ -13343,6 +14456,7 @@ class WebGPURenderer {
       label: "Render Texture",
       size: [width, height],
       format: "rgba16float",
+      // 使用 16-bit float 以保持精度
       usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING
     });
     this.renderTextureView = this.renderTexture.createView();
@@ -13355,6 +14469,11 @@ class WebGPURenderer {
     this.framebufferWidth = width;
     this.framebufferHeight = height;
   }
+  /**
+   * 从已打包数据加载
+   * 🚀 间接索引渲染：packedData 是原始数据，sortOrder 是排序索引
+   * 🚀 完全消除 CPU 重排序开销
+   */
   loadSplatsFromPackedData(packedData, pointCount, sortOrder) {
     if (!this.device)
       throw new Error("Device not initialized");
@@ -13417,6 +14536,9 @@ class WebGPURenderer {
       }
     }
   }
+  /**
+   * 渲染一帧
+   */
   render(viewMatrix, projectionMatrix, screenSize, transform) {
     if (!this.device || !this.context || !this.renderPipeline)
       return;
@@ -13488,6 +14610,9 @@ class WebGPURenderer {
     }
     this.device.queue.submit([commandEncoder.finish()]);
   }
+  /**
+   * 将 render texture 绘制到屏幕（应用 transform）
+   */
   blitToScreen(commandEncoder, transform) {
     if (!this.device || !this.blitPipeline || !this.renderTextureView || !this.blitQuadBuffer || !this.blitUniformBuffer || !this.blitSampler) {
       logger.error(`[WebGPURenderer] Blit failed: device=${!!this.device}, pipeline=${!!this.blitPipeline}, texture=${!!this.renderTextureView}, buffer=${!!this.blitQuadBuffer}, uniform=${!!this.blitUniformBuffer}, sampler=${!!this.blitSampler}`);
@@ -13551,6 +14676,9 @@ class WebGPURenderer {
     blitPass.draw(4);
     blitPass.end();
   }
+  /**
+   * 更新 Uniform Buffer
+   */
   updateUniforms(viewMatrix, projectionMatrix, screenSize) {
     if (!this.device || !this.uniformBuffer)
       return;
@@ -13564,9 +14692,15 @@ class WebGPURenderer {
     uint32View[36] = 1;
     this.device.queue.writeBuffer(this.uniformBuffer, 0, uniformData);
   }
+  /**
+   * 更新背景颜色
+   */
   updateBackgroundColor(backgroundColor) {
     this.backgroundColor = backgroundColor;
   }
+  /**
+   * 清理资源
+   */
   dispose() {
     var _a, _b, _c, _d, _e2, _f, _g, _h, _i2;
     (_a = this.sortIndexBuffer) == null ? void 0 : _a.destroy();
@@ -13604,19 +14738,29 @@ class RenderSystem {
     __publicField(this, "canvas");
     __publicField(this, "options");
     __publicField(this, "backgroundColor");
+    // Camera configuration
     __publicField(this, "camera");
+    // Matrix cache (reuse buffers to avoid per-frame allocation)
     __publicField(this, "viewMatrix", new Float32Array(16));
     __publicField(this, "projectionMatrix", new Float32Array(16));
+    // Camera forward vector cache (reuse to avoid per-frame allocation)
     __publicField(this, "cachedForward", [0, 0, 1]);
     __publicField(this, "forwardCacheValid", false);
+    // Temporary vectors for view matrix calculation (reuse buffers)
     __publicField(this, "tempForward", [0, 0, 0]);
     __publicField(this, "tempRight", [0, 0, 0]);
     __publicField(this, "tempUp", [0, 0, 0]);
+    // Camera parameter cache for matrix update optimization
     __publicField(this, "cachedCameraParams", null);
     __publicField(this, "matricesCacheValid", false);
+    // 当前数据（GPU 格式：[pos3, color4, cov6] x N）
     __publicField(this, "originalPackedData", null);
+    // 性能统计
     __publicField(this, "renderTime", 0);
+    // 总渲染耗时
     __publicField(this, "sortTime", 0);
+    // 排序耗时
+    // Transform for render texture blit
     __publicField(this, "offsetX", 0);
     __publicField(this, "offsetY", 0);
     __publicField(this, "scale", 1);
@@ -13636,6 +14780,9 @@ class RenderSystem {
       aspect: 1
     };
   }
+  /**
+   * Initialize render system
+   */
   async initialize() {
     const { preferBackend, alpha = true } = this.options;
     const backgroundColor = this.backgroundColor;
@@ -13660,11 +14807,20 @@ class RenderSystem {
     logger.log("✅ Using WebGL renderer");
     this.updateCameraAspect();
   }
+  /**
+   * Load packed Splat data (zero-copy, GPU format)
+   * Directly receives WASM packed data
+   *
+   * @param packedData Float32Array [pos3, color4, cov6] x N points
+   */
   loadSplatsFromPackedData(packedData) {
     if (!this.renderer)
       throw new Error("Renderer not initialized");
     this.originalPackedData = packedData;
   }
+  /**
+   * 渲染一帧
+   */
   renderFrame() {
     if (!this.renderer || !this.originalPackedData)
       return;
@@ -13689,43 +14845,72 @@ class RenderSystem {
       this.viewMatrix,
       this.projectionMatrix,
       [this.canvas.width, this.canvas.height],
+      // 传递 transform（如果不需要 transform，则不传递，保持向后兼容）
       this.offsetX !== 0 || this.offsetY !== 0 || this.scale !== 1 ? { x: this.offsetX, y: this.offsetY, scale: this.scale } : void 0
     );
     const renderTime = performance.now() - startRender;
     this.renderTime = renderTime;
   }
+  /**
+   * Set transform for render texture blit
+   * @param x - Horizontal offset in normalized coordinates (-1 to 1, where -1 = left edge, 0 = center, 1 = right edge)
+   * @param y - Vertical offset in normalized coordinates (-1 to 1, where -1 = bottom edge, 0 = center, 1 = top edge)
+   * @param scale - Scale factor (1.0 = original size, 2.0 = double size, 0.5 = half size)
+   */
   setTransform(x2, y2, scale = 1) {
     logger.log(`[RenderSystem] Setting transform: x=${x2}, y=${y2}, scale=${scale}`);
     this.offsetX = x2;
     this.offsetY = y2;
     this.scale = scale;
   }
+  /**
+   * Get current transform
+   */
   getTransform() {
     return { x: this.offsetX, y: this.offsetY, scale: this.scale };
   }
+  /**
+   * Update camera parameters
+   */
   updateCamera(params) {
     Object.assign(this.camera, params);
     this.updateCameraAspect();
   }
+  /**
+   * Handle window resize
+   */
   handleResize() {
     this.updateCameraAspect();
     this.updateCameraMatrices();
   }
+  /**
+   * 获取当前使用的后端
+   */
   getBackend() {
     return this.backend;
   }
+  /**
+   * 更新背景颜色
+   */
   updateBackgroundColor(backgroundColor) {
     this.backgroundColor = backgroundColor;
     if (this.renderer && typeof this.renderer.updateBackgroundColor === "function") {
       this.renderer.updateBackgroundColor(backgroundColor);
     }
   }
+  /**
+   * Dispose resources
+   */
   dispose() {
     var _a;
     (_a = this.renderer) == null ? void 0 : _a.dispose();
     this.renderer = null;
     this.originalPackedData = null;
   }
+  // ========== Private Methods ==========
+  /**
+   * Check WebGPU support
+   */
   async checkWebGPUSupport() {
     if (!navigator.gpu)
       return false;
@@ -13736,10 +14921,16 @@ class RenderSystem {
       return false;
     }
   }
+  /**
+   * Update camera aspect ratio
+   */
   updateCameraAspect() {
     this.camera.aspect = this.canvas.width / this.canvas.height;
     this.matricesCacheValid = false;
   }
+  /**
+   * Update camera matrices (with caching to avoid unnecessary updates)
+   */
   updateCameraMatrices() {
     const { position, target, up, fov, aspect, near, far } = this.camera;
     const paramsChanged = !this.cachedCameraParams || this.cachedCameraParams.position[0] !== position[0] || this.cachedCameraParams.position[1] !== position[1] || this.cachedCameraParams.position[2] !== position[2] || this.cachedCameraParams.target[0] !== target[0] || this.cachedCameraParams.target[1] !== target[1] || this.cachedCameraParams.target[2] !== target[2] || this.cachedCameraParams.up[0] !== up[0] || this.cachedCameraParams.up[1] !== up[1] || this.cachedCameraParams.up[2] !== up[2] || this.cachedCameraParams.fov !== fov || this.cachedCameraParams.aspect !== aspect || this.cachedCameraParams.near !== near || this.cachedCameraParams.far !== far;
@@ -13776,6 +14967,9 @@ class RenderSystem {
     this.updateViewMatrix(position, target, up);
     this.matricesCacheValid = true;
   }
+  /**
+   * Get camera forward vector (cached version)
+   */
   getCameraForward() {
     if (this.forwardCacheValid) {
       return this.cachedForward;
@@ -13794,6 +14988,9 @@ class RenderSystem {
     this.forwardCacheValid = true;
     return this.cachedForward;
   }
+  /**
+   * Update perspective projection matrix (reuse buffer)
+   */
   updatePerspectiveMatrix(fov, aspect, near, far) {
     const fovYRadians = fov * Math.PI / 180;
     const f2 = 1 / Math.tan(fovYRadians / 2);
@@ -13816,6 +15013,12 @@ class RenderSystem {
     m2[14] = zs2 * near;
     m2[15] = 0;
   }
+  /**
+   * Update view matrix (directly update pre-allocated buffer to avoid per-frame allocation)
+   * Equivalent to: inverse(translation) * inverse(rotation) = T^(-1) * R^(-1)
+   * Where T is translation matrix, R is rotation matrix
+   * Uses reusable temporary vector buffers to avoid allocations
+   */
   updateViewMatrix(position, target, up) {
     this.tempForward[0] = target[0] - position[0];
     this.tempForward[1] = target[1] - position[1];
@@ -13925,17 +15128,26 @@ function createBezierEasing(x1, y1, x2, y2) {
   };
 }
 const BEZIER_CURVES = {
+  // jaw: 快速启动，平稳停止
   jaw: createBezierEasing(0.2, 0.8, 0.3, 1),
+  // expression: 平滑 S 曲线
   expression: createBezierEasing(0.4, 0, 0.2, 1),
+  // eye: 更柔和的 S 曲线
   eye: createBezierEasing(0.3, 0, 0.1, 1),
+  // neck: 慢启动，惯性停止
   neck: createBezierEasing(0.1, 0.2, 0.2, 1),
+  // global: 标准 ease-in-out
   global: createBezierEasing(0.42, 0, 0.58, 1)
 };
 const TIME_SCALE = {
   jaw: 2.5,
+  // 40% 时间完成
   expression: 1.6,
+  // 62.5% 时间完成
   eye: 1.3,
+  // 77% 时间完成
   neck: 1,
+  // 100% 时间完成
   global: 1
 };
 function bezierLerp(from, to2, progress) {
@@ -13975,35 +15187,55 @@ function generateTransitionFrames(from, to2, durationMs, fps = 25) {
   return frames;
 }
 class AvatarView {
+  /**
+   * Constructor
+   * Creates a unified AvatarController, internally composes network layer based on configuration
+   * @param avatar - Avatar instance
+   * @param container - Canvas container element (required)
+   */
   constructor(avatar, container) {
     __publicField(this, "avatarController");
     __publicField(this, "avatar");
+    // 首帧渲染回调
     __publicField(this, "onFirstRendering");
+    // Canvas and rendering
     __publicField(this, "canvas");
     __publicField(this, "renderSystem", null);
     __publicField(this, "isInitialized", false);
     __publicField(this, "cameraConfig", null);
+    // Rendering state machine
     __publicField(this, "renderingState", "idle");
+    // Realtime animation data
     __publicField(this, "currentKeyframes", []);
     __publicField(this, "lastRenderedFrameIndex", -1);
     __publicField(this, "lastRealtimeProtoFrame", null);
+    // Animation loop types
     __publicField(this, "idleAnimationLoopId", null);
     __publicField(this, "realtimeAnimationLoopId", null);
     __publicField(this, "resizeObserver", null);
     __publicField(this, "onWindowResize", () => this.handleResize());
+    // FPS 计算
     __publicField(this, "frameCount", 0);
     __publicField(this, "lastFpsUpdate", 0);
     __publicField(this, "currentFPS", 0);
+    // Transition animation data
     __publicField(this, "transitionKeyframes", []);
     __publicField(this, "transitionStartTime", 0);
     __publicField(this, "startTransitionDurationMs", 200);
+    // Idle -> Speaking 过渡时长
     __publicField(this, "endTransitionDurationMs", 1600);
+    // Speaking -> Idle 过渡时长
     __publicField(this, "cachedIdleFirstFrame", null);
     __publicField(this, "idleCurrentFrameIndex", 0);
+    // 当前正在播放的帧（统一用于所有过渡，无论处于什么状态）
     __publicField(this, "currentPlayingFrame", null);
+    // Character handle for multi-character support
     __publicField(this, "characterHandle", null);
     __publicField(this, "characterId");
+    // Unique ID for this character instance
+    // 纯渲染模式标志（阻止 idle 循环渲染）
     __publicField(this, "isPureRenderingMode", false);
+    // avatar_active 埋点相关
     __publicField(this, "avatarActiveTimer", null);
     __publicField(this, "AVATAR_ACTIVE_INTERVAL", 6e5);
     this.avatar = avatar;
@@ -14024,6 +15256,10 @@ class AvatarView {
     });
     this.setupControllerEventListeners();
   }
+  // 10分钟 = 600000ms
+  /**
+   * 对齐两端 Flame 维度：标量统一长度，expression 取最大长度并零填充
+   */
   alignFlamePair(from, to2) {
     const ensureLen = (arr, len) => {
       const a2 = Array.isArray(arr) ? arr.slice(0, len) : [];
@@ -14055,6 +15291,13 @@ class AvatarView {
     toFixed.expression = ensureLen(toFixed.expression, exprLen);
     return { from: fromFixed, to: toFixed };
   }
+  /**
+   * 生成并对齐过渡帧，确保首尾帧与起止帧完全一致
+   * @param from 起始帧
+   * @param to 目标帧
+   * @param durationMs 过渡时长（开头或结尾）
+   * @param useLinearInterpolation 是否使用线性插值（旧实现），true 用于 idle->speaking，false 用于 speaking->idle（使用 Bezier 曲线）
+   */
   generateAndAlignTransitionFrames(from, to2, durationMs, useLinearInterpolation = false) {
     const aligned = this.alignFlamePair(from, to2);
     let keyframes = useLinearInterpolation ? generateTransitionFramesLinear(
@@ -14075,6 +15318,9 @@ class AvatarView {
     keyframes[keyframes.length - 1] = aligned.to;
     return keyframes;
   }
+  /**
+   * 获取缓存的 Idle 首帧，如果未缓存则获取并缓存
+   */
   async getCachedIdleFirstFrame() {
     if (!this.cachedIdleFirstFrame) {
       const avatarCore = AvatarSDK.getAvatarCore();
@@ -14089,9 +15335,15 @@ class AvatarView {
     }
     return this.cachedIdleFirstFrame;
   }
+  /**
+   * Get controller (public interface)
+   */
   get controller() {
     return this.avatarController;
   }
+  /**
+   * 创建canvas元素
+   */
   createCanvas(container) {
     const canvas = document.createElement("canvas");
     const containerWidth = container.offsetWidth || 800;
@@ -14128,9 +15380,16 @@ class AvatarView {
     window.addEventListener("resize", this.onWindowResize);
     return canvas;
   }
+  /**
+   * 获取canvas元素（供外部访问）
+   * @internal
+   */
   getCanvas() {
     return this.canvas;
   }
+  /**
+   * 初始化视图系统
+   */
   async initializeView(avatar) {
     var _a;
     try {
@@ -14198,6 +15457,9 @@ class AvatarView {
       throw error;
     }
   }
+  /**
+   * 初始化渲染系统
+   */
   async initializeRenderSystem(cameraInfo) {
     this.cameraConfig = cameraInfo || this.getDefaultCameraConfig();
     if (cameraInfo) {
@@ -14209,15 +15471,23 @@ class AvatarView {
       canvas: this.canvas,
       camera: this.cameraConfig,
       backgroundColor: [0, 0, 0, 0],
+      // 透明背景
       alpha: true
+      // 启用 alpha 通道
     });
     await this.renderSystem.initialize();
     if (APP_CONFIG.debug)
       logger.log("[AvatarView] Render system initialized successfully");
   }
+  /**
+   * 获取默认相机配置
+   */
   getDefaultCameraConfig() {
     return { ...APP_CONFIG.camera };
   }
+  /**
+   * 根据资源解析最终的相机配置，优先使用角色设置，其次 camera.json
+   */
   resolveCameraConfig(resources) {
     var _a, _b;
     const defaultCamera = this.getDefaultCameraConfig();
@@ -14231,6 +15501,9 @@ class AvatarView {
     const source = characterCameraSettings ? "characterSettings" : "camera.json";
     return this.deriveCameraConfigFromSettings(candidateSettings, defaultCamera, source);
   }
+  /**
+   * 从角色设置中推导相机配置
+   */
   deriveCameraConfigFromSettings(cameraSettings, fallback, source) {
     const safeValue = (value, fallbackValue) => Number.isFinite(value) ? value : fallbackValue;
     const translationX = safeValue(cameraSettings.translationX, fallback.position[0]);
@@ -14268,10 +15541,12 @@ class AvatarView {
     const fov = hasCustomFov ? fovRadians * 180 / Math.PI : fallback.fov;
     const derivedCamera = {
       ...fallback,
+      // 自动继承 near/far 等配置（来自 APP_CONFIG.camera）
       position,
       target,
       up,
       fov
+      // near/far 从 fallback 继承，无需硬编码
     };
     logger.log("[AvatarView] Applied camera settings from resources", {
       source,
@@ -14285,6 +15560,9 @@ class AvatarView {
     });
     return derivedCamera;
   }
+  /**
+   * 渲染第一帧
+   */
   async renderFirstFrame() {
     var _a;
     if (!this.renderSystem) {
@@ -14316,6 +15594,9 @@ class AvatarView {
       throw new Error("Failed to compute first frame splat data");
     }
   }
+  /**
+   * 更新 FPS 统计（在 requestAnimationFrame 回调中调用）
+   */
   updateFPS() {
     this.frameCount++;
     const now = performance.now();
@@ -14325,10 +15606,16 @@ class AvatarView {
       this.lastFpsUpdate = now;
     }
   }
+  /**
+   * 初始化 FPS 计算
+   */
   initFPS() {
     this.frameCount = 0;
     this.lastFpsUpdate = performance.now();
   }
+  /**
+   * 开始idle动画循环
+   */
   startIdleAnimationLoop() {
     if (this.idleAnimationLoopId) {
       this.stopIdleAnimationLoop();
@@ -14388,6 +15675,9 @@ class AvatarView {
     if (APP_CONFIG.debug)
       logger.log("[AvatarView] Idle animation loop started");
   }
+  /**
+   * 开始实时对话动画循环
+   */
   startRealtimeAnimationLoop() {
     if (this.realtimeAnimationLoopId) {
       this.stopRealtimeAnimationLoop();
@@ -14412,10 +15702,16 @@ class AvatarView {
         if (state === "transitioningToSpeaking" || state === "transitioningToIdle") {
           if (this.transitionKeyframes.length === 0) {
             if (state === "transitioningToSpeaking") {
-              this.setState("speaking");
+              this.setState(
+                "speaking"
+                /* Speaking */
+              );
               this.avatarController.onTransitionComplete();
             } else if (state === "transitioningToIdle") {
-              this.setState("idle");
+              this.setState(
+                "idle"
+                /* Idle */
+              );
               this.stopRealtimeAnimationLoop();
               this.startIdleAnimationLoop();
               return;
@@ -14441,11 +15737,17 @@ class AvatarView {
           }
           if (progress >= 1) {
             if (state === "transitioningToSpeaking") {
-              this.setState("speaking");
+              this.setState(
+                "speaking"
+                /* Speaking */
+              );
               this.transitionKeyframes = [];
               this.avatarController.onTransitionComplete();
             } else if (state === "transitioningToIdle") {
-              this.setState("idle");
+              this.setState(
+                "idle"
+                /* Idle */
+              );
               this.transitionKeyframes = [];
               this.stopRealtimeAnimationLoop();
               this.startIdleAnimationLoop();
@@ -14453,7 +15755,10 @@ class AvatarView {
             }
           }
           if (state === "transitioningToSpeaking" && this.transitionStartTime > 0 && this.transitionKeyframes.length > 0 && elapsed >= this.startTransitionDurationMs + 100) {
-            this.setState("speaking");
+            this.setState(
+              "speaking"
+              /* Speaking */
+            );
             this.transitionKeyframes = [];
             this.avatarController.onTransitionComplete();
           }
@@ -14473,6 +15778,9 @@ class AvatarView {
     if (APP_CONFIG.debug)
       logger.log("[AvatarView] Realtime animation loop started");
   }
+  /**
+   * 停止idle动画循环
+   */
   stopIdleAnimationLoop() {
     if (this.idleAnimationLoopId) {
       cancelAnimationFrame(this.idleAnimationLoopId);
@@ -14481,6 +15789,9 @@ class AvatarView {
         logger.log("[AvatarView] Idle animation loop stopped");
     }
   }
+  /**
+   * 停止实时对话动画循环
+   */
   stopRealtimeAnimationLoop() {
     if (this.realtimeAnimationLoopId) {
       cancelAnimationFrame(this.realtimeAnimationLoopId);
@@ -14489,10 +15800,16 @@ class AvatarView {
         logger.log("[AvatarView] Realtime animation loop stopped");
     }
   }
+  /**
+   * 停止所有动画循环
+   */
   stopAllAnimationLoops() {
     this.stopIdleAnimationLoop();
     this.stopRealtimeAnimationLoop();
   }
+  /**
+   * 渲染实时帧（由播放层回调调用）
+   */
   renderRealtimeFrame(splatData, frameIndex) {
     if (!this.renderSystem || this.renderingState !== "speaking") {
       return;
@@ -14505,6 +15822,10 @@ class AvatarView {
       this.currentPlayingFrame = this.lastRealtimeProtoFrame;
     }
   }
+  /**
+   * 状态转换方法
+   * 统一管理状态转换，确保状态一致性
+   */
   setState(newState) {
     const oldState = this.renderingState;
     this.renderingState = newState;
@@ -14523,15 +15844,28 @@ class AvatarView {
       this.currentPlayingFrame = null;
     }
   }
+  /**
+   * 检查是否在实时播放状态（Speaking 或过渡到 Speaking）
+   */
   get isRealtimePlaying() {
     return this.renderingState === "speaking" || this.renderingState === "transitioningToSpeaking";
   }
+  /**
+   * 检查是否在过渡中
+   */
   get isTransitioning() {
     return this.renderingState === "transitioningToSpeaking" || this.renderingState === "transitioningToIdle";
   }
+  /**
+   * 检查过渡结束后是否回到 Idle
+   */
   get endToIdleAfterTransition() {
     return this.renderingState === "transitioningToIdle";
   }
+  /**
+   * 处理打断
+   * 打断时应该生成过渡动画，而不是直接跳回 Idle
+   */
   handleInterrupt() {
     const state = this.renderingState;
     if (state === "idle") {
@@ -14543,11 +15877,17 @@ class AvatarView {
     if (state === "speaking" || state === "transitioningToSpeaking") {
       this.stopRealtimeRendering();
     } else {
-      this.setState("idle");
+      this.setState(
+        "idle"
+        /* Idle */
+      );
       this.stopRealtimeAnimationLoop();
       this.startIdleAnimationLoop();
     }
   }
+  /**
+   * 设置 AvatarController 事件监听器
+   */
   setupControllerEventListeners() {
     this.avatarController.setupInternalEventListeners({
       onKeyframesUpdate: (keyframes) => {
@@ -14564,6 +15904,10 @@ class AvatarView {
       }
     });
   }
+  /**
+   * 准备实时渲染（生成过渡到 Speaking）
+   * 统一逻辑：从当前正在播放的帧 -> Speaking 第一帧
+   */
   async prepareRealtimeRendering(keyframes) {
     const state = this.renderingState;
     if ((state === "speaking" || state === "transitioningToSpeaking") && this.currentKeyframes.length > 0) {
@@ -14572,7 +15916,10 @@ class AvatarView {
     }
     this.stopIdleAnimationLoop();
     this.currentKeyframes = keyframes;
-    this.setState("transitioningToSpeaking");
+    this.setState(
+      "transitioningToSpeaking"
+      /* TransitioningToSpeaking */
+    );
     try {
       const avatarCore = AvatarSDK.getAvatarCore();
       if (avatarCore && keyframes.length > 0) {
@@ -14607,7 +15954,10 @@ class AvatarView {
         this.transitionStartTime = performance.now();
         this.currentPlayingFrame = null;
         if (this.transitionKeyframes.length === 0) {
-          this.setState("speaking");
+          this.setState(
+            "speaking"
+            /* Speaking */
+          );
           this.avatarController.onTransitionComplete();
         } else {
           if (APP_CONFIG.debug)
@@ -14617,12 +15967,18 @@ class AvatarView {
     } catch (e2) {
       logger.warn("[AvatarView] Transition generation failed:", e2 instanceof Error ? e2.message : String(e2));
       if (this.renderingState === "transitioningToSpeaking") {
-        this.setState("speaking");
+        this.setState(
+          "speaking"
+          /* Speaking */
+        );
         this.avatarController.onTransitionComplete();
       }
     }
     this.startRealtimeAnimationLoop();
   }
+  /**
+   * 开始实时渲染循环
+   */
   startRealtimeRendering() {
     if (APP_CONFIG.debug)
       logger.log("[AvatarView] Starting realtime rendering with", this.currentKeyframes.length, "frames");
@@ -14632,6 +15988,9 @@ class AvatarView {
       keyframesCount: this.currentKeyframes.length
     });
   }
+  /**
+   * 停止实时对话渲染
+   */
   stopRealtimeRendering() {
     var _a, _b;
     const state = this.renderingState;
@@ -14642,12 +16001,18 @@ class AvatarView {
       if (state === "transitioningToIdle") {
         return;
       }
-      this.setState("idle");
+      this.setState(
+        "idle"
+        /* Idle */
+      );
       this.stopRealtimeAnimationLoop();
       this.startIdleAnimationLoop();
       return;
     }
-    this.setState("transitioningToIdle");
+    this.setState(
+      "transitioningToIdle"
+      /* TransitioningToIdle */
+    );
     (_b = (_a = this.avatarController).onConversationState) == null ? void 0 : _b.call(_a, ConversationState.idle);
     (async () => {
       try {
@@ -14673,7 +16038,10 @@ class AvatarView {
           }
           if (!fromFrame) {
             logger.warn("[AvatarView] Cannot get current playing frame for transition to idle, fallback to idle frame");
-            this.setState("idle");
+            this.setState(
+              "idle"
+              /* Idle */
+            );
             this.stopRealtimeAnimationLoop();
             this.startIdleAnimationLoop();
             return;
@@ -14698,12 +16066,19 @@ class AvatarView {
         logger.warn("[AvatarView] Return transition generation failed:", e2 instanceof Error ? e2.message : String(e2));
       }
       if (this.renderingState === "transitioningToIdle") {
-        this.setState("idle");
+        this.setState(
+          "idle"
+          /* Idle */
+        );
         this.stopRealtimeAnimationLoop();
         this.startIdleAnimationLoop();
       }
     })();
   }
+  /**
+   * Cleanup view resources
+   * Closes avatarController and cleans up all related resources
+   */
   dispose() {
     if (APP_CONFIG.debug)
       logger.log("[AvatarView] Disposing avatar view...");
@@ -14717,7 +16092,10 @@ class AvatarView {
     }
     this.stopAllAnimationLoops();
     this.stopAvatarActiveHeartbeat();
-    this.setState("idle");
+    this.setState(
+      "idle"
+      /* Idle */
+    );
     this.cachedIdleFirstFrame = null;
     this.idleCurrentFrameIndex = 0;
     this.currentPlayingFrame = null;
@@ -14748,9 +16126,17 @@ class AvatarView {
     if (APP_CONFIG.debug)
       logger.log("[AvatarView] Avatar view disposed successfully");
   }
+  /**
+   * 获取相机配置
+   * @internal
+   */
   getCameraConfig() {
     return this.cameraConfig;
   }
+  /**
+   * 更新相机配置
+   * @internal
+   */
   updateCameraConfig(cameraConfig) {
     this.cameraConfig = cameraConfig;
     if (APP_CONFIG.debug)
@@ -14764,7 +16150,13 @@ class AvatarView {
       }
     }
   }
-  async renderFlame(flame, enableIdleRendering) {
+  /**
+   * Render specified keyframe (pure rendering mode, no audio-animation synchronization)
+   * Suitable for scenarios where external application controls audio playback and animation playback
+   * @param keyframeData - Keyframe data
+   * @param enableIdleRendering - Whether to enable idle loop rendering. true: Enable idle rendering and return immediately (skip this keyframe); false: Disable idle rendering and process keyframe (default)
+   */
+  async renderFlame(keyframeData, enableIdleRendering) {
     if (!this.isInitialized || !this.renderSystem) {
       throw new Error("AvatarView not initialized");
     }
@@ -14774,6 +16166,7 @@ class AvatarView {
     }
     this.isPureRenderingMode = true;
     try {
+      const flame = keyframeData;
       const processedFlame = this.avatarController.applyPostProcessingToFlame(flame);
       const wasmParams = convertProtoFlameToWasmParams(processedFlame);
       const avatarCore = AvatarSDK.getAvatarCore();
@@ -14793,7 +16186,14 @@ class AvatarView {
       throw error;
     }
   }
-  async generateTransitionFromIdle(toFlame, frameCount, transitionType = "start") {
+  /**
+   * Generate transition frame array from current idle frame to target keyframe (pure rendering mode)
+   * @param toKeyframeData - Target keyframe data
+   * @param frameCount - Number of transition frames
+   * @param transitionType - Transition type: 'start' means Idle -> toKeyframeData (start transition), 'end' means toKeyframeData -> Idle (end transition)
+   * @returns Transition frame array with length of frameCount
+   */
+  async generateTransitionFromIdle(toKeyframeData, frameCount, transitionType = "start") {
     if (!this.isInitialized) {
       throw new Error("AvatarView not initialized");
     }
@@ -14807,6 +16207,7 @@ class AvatarView {
     try {
       const idleParams = await avatarCore.getCurrentFrameParams(this.idleCurrentFrameIndex, this.characterId);
       const idleFrameProto = convertWasmParamsToProtoFlame(idleParams);
+      const toFlame = toKeyframeData;
       const toFlameWithPostProcessing = this.avatarController.applyPostProcessingToFlame(toFlame);
       const aligned = this.alignFlamePair(idleFrameProto, toFlameWithPostProcessing);
       const from = transitionType === "start" ? aligned.from : aligned.to;
@@ -14833,17 +16234,31 @@ class AvatarView {
       throw error;
     }
   }
+  /**
+   * 使用新的相机配置重新渲染当前帧（用于暂停状态下更新相机）
+   * 复用 AvatarController 的重新渲染逻辑，因为 renderCallback 会调用 renderRealtimeFrame，
+   * 而 renderRealtimeFrame 会使用已更新的相机配置（通过 renderSystem.updateCamera）
+   * @private
+   */
   async rerenderCurrentFrameWithNewCamera() {
     if (this.avatarController.state !== AvatarState.paused || this.renderingState !== "speaking" || !this.renderSystem) {
       return;
     }
     await this.avatarController.rerenderCurrentFrameIfPaused();
   }
+  /**
+   * 处理尺寸变化：通知渲染系统更新视口与投影
+   */
   handleResize() {
     if (this.renderSystem) {
       this.renderSystem.handleResize();
     }
   }
+  /**
+   * 获取渲染性能统计
+   * @returns 渲染性能统计数据，如果渲染系统未初始化则返回 null
+   * @internal Not part of public API yet
+   */
   getPerformanceStats() {
     if (!this.renderSystem || !this.isInitialized) {
       return null;
@@ -14853,8 +16268,19 @@ class AvatarView {
       sortTime: this.renderSystem.sortTime,
       backend: this.renderSystem.getBackend(),
       fps: this.currentFPS
+      // pointCount 可后续通过 AvatarCoreAdapter 添加公开方法获取
     };
   }
+  /**
+   * Get or set avatar transform in canvas
+   * 
+   * @example
+   * // Get current transform
+   * const current = avatarView.transform
+   * 
+   * // Set transform
+   * avatarView.transform = { x: 0.5, y: 0, scale: 2.0 }
+   */
   get transform() {
     if (!this.renderSystem) {
       throw new Error("Render system not initialized");
@@ -14872,6 +16298,10 @@ class AvatarView {
       this.renderSystem.renderFrame();
     }
   }
+  /**
+   * 上报 avatar_active 埋点
+   * @private
+   */
   reportAvatarActive() {
     var _a, _b;
     logEvent("avatar_active", "info", {
@@ -14880,6 +16310,10 @@ class AvatarView {
       dsm: ((_b = AvatarSDK.configuration) == null ? void 0 : _b.drivingServiceMode) || DrivingServiceMode.sdk
     });
   }
+  /**
+   * 启动 avatar_active 心跳埋点（每10分钟一次）
+   * @private
+   */
   startAvatarActiveHeartbeat() {
     this.stopAvatarActiveHeartbeat();
     this.avatarActiveTimer = window.setInterval(() => {
@@ -14888,6 +16322,10 @@ class AvatarView {
       }
     }, this.AVATAR_ACTIVE_INTERVAL);
   }
+  /**
+   * 停止 avatar_active 心跳埋点
+   * @private
+   */
   stopAvatarActiveHeartbeat() {
     if (this.avatarActiveTimer !== null) {
       clearInterval(this.avatarActiveTimer);