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

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

@@ -3,10 +3,11 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 class Avatar {
   /**
-   * 构造函数（内部使用）
-   * @param id 数字人 ID
-   * @param characterMeta 角色元数据
-   * @param resources 资源数据
+   * Constructor (internal use)
+   * @param id Avatar ID
+   * @param characterMeta Character metadata
+   * @param resources Resource data
+   * @internal
    */
   constructor(id, characterMeta, resources) {
     __publicField(this, "id");
@@ -24,7 +25,7 @@ class Avatar {
     return this.characterMeta;
   }
   /**
-   * 更新角色元数据（内部使用）
+   * Update character metadata (internal use)
    * @internal
    */
   updateCharacterMeta(newMeta) {
@@ -34,7 +35,7 @@ class Avatar {
     }
   }
   /**
-   * 获取资源数据（内部使用）
+   * Get resource data (internal use)
    * @internal
    */
   getResources() {
@@ -1433,14 +1434,14 @@ const APP_CONFIG = {
   },
   animation: {
     fps: 25
-    // 动画帧率（从 CharacterMeta 加载动画资源）
+    // Animation frame rate (load animation resources from CharacterMeta)
   },
   audio: {
     sampleRate: 16e3
-    // 音频采样率（后端要求 16kHz）
+    // Audio sample rate (backend requires 16kHz)
   },
-  // FLAME 全局模板资源 CDN
-  // 这些资源是所有角色共享的基础模板
+  // FLAME global template resource CDN
+  // These resources are base templates shared by all characters
   flame: {
     cdnBaseUrl: "https://cdn.spatialwalk.top/public",
     resources: {
@@ -7482,7 +7483,7 @@ class IdManager {
     });
     this.ids.clientId = getOrCreateClientId();
   }
-  // ========== 全局 ID ==========
+  // ========== Global IDs ==========
   getClientId() {
     return this.ids.clientId;
   }
@@ -7504,16 +7505,18 @@ class IdManager {
   getSessionToken() {
     return this.ids.sessionToken;
   }
-  // ========== 连接级别 ID ==========
+  // ========== Connection Level IDs ==========
   /**
-   * 生成新的 connectionId（用于 WebSocket 连接）
+   * Generate new connectionId (for WebSocket connection)
+   * @internal
    */
   generateConnectionId() {
     this.ids.connectionId = generateConversationId();
     return this.ids.connectionId;
   }
   /**
-   * 设置 connectionId（用于从服务器接收到的 connectionId）
+   * Set connectionId (for connectionId received from server)
+   * @internal
    */
   setConnectionId(connectionId) {
     this.ids.connectionId = connectionId;
@@ -7524,9 +7527,10 @@ class IdManager {
   clearConnectionId() {
     this.ids.connectionId = null;
   }
-  // ========== 会话级别 ID ==========
+  // ========== Session Level IDs ==========
   /**
-   * 生成新的 conversationId（用于每次对话）
+   * Generate new conversationId (for each conversation)
+   * @internal
    */
   generateNewConversationId() {
     this.ids.conversationId = generateConversationId();
@@ -7541,15 +7545,17 @@ class IdManager {
   clearConversationId() {
     this.ids.conversationId = null;
   }
-  // ========== 批量获取（用于 PostHog 日志）==========
+  // ========== Batch Get (for PostHog logging) ==========
   /**
-   * 获取所有 ID（用于日志上报）
+   * Get all IDs (for log reporting)
+   * @internal
    */
   getAllIds() {
     return { ...this.ids };
   }
   /**
-   * 获取公共日志参数（包含所有必要的 ID）
+   * Get public log parameters (contains all necessary IDs)
+   * @internal
    */
   getLogContext() {
     return {
@@ -7561,7 +7567,8 @@ class IdManager {
     };
   }
   /**
-   * 清理所有 ID（用于测试或重置）
+   * Clear all IDs (for testing or reset)
+   * @internal
    */
   clear() {
     this.ids.userId = null;
@@ -7604,15 +7611,15 @@ function initializePostHog(environment, version) {
       api_host: host,
       person_profiles: "identified_only",
       capture_pageview: false,
-      // SDK 不需要自动捕获页面浏览
+      // SDK doesn't need automatic page view capture
       capture_pageleave: false,
-      // SDK 不需要自动捕获页面离开
+      // SDK doesn't need automatic page leave capture
       disable_compression: disableCompression,
-      // 根据环境配置压缩：国内禁用，国外启用
+      // Configure compression based on environment: disabled in CN, enabled in INT
       disable_session_recording: true,
-      // 禁用 Session Recording，避免额外的请求和错误
+      // Disable Session Recording to avoid additional requests and errors
       autocapture: false,
-      // 禁用自动捕获，只上报 SDK 自定义事件
+      // Disable autocapture, only report SDK custom events
       loaded: (posthogInstance) => {
         logger.log(`[PostHog] Initialized successfully - environment: ${environment}, host: ${host}, instance: ${SDK_POSTHOG_INSTANCE_NAME}`);
         isInitialized = true;
@@ -7698,19 +7705,19 @@ function trackEvent(event, level = "info", contents = {}) {
   try {
     const logContext = idManager.getLogContext();
     const properties = {
-      // 基础属性
+      // Basic properties
       service_module: "sdk",
       platform: "Web",
       sdk_version: sdkVersion,
       level,
       environment: currentEnvironment || "unknown",
-      // ID 信息
+      // ID information
       app_id: logContext.app_id,
       user_id: logContext.user_id,
       client_id: logContext.client_id,
-      // 时间戳
+      // Timestamp
       timestamp: Date.now(),
-      // 自定义内容
+      // Custom contents
       ...contents
     };
     if (logContext.connection_id) {
@@ -7845,7 +7852,7 @@ const _AnimationPlayer = class _AnimationPlayer {
     if (this.streamingPlayer) {
       return;
     }
-    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-DiIRp5nx.js");
+    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-Bi2685bX.js");
     const { AvatarSDK: AvatarSDK2 } = await Promise.resolve().then(() => AvatarSDK$1);
     const audioFormat = AvatarSDK2.getAudioFormat();
     this.streamingPlayer = new StreamingAudioPlayer({
@@ -8039,7 +8046,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 预检
+        // GET request doesn't need Content-Type header, avoid triggering CORS preflight
       });
       if (!response.ok) {
         throw new Error(`HTTP ${response.status} ${response.statusText}`);
@@ -8486,17 +8493,18 @@ class AvatarCoreAdapter {
     };
   }
   /**
-   * 加载 WASM 模块并设置 API
-   * 每次都创建全新的 WASM 实例，确保 C++ 内存是干净的
+   * Load WASM module and setup API
+   * Creates a completely new WASM instance each time, ensuring C++ memory is clean
    * 
-   * 注意：这里使用动态 import() 导入 WASM 模块。
-   * Vite 在构建时会自动为 WASM 文件和 JS glue 代码添加 hash（如 avatar_core_wasm-CxWuw7eS.wasm），
-   * 确保浏览器缓存与版本一致，不会有缓存问题。
+   * Note: Uses dynamic import() to import WASM module.
+   * Vite automatically adds hash to WASM files and JS glue code during build (e.g., avatar_core_wasm-CxWuw7eS.wasm),
+   * ensuring browser cache is consistent with version, no cache issues.
    * 
-   * Hash 的作用机制：
-   * - WASM 文件内容变化 → hash 自动变化 → URL 变化 → 浏览器拉取新版本
-   * - WASM 文件内容不变 → hash 保持不变 → URL 不变 → 浏览器使用缓存
-   * - Emscripten 生成的 JS 内部会使用 hard-coded 的 hash 路径加载 .wasm 文件
+   * Hash mechanism:
+   * - WASM file content changes → hash automatically changes → URL changes → browser fetches new version
+   * - WASM file content unchanged → hash remains same → URL unchanged → browser uses cache
+   * - Emscripten-generated JS internally uses hard-coded hash path to load .wasm file
+   * @internal
    */
   async loadWASMModule() {
     try {
@@ -8516,7 +8524,8 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 验证 WASM 模块功能
+   * Validate WASM module functionality
+   * @internal
    */
   validateWASMModule() {
     const requiredFunctions = ["cwrap", "_malloc", "_free", "setValue", "getValue", "writeArrayToMemory"];
@@ -8528,7 +8537,8 @@ class AvatarCoreAdapter {
     this.initializeMemoryViews();
   }
   /**
-   * 初始化内存视图
+   * Initialize memory views
+   * @internal
    */
   initializeMemoryViews() {
     try {
@@ -8549,13 +8559,14 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 设置 C API 函数包装
+   * Setup C API function wrappers
+   * @internal
    */
   setupCAPIFunctions() {
     this.api = {
-      // 核心系统管理
+      // Core system management
       initialize: this.wasmModule.cwrap("avatar_core_initialize", "number", ["number"]),
-      // 返回 handle
+      // Returns 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"]),
@@ -8587,17 +8598,15 @@ class AvatarCoreAdapter {
       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 信息查询
+      // FLAME information query
       getFlameInfo: this.wasmModule.cwrap("avatar_core_get_flame_info", "number", ["number", "number", "number", "number"])
     };
   }
   /**
-   * 读取当前动画帧的 FlameParams（用于过渡或调试）
-   */
-  /**
-   * Get current frame parameters
+   * Get current frame parameters (for transitions or debugging)
    * @param frameIndex Frame index
    * @param characterId Optional character ID for multi-character support
+   * @internal
    */
   async getCurrentFrameParams(frameIndex = 0, characterId) {
     const paramsPtr = await this.getAnimationFrameParams(frameIndex, characterId);
@@ -8609,7 +8618,8 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 初始化 Avatar Core 核心
+   * Initialize Avatar Core
+   * @internal
    */
   async initializeAvatarCore(templateResources) {
     try {
@@ -8626,7 +8636,8 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 加载模板资源（从预加载的 ArrayBuffers）
+   * Load template resources (from preloaded ArrayBuffers)
+   * @internal
    */
   async loadTemplateResourcesFromBuffers(templateResources) {
     const formattedResources = {
@@ -8652,14 +8663,13 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 加载角色数据（从预加载的 ArrayBuffers）
-   */
-  /**
+   * Load character data (from preloaded 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
+   * @internal
    */
   async loadCharacterFromBuffers(shapeBuffer, pointCloudBuffer, characterId) {
     if (!this.isInitialized) {
@@ -8762,8 +8772,9 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 获取动画总帧数
+   * Get total animation frames
    * @param animationHandle Optional animation handle (for multi-character support)
+   * @internal
    */
   async getAnimationTotalFrames(animationHandle) {
     const handle = animationHandle || this.animationHandle;
@@ -8791,9 +8802,10 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 从动画中获取指定帧的参数
+   * Get specified frame parameters from animation
    * @param frameIndex Frame index
    * @param characterId Optional character ID for multi-character support
+   * @internal
    */
   async getAnimationFrameParams(frameIndex = 0, characterId) {
     const id = characterId || "default";
@@ -8832,9 +8844,10 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 设置眼部追踪配置（对齐 app 实现）
+   * Set eye tracking configuration (aligned with app implementation)
    * @param config Eye tracking configuration
    * @param characterId Optional character ID for multi-character support
+   * @internal
    */
   async setEyeTrackingConfig(config, characterId) {
     if (!this.isCharacterLoaded) {
@@ -8861,11 +8874,12 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 设置眼部追踪目标（高级功能）
+   * Set eye tracking target (advanced feature)
    * @param x Target X coordinate
    * @param y Target Y coordinate
    * @param z Target Z coordinate
    * @param characterId Optional character ID for multi-character support
+   * @internal
    */
   async setGazeTarget(x2, y2, z2, characterId) {
     if (!this.isCharacterLoaded) {
@@ -8887,7 +8901,8 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 重置眼部追踪
+   * Reset eye tracking
+   * @internal
    */
   async resetEyeTracking() {
     if (!this.isCharacterLoaded) {
@@ -8904,7 +8919,8 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 查询 FLAME 模型信息
+   * Query FLAME model information
+   * @internal
    */
   async queryFlameInfo() {
     try {
@@ -8931,7 +8947,8 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 查询角色信息
+   * Query character information
+   * @internal
    */
   async queryCharacterInfo() {
     try {
@@ -8954,7 +8971,8 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 检查错误码并抛出异常
+   * Check error code and throw exception
+   * @internal
    */
   checkError(errorCode, functionName) {
     if (errorCode !== 0) {
@@ -8965,7 +8983,8 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 更新进度回调
+   * Update progress callback
+   * @internal
    */
   async updateProgress(callback, message, progress) {
     if (callback && typeof callback === "function") {
@@ -8973,7 +8992,8 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 获取性能指标
+   * Get performance metrics
+   * @internal
    */
   getPerformanceMetrics() {
     var _a, _b;
@@ -8985,9 +9005,10 @@ class AvatarCoreAdapter {
     };
   }
   /**
-   * 获取角色的点云数量
-   * @param characterHandle 角色 handle（可选，默认使用当前角色）
-   * @returns 点云数量，如果角色未加载则返回 null
+   * Get character point cloud count
+   * @param characterHandle Character handle (optional, defaults to current character)
+   * @returns Point cloud count, or null if character not loaded
+   * @internal
    */
   getPointCount(characterHandle) {
     if (!this.isCharacterLoaded) {
@@ -9016,12 +9037,11 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 释放当前角色和动画资源（但保留 core）
-   */
-  /**
+   * Release current character and animation resources (but keep core)
    * Remove a specific character by handle
    * @param characterHandle Character handle to remove
    * @param characterId Optional character ID for cleanup
+   * @internal
    */
   removeCharacter(characterHandle, characterId) {
     try {
@@ -9056,7 +9076,8 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 释放所有资源（包括 core）
+   * Release all resources (including core)
+   * @internal
    */
   release() {
     try {
@@ -9081,29 +9102,29 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 兼容性接口：提供与 FlameComplete3DGSManager 相同的接口
+   * Compatibility interface: provides same interface as FlameComplete3DGSManager
+   * @internal
    */
-  // 兼容 loadFlameModel
+  // Compatible with loadFlameModel
   // eslint-disable-next-line ts/no-explicit-any
   async loadFlameModel(_modelData) {
     return true;
   }
-  // 兼容 load3DGSData
+  // Compatible with 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 frame and return GPU-friendly flat format (zero-copy, covariance pre-computed)
+   * 🚀 Performance optimized version:
+   * - C++ pre-computes covariance matrix
+   * - Zero-copy direct access to WASM memory
+   * - Direct output GPU format [pos3, color4, cov6]
    * Compute complete frame from animation
    * @param params Frame parameters
    * @param characterHandle Optional character handle (for multi-character support)
+   * @internal
    */
   async computeCompleteFrameFlat(params, characterHandle) {
     if (!this.isCharacterLoaded) {
@@ -9161,13 +9182,12 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 计算帧并返回 GPU 友好的 flat 格式（从 FLAME 参数）
-   * 🔑 用于 Realtime: 接受自定义 FLAME 参数并计算 Splat
-   */
-  /**
+   * Compute frame and return GPU-friendly flat format (from FLAME parameters)
+   * 🔑 Used for Realtime: accepts custom FLAME parameters and computes Splat
    * Compute frame from Flame parameters
    * @param flameParams Flame parameters
    * @param characterHandle Optional character handle (for multi-character support)
+   * @internal
    */
   async computeFrameFlatFromParams(flameParams, characterHandle) {
     if (!this.isCharacterLoaded) {
@@ -9212,8 +9232,9 @@ class AvatarCoreAdapter {
     }
   }
   /**
-   * 获取 WASM 内存使用情况（MB）
-   * @returns WASM 内存使用量（MB），如果模块未加载则返回 null
+   * Get WASM memory usage (MB)
+   * @returns WASM memory usage (MB), or null if module not loaded
+   * @internal
    */
   getWASMMemoryMB() {
     if (!this.wasmModule) {
@@ -9285,7 +9306,8 @@ class AvatarSDK {
     }
   }
   /**
-   * 初始化WASM模块（跟随整个SDK生命周期）
+   * Initialize WASM module (follows entire SDK lifecycle)
+   * @internal
    */
   static async initializeWASMModule() {
     try {
@@ -9322,8 +9344,9 @@ class AvatarSDK {
     }
   }
   /**
-   * 初始化模板资源（在SDK初始化时加载）
-   * 从全局 CDN 加载模板资源，失败时直接抛出错误，阻止SDK初始化
+   * Initialize template resources (loaded during SDK initialization)
+   * Load template resources from global CDN, throw error on failure to prevent SDK initialization
+   * @internal
    */
   static async initializeTemplateResources() {
     if (!this._avatarCore) {
@@ -9431,7 +9454,8 @@ class AvatarSDK {
     }
   }
   /**
-   * 从远程配置接口获取SDK配置（已简化，逻辑移到 config/sdk-config-loader.ts）
+   * Fetch SDK configuration from remote config endpoint (simplified, logic moved to config/sdk-config-loader.ts)
+   * @internal
    */
   static async _fetchSdkConfig() {
     try {
@@ -9472,7 +9496,7 @@ class AvatarSDK {
 }
 __publicField(AvatarSDK, "_isInitialized", false);
 __publicField(AvatarSDK, "_configuration", null);
-__publicField(AvatarSDK, "_version", "1.0.0-beta.69");
+__publicField(AvatarSDK, "_version", "1.0.0-beta.70");
 __publicField(AvatarSDK, "_avatarCore", null);
 __publicField(AvatarSDK, "_dynamicSdkConfig", null);
 const AvatarSDK$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
@@ -11185,8 +11209,8 @@ class NetworkLayer {
     });
   }
   /**
-   * 启动驱动服务心跳检测（每2分钟检查一次连接状态）
-   * @private
+   * Start driving service heartbeat check (check connection status every 2 minutes)
+   * @internal
    */
   startHeartbeatCheck() {
     this.stopHeartbeatCheck();
@@ -11198,8 +11222,8 @@ class NetworkLayer {
     this.setupVisibilityListener();
   }
   /**
-   * 停止驱动服务心跳检测
-   * @private
+   * Stop driving service heartbeat check
+   * @internal
    */
   stopHeartbeatCheck() {
     if (this.heartbeatTimer !== null) {
@@ -11210,9 +11234,9 @@ class NetworkLayer {
     this.heartbeatFailureCount = 0;
   }
   /**
-   * 执行心跳检查：检测 WebSocket 连接状态
-   * 如果连接失败 3 次，上报 heartbeat_failed 事件
-   * @private
+   * Perform heartbeat check: detect WebSocket connection status
+   * If connection fails 3 times, report heartbeat_failed event
+   * @internal
    */
   performHeartbeatCheck() {
     try {
@@ -11243,8 +11267,8 @@ class NetworkLayer {
     }
   }
   /**
-   * 设置页面可见性监听器（用于页面重新可见时立即执行心跳检查）
-   * @private
+   * Setup page visibility listener (for immediately performing heartbeat check when page becomes visible)
+   * @internal
    */
   setupVisibilityListener() {
     if (typeof window === "undefined" || typeof document === "undefined") {
@@ -11259,8 +11283,8 @@ class NetworkLayer {
     document.addEventListener("visibilitychange", this.visibilityChangeHandler);
   }
   /**
-   * 移除页面可见性监听器
-   * @private
+   * Remove page visibility listener
+   * @internal
    */
   removeVisibilityListener() {
     if (typeof window === "undefined" || typeof document === "undefined" || !this.visibilityChangeHandler) {
@@ -11387,7 +11411,7 @@ class AvatarController {
     return this.currentState;
   }
   /**
-   * 将内部 AvatarState 映射到外部 ConversationState
+   * Map internal AvatarState to external ConversationState
    * @internal
    */
   mapToConversationState(avatarState) {
@@ -11468,6 +11492,7 @@ class AvatarController {
   /**
    * Check if audio context is initialized
    * @throws AvatarError if audio context is not initialized
+   * @internal
    */
   checkAudioContextInitialized() {
     var _a;
@@ -11854,7 +11879,7 @@ class AvatarController {
   // ========== Internal Helper Methods ==========
   /**
    * Generate new conversation ID and log conversation started event
-   * @private
+   * @internal
    */
   generateAndLogNewConversationId() {
     const conversationId = idManager.generateNewConversationId();
@@ -11867,7 +11892,7 @@ class AvatarController {
   }
   /**
    * Clear playback data (keyframes, audio chunks, and playback state)
-   * @private
+   * @internal
    */
   clearPlaybackData() {
     this.currentKeyframes = [];
@@ -11891,7 +11916,7 @@ class AvatarController {
   }
   /**
    * Reset conversation ID state (for both network and external modes)
-   * @private
+   * @internal
    */
   resetConversationIdState() {
     if (this.networkLayer) {
@@ -11915,7 +11940,7 @@ class AvatarController {
   }
   /**
    * Get effective conversation ID (handles both SDK and host modes)
-   * @private
+   * @internal
    */
   getEffectiveConversationId() {
     var _a;
@@ -11978,8 +12003,8 @@ class AvatarController {
     }
   }
   /**
-   * 设置完整的 eye tracking 配置到 C++
-   * @private
+   * Set complete eye tracking configuration to C++
+   * @internal
    */
   async setEyeTrackingConfig(eyefocus) {
     const avatarCore = AvatarSDK.getAvatarCore();
@@ -12041,8 +12066,8 @@ class AvatarController {
     }
   }
   /**
-   * 重新渲染当前帧（用于暂停状态下更新后处理参数）
-   * @private
+   * Rerender current frame (for updating post-processing parameters when paused)
+   * @internal
    */
   async rerenderCurrentFrame() {
     await this.rerenderCurrentFrameIfPaused();
@@ -12105,6 +12130,7 @@ class AvatarController {
   // ========== Private Methods ==========
   /**
    * Start streaming playback (internal implementation)
+   * @internal
    */
   async startStreamingPlaybackInternal() {
     var _a, _b, _c;
@@ -12246,6 +12272,10 @@ class AvatarController {
     }
     return false;
   }
+  /**
+   * Start playback loop
+   * @internal
+   */
   startPlaybackLoop() {
     if (this.playbackLoopId) {
       return;
@@ -12340,6 +12370,7 @@ class AvatarController {
   }
   /**
    * Stop playback loop
+   * @internal
    */
   stopPlaybackLoop() {
     if (this.playbackLoopId) {
@@ -12349,10 +12380,10 @@ class AvatarController {
   }
   // ========== Audio Only Mode ==========
   /**
-   * 启用音频独立播放模式（当服务器错误或超时时调用）
-   * 此模式下，音频会独立播放，不依赖动画数据
-   * 一旦启用，本次会话后续的动画数据将被忽略
-   * @private
+   * Enable audio-only playback mode (called when server error or timeout occurs)
+   * In this mode, audio plays independently without animation data
+   * Once enabled, subsequent animation data in this session will be ignored
+   * @internal
    */
   enableAudioOnlyMode() {
     if (this.isAudioOnlyMode) {
@@ -12368,8 +12399,8 @@ class AvatarController {
     }
   }
   /**
-   * 音频独立播放（完全独立的逻辑，不影响正常播放流程）
-   * @private
+   * Audio-only playback (completely independent logic, does not affect normal playback flow)
+   * @internal
    */
   async startAudioOnlyPlayback() {
     var _a, _b;
@@ -12418,9 +12449,9 @@ class AvatarController {
     }
   }
   /**
-   * 音频监控循环（仅用于音频独立模式）
-   * 只检测音频是否结束，不进行动画渲染
-   * @private
+   * Audio monitoring loop (only for audio-only mode)
+   * Only detects if audio has ended, does not render animation
+   * @internal
    */
   startAudioMonitoringLoop() {
     if (this.playbackLoopId) {
@@ -12470,6 +12501,10 @@ class AvatarController {
    * Add audio chunk to buffer
    * Note: animationPlayer should already be initialized before calling this method
    */
+  /**
+   * Add audio chunk to buffer
+   * @internal
+   */
   addAudioChunkToBuffer(data, isLast) {
     if (!this.animationPlayer) {
       logger.warn("[AvatarController] animationPlayer is null in addAudioChunkToBuffer, this should not happen");
@@ -12485,6 +12520,10 @@ class AvatarController {
   /**
    * Event system
    */
+  /**
+   * Register event listener
+   * @internal
+   */
   registerEventListener(event, callback) {
     if (!this.eventListeners.has(event)) {
       this.eventListeners.set(event, /* @__PURE__ */ new Set());
@@ -12515,7 +12554,7 @@ class AvatarController {
   }
   /**
    * Apply post-processing parameters to animation parameters
-   * @private
+   * @internal
    */
   applyPostProcessingToParams(baseParams) {
     if (!this.postProcessingConfig) {
@@ -12591,9 +12630,9 @@ class AvatarController {
     return result2;
   }
   /**
-   * 上报 driving_service_latency 事件（Host 模式）
-   * 每轮会话只上报一次（在收到首帧时）
-   * @private
+   * Report driving_service_latency event (Host mode)
+   * Report once per session (when first frame is received)
+   * @internal
    */
   reportDrivingServiceLatency(conversationId) {
     if (!conversationId || this.playbackMode !== DrivingServiceMode.host) {
@@ -12636,19 +12675,22 @@ function errorToMessage(err) {
 }
 const _PwaCacheManager = class _PwaCacheManager {
   /**
-   * 检查是否支持 Cache API
+   * Check if Cache API is supported
+   * @internal
    */
   static isSupported() {
     return typeof caches !== "undefined";
   }
   /**
-   * 获取角色缓存名称
+   * Get character cache name
+   * @internal
    */
   static getCharacterCacheName(characterId) {
     return `${_PwaCacheManager.CHARACTER_CACHE_PREFIX}${characterId}${_PwaCacheManager.CHARACTER_CACHE_SUFFIX}`;
   }
   /**
-   * 从角色缓存获取资源
+   * Get character resource from cache
+   * @internal
    */
   static async getCharacterResource(characterId, url) {
     if (!_PwaCacheManager.isSupported()) {
@@ -12670,7 +12712,8 @@ const _PwaCacheManager = class _PwaCacheManager {
     }
   }
   /**
-   * 将角色资源写入缓存
+   * Put character resource into cache
+   * @internal
    */
   static async putCharacterResource(characterId, url, data) {
     if (!_PwaCacheManager.isSupported()) {
@@ -12692,7 +12735,8 @@ const _PwaCacheManager = class _PwaCacheManager {
     }
   }
   /**
-   * 从模板缓存获取资源
+   * Get template resource from cache
+   * @internal
    */
   static async getTemplateResource(url) {
     if (!_PwaCacheManager.isSupported()) {
@@ -12713,8 +12757,9 @@ const _PwaCacheManager = class _PwaCacheManager {
     }
   }
   /**
-   * 将模板资源写入缓存
-   * 模板资源不设置数量限制，永久保留直到版本更新
+   * Put template resource into cache
+   * Template resources have no quantity limit, permanently retained until version update
+   * @internal
    */
   static async putTemplateResource(url, data) {
     if (!_PwaCacheManager.isSupported()) {
@@ -12729,7 +12774,8 @@ const _PwaCacheManager = class _PwaCacheManager {
     }
   }
   /**
-   * 清理角色缓存
+   * Clear character cache
+   * @internal
    */
   static async clearCharacterCache(characterId) {
     if (!_PwaCacheManager.isSupported()) {
@@ -12744,9 +12790,10 @@ const _PwaCacheManager = class _PwaCacheManager {
     }
   }
   /**
-   * 检查模板缓存版本，如果版本变化则清理
-   * 使用独立的模板资源版本号（不依赖 SDK 版本），这样不同 SDK 版本可以共享相同模板资源的缓存
-   * @returns true 如果版本变化并清理了缓存，false 否则
+   * Check template cache version, clear cache if version changed
+   * Uses independent template resource version (not dependent on SDK version), allowing different SDK versions to share the same template resource cache
+   * @returns true if version changed and cache was cleared, false otherwise
+   * @internal
    */
   static async checkTemplateCacheVersion() {
     if (!_PwaCacheManager.isSupported()) {
@@ -12772,14 +12819,14 @@ const _PwaCacheManager = class _PwaCacheManager {
     }
   }
 };
-// 模板缓存版本（独立于 SDK 版本，当模板资源更新时需要手动更新此版本号）
+// Template cache version (independent of SDK version, manually update when template resources change)
 __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");
-// 角色缓存前缀和后缀
+// Character cache prefix and suffix
 __publicField(_PwaCacheManager, "CHARACTER_CACHE_PREFIX", "spatialwalk-sdk-character-");
 __publicField(_PwaCacheManager, "CHARACTER_CACHE_SUFFIX", "-cache");
-// 角色缓存 LRU 限制：最多 1000 个资源条目（支持约 250 个角色，每个角色 4 个资源）
+// Character cache LRU limit: maximum 1000 resource entries (supports ~250 characters, 4 resources per character)
 __publicField(_PwaCacheManager, "MAX_CHARACTER_CACHE_ENTRIES", 1e3);
 let PwaCacheManager = _PwaCacheManager;
 const pwaCacheManager = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
@@ -13335,7 +13382,8 @@ const _AvatarManager = class _AvatarManager {
     return loadPromise;
   }
   /**
-   * 处理下载队列（确保串行执行）
+   * Process download queue (ensure serial execution)
+   * @internal
    */
   async processDownloadQueue() {
     if (this.isDownloading || this.downloadQueue.length === 0) {
@@ -13355,7 +13403,8 @@ const _AvatarManager = class _AvatarManager {
     }
   }
   /**
-   * 执行实际的加载逻辑（私有方法）
+   * Execute actual loading logic (private method)
+   * @internal
    */
   async doLoad(id, characterMeta, onProgress) {
     try {
@@ -15128,26 +15177,26 @@ function createBezierEasing(x1, y1, x2, y2) {
   };
 }
 const BEZIER_CURVES = {
-  // jaw: 快速启动，平稳停止
+  // jaw: fast start, smooth stop
   jaw: createBezierEasing(0.2, 0.8, 0.3, 1),
-  // expression: 平滑 S 曲线
+  // expression: smooth S curve
   expression: createBezierEasing(0.4, 0, 0.2, 1),
-  // eye: 更柔和的 S 曲线
+  // eye: softer S curve
   eye: createBezierEasing(0.3, 0, 0.1, 1),
-  // neck: 慢启动，惯性停止
+  // neck: slow start, inertial stop
   neck: createBezierEasing(0.1, 0.2, 0.2, 1),
-  // global: 标准 ease-in-out
+  // global: standard ease-in-out
   global: createBezierEasing(0.42, 0, 0.58, 1)
 };
 const TIME_SCALE = {
   jaw: 2.5,
-  // 40% 时间完成
+  // 40% time to complete
   expression: 1.6,
-  // 62.5% 时间完成
+  // 62.5% time to complete
   eye: 1.3,
-  // 77% 时间完成
+  // 77% time to complete
   neck: 1,
-  // 100% 时间完成
+  // 100% time to complete
   global: 1
 };
 function bezierLerp(from, to2, progress) {
@@ -15258,7 +15307,8 @@ class AvatarView {
   }
   // 10分钟 = 600000ms
   /**
-   * 对齐两端 Flame 维度：标量统一长度，expression 取最大长度并零填充
+   * Align Flame dimensions at both ends: unify scalar lengths, take max length for expression and zero-pad
+   * @internal
    */
   alignFlamePair(from, to2) {
     const ensureLen = (arr, len) => {
@@ -15292,11 +15342,12 @@ class AvatarView {
     return { from: fromFixed, to: toFixed };
   }
   /**
-   * 生成并对齐过渡帧，确保首尾帧与起止帧完全一致
-   * @param from 起始帧
-   * @param to 目标帧
-   * @param durationMs 过渡时长（开头或结尾）
-   * @param useLinearInterpolation 是否使用线性插值（旧实现），true 用于 idle->speaking，false 用于 speaking->idle（使用 Bezier 曲线）
+   * Generate and align transition frames, ensuring first and last frames match start and end frames exactly
+   * @param from Start frame
+   * @param to Target frame
+   * @param durationMs Transition duration (start or end)
+   * @param useLinearInterpolation Whether to use linear interpolation (legacy implementation), true for idle->speaking, false for speaking->idle (uses Bezier curve)
+   * @internal
    */
   generateAndAlignTransitionFrames(from, to2, durationMs, useLinearInterpolation = false) {
     const aligned = this.alignFlamePair(from, to2);
@@ -15319,7 +15370,8 @@ class AvatarView {
     return keyframes;
   }
   /**
-   * 获取缓存的 Idle 首帧，如果未缓存则获取并缓存
+   * Get cached Idle first frame, fetch and cache if not cached
+   * @internal
    */
   async getCachedIdleFirstFrame() {
     if (!this.cachedIdleFirstFrame) {
@@ -15342,7 +15394,8 @@ class AvatarView {
     return this.avatarController;
   }
   /**
-   * 创建canvas元素
+   * Create canvas element
+   * @internal
    */
   createCanvas(container) {
     const canvas = document.createElement("canvas");
@@ -15388,7 +15441,8 @@ class AvatarView {
     return this.canvas;
   }
   /**
-   * 初始化视图系统
+   * Initialize view system
+   * @internal
    */
   async initializeView(avatar) {
     var _a;
@@ -15458,7 +15512,8 @@ class AvatarView {
     }
   }
   /**
-   * 初始化渲染系统
+   * Initialize render system
+   * @internal
    */
   async initializeRenderSystem(cameraInfo) {
     this.cameraConfig = cameraInfo || this.getDefaultCameraConfig();
@@ -15480,13 +15535,15 @@ class AvatarView {
       logger.log("[AvatarView] Render system initialized successfully");
   }
   /**
-   * 获取默认相机配置
+   * Get default camera configuration
+   * @internal
    */
   getDefaultCameraConfig() {
     return { ...APP_CONFIG.camera };
   }
   /**
-   * 根据资源解析最终的相机配置，优先使用角色设置，其次 camera.json
+   * Resolve final camera configuration from resources, prioritize character settings, then camera.json
+   * @internal
    */
   resolveCameraConfig(resources) {
     var _a, _b;
@@ -15502,7 +15559,8 @@ class AvatarView {
     return this.deriveCameraConfigFromSettings(candidateSettings, defaultCamera, source);
   }
   /**
-   * 从角色设置中推导相机配置
+   * Derive camera configuration from character settings
+   * @internal
    */
   deriveCameraConfigFromSettings(cameraSettings, fallback, source) {
     const safeValue = (value, fallbackValue) => Number.isFinite(value) ? value : fallbackValue;
@@ -15561,7 +15619,8 @@ class AvatarView {
     return derivedCamera;
   }
   /**
-   * 渲染第一帧
+   * Render first frame
+   * @internal
    */
   async renderFirstFrame() {
     var _a;
@@ -15595,7 +15654,8 @@ class AvatarView {
     }
   }
   /**
-   * 更新 FPS 统计（在 requestAnimationFrame 回调中调用）
+   * Update FPS statistics (called in requestAnimationFrame callback)
+   * @internal
    */
   updateFPS() {
     this.frameCount++;
@@ -15607,14 +15667,16 @@ class AvatarView {
     }
   }
   /**
-   * 初始化 FPS 计算
+   * Initialize FPS calculation
+   * @internal
    */
   initFPS() {
     this.frameCount = 0;
     this.lastFpsUpdate = performance.now();
   }
   /**
-   * 开始idle动画循环
+   * Start idle animation loop
+   * @internal
    */
   startIdleAnimationLoop() {
     if (this.idleAnimationLoopId) {
@@ -15676,7 +15738,8 @@ class AvatarView {
       logger.log("[AvatarView] Idle animation loop started");
   }
   /**
-   * 开始实时对话动画循环
+   * Start realtime conversation animation loop
+   * @internal
    */
   startRealtimeAnimationLoop() {
     if (this.realtimeAnimationLoopId) {
@@ -15779,7 +15842,8 @@ class AvatarView {
       logger.log("[AvatarView] Realtime animation loop started");
   }
   /**
-   * 停止idle动画循环
+   * Stop idle animation loop
+   * @internal
    */
   stopIdleAnimationLoop() {
     if (this.idleAnimationLoopId) {
@@ -15790,7 +15854,8 @@ class AvatarView {
     }
   }
   /**
-   * 停止实时对话动画循环
+   * Stop realtime conversation animation loop
+   * @internal
    */
   stopRealtimeAnimationLoop() {
     if (this.realtimeAnimationLoopId) {
@@ -15801,14 +15866,16 @@ class AvatarView {
     }
   }
   /**
-   * 停止所有动画循环
+   * Stop all animation loops
+   * @internal
    */
   stopAllAnimationLoops() {
     this.stopIdleAnimationLoop();
     this.stopRealtimeAnimationLoop();
   }
   /**
-   * 渲染实时帧（由播放层回调调用）
+   * Render realtime frame (called by playback layer callback)
+   * @internal
    */
   renderRealtimeFrame(splatData, frameIndex) {
     if (!this.renderSystem || this.renderingState !== "speaking") {
@@ -15823,8 +15890,9 @@ class AvatarView {
     }
   }
   /**
-   * 状态转换方法
-   * 统一管理状态转换，确保状态一致性
+   * State transition method
+   * Unified state transition management to ensure state consistency
+   * @internal
    */
   setState(newState) {
     const oldState = this.renderingState;
@@ -15845,26 +15913,30 @@ class AvatarView {
     }
   }
   /**
-   * 检查是否在实时播放状态（Speaking 或过渡到 Speaking）
+   * Check if in realtime playing state (Speaking or transitioning to Speaking)
+   * @internal
    */
   get isRealtimePlaying() {
     return this.renderingState === "speaking" || this.renderingState === "transitioningToSpeaking";
   }
   /**
-   * 检查是否在过渡中
+   * Check if in transition state
+   * @internal
    */
   get isTransitioning() {
     return this.renderingState === "transitioningToSpeaking" || this.renderingState === "transitioningToIdle";
   }
   /**
-   * 检查过渡结束后是否回到 Idle
+   * Check if will return to Idle after transition ends
+   * @internal
    */
   get endToIdleAfterTransition() {
     return this.renderingState === "transitioningToIdle";
   }
   /**
-   * 处理打断
-   * 打断时应该生成过渡动画，而不是直接跳回 Idle
+   * Handle interrupt
+   * When interrupted, should generate transition animation instead of directly jumping back to Idle
+   * @internal
    */
   handleInterrupt() {
     const state = this.renderingState;
@@ -15886,7 +15958,8 @@ class AvatarView {
     }
   }
   /**
-   * 设置 AvatarController 事件监听器
+   * Setup AvatarController event listeners
+   * @internal
    */
   setupControllerEventListeners() {
     this.avatarController.setupInternalEventListeners({
@@ -15905,8 +15978,9 @@ class AvatarView {
     });
   }
   /**
-   * 准备实时渲染（生成过渡到 Speaking）
-   * 统一逻辑：从当前正在播放的帧 -> Speaking 第一帧
+   * Prepare realtime rendering (generate transition to Speaking)
+   * Unified logic: from current playing frame -> Speaking first frame
+   * @internal
    */
   async prepareRealtimeRendering(keyframes) {
     const state = this.renderingState;
@@ -15977,7 +16051,8 @@ class AvatarView {
     this.startRealtimeAnimationLoop();
   }
   /**
-   * 开始实时渲染循环
+   * Start realtime rendering loop
+   * @internal
    */
   startRealtimeRendering() {
     if (APP_CONFIG.debug)
@@ -15989,7 +16064,8 @@ class AvatarView {
     });
   }
   /**
-   * 停止实时对话渲染
+   * Stop realtime conversation rendering
+   * @internal
    */
   stopRealtimeRendering() {
     var _a, _b;
@@ -16235,10 +16311,10 @@ class AvatarView {
     }
   }
   /**
-   * 使用新的相机配置重新渲染当前帧（用于暂停状态下更新相机）
-   * 复用 AvatarController 的重新渲染逻辑，因为 renderCallback 会调用 renderRealtimeFrame，
-   * 而 renderRealtimeFrame 会使用已更新的相机配置（通过 renderSystem.updateCamera）
-   * @private
+   * Rerender current frame with new camera configuration (for updating camera when paused)
+   * Reuses AvatarController's rerender logic, as renderCallback will call renderRealtimeFrame,
+   * which uses the updated camera configuration (via renderSystem.updateCamera)
+   * @internal
    */
   async rerenderCurrentFrameWithNewCamera() {
     if (this.avatarController.state !== AvatarState.paused || this.renderingState !== "speaking" || !this.renderSystem) {
@@ -16247,7 +16323,8 @@ class AvatarView {
     await this.avatarController.rerenderCurrentFrameIfPaused();
   }
   /**
-   * 处理尺寸变化：通知渲染系统更新视口与投影
+   * Handle size change: notify render system to update viewport and projection
+   * @internal
    */
   handleResize() {
     if (this.renderSystem) {
@@ -16299,8 +16376,8 @@ class AvatarView {
     }
   }
   /**
-   * 上报 avatar_active 埋点
-   * @private
+   * Report avatar_active event
+   * @internal
    */
   reportAvatarActive() {
     var _a, _b;
@@ -16311,8 +16388,8 @@ class AvatarView {
     });
   }
   /**
-   * 启动 avatar_active 心跳埋点（每10分钟一次）
-   * @private
+   * Start avatar_active heartbeat event (every 10 minutes)
+   * @internal
    */
   startAvatarActiveHeartbeat() {
     this.stopAvatarActiveHeartbeat();
@@ -16323,8 +16400,8 @@ class AvatarView {
     }, this.AVATAR_ACTIVE_INTERVAL);
   }
   /**
-   * 停止 avatar_active 心跳埋点
-   * @private
+   * Stop avatar_active heartbeat event
+   * @internal
    */
   stopAvatarActiveHeartbeat() {
     if (this.avatarActiveTimer !== null) {