@spatialwalk/avatarkit 1.0.0-beta.71 → 1.0.0-beta.73

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0-beta.73] - 2026-01-22
+
+### ✨ New Features
+- **Local Log Upload** - Automatic local log upload functionality
+
+## [1.0.0-beta.72] - 2026-01-17
+
+### 📚 Documentation
+- **README Optimization** - Enhanced README with authentication section and improved API documentation
+
 ## [1.0.0-beta.71] - 2026-01-17
 
 ### 🔧 Improvements

package/README.md

@@ -18,13 +18,34 @@ Real-time virtual avatar rendering SDK based on 3D Gaussian Splatting, supportin
 npm install @spatialwalk/avatarkit
 ```
 
-## 🔧 Vite 配置（推荐）
+## 🚀 Demo Repository
 
-如果你使用 Vite 作为构建工具，强烈推荐使用我们的 Vite 插件来自动处理 WASM 文件配置。插件会自动处理所有必要的配置，让你无需手动设置。
+<div align="center">
 
-### 使用插件
+### 📌 **Quick Start: Check Out Our Demo Repository**
 
-在 `vite.config.ts` 中添加插件：
+We provide complete example code and best practices to help you quickly integrate the SDK.
+
+**The demo repository includes:**
+- ✅ Complete integration examples
+- ✅ Usage examples for both SDK mode and Host mode  
+- ✅ Audio processing examples (PCM16, WAV, MP3, etc.)
+- ✅ Vite configuration examples
+- ✅ Best practices for common scenarios
+
+**[👉 View Demo Repository](https://github.com/spatialwalk/avatarkit-demo)** | *If not yet created, please contact the team*
+
+</div>
+
+---
+
+## 🔧 Vite Configuration (Recommended)
+
+If you are using Vite as your build tool, we strongly recommend using our Vite plugin to automatically handle WASM file configuration. The plugin automatically handles all necessary configurations, so you don't need to set them up manually.
+
+### Using the Plugin
+
+Add the plugin to `vite.config.ts`:
 
 ```typescript
 import { defineConfig } from 'vite'
@@ -32,27 +53,27 @@ import { avatarkitVitePlugin } from '@spatialwalk/avatarkit/vite'
 
 export default defineConfig({
   plugins: [
-    avatarkitVitePlugin(), // 添加这一行即可
+    avatarkitVitePlugin(), // Just add this line
   ],
 })
 ```
 
-### 插件功能
+### Plugin Features
 
-插件会自动处理：
+The plugin automatically handles:
 
-- ✅ **开发服务器**：自动设置 WASM 文件的正确 MIME 类型 (`application/wasm`)
-- ✅ **构建时**：自动复制 WASM 文件到 `dist/assets/` 目录
-  - 智能检测：从 JS glue 文件中提取引用的 WASM 文件名（包括 hash）
-  - 自动匹配：确保复制的 WASM 文件与 JS glue 文件中的引用匹配
-  - 支持 hash：正确处理带 hash 的 WASM 文件（如 `avatar_core_wasm-{hash}.wasm`）
-- ✅ **WASM JS Glue**：自动复制 WASM JS glue 文件到 `dist/assets/` 目录
-- ✅ **Cloudflare Pages**：自动生成 `_headers` 文件，确保 WASM 文件使用正确的 MIME 类型
-- ✅ **Vite 配置**：自动配置 `optimizeDeps`、`assetsInclude`、`assetsInlineLimit` 等选项
+- ✅ **Development Server**: Automatically sets the correct MIME type (`application/wasm`) for WASM files
+- ✅ **Build Time**: Automatically copies WASM files to `dist/assets/` directory
+  - Smart Detection: Extracts referenced WASM file names (including hash) from JS glue files
+  - Auto Matching: Ensures copied WASM files match references in JS glue files
+  - Hash Support: Correctly handles hashed WASM files (e.g., `avatar_core_wasm-{hash}.wasm`)
+- ✅ **WASM JS Glue**: Automatically copies WASM JS glue files to `dist/assets/` directory
+- ✅ **Cloudflare Pages**: Automatically generates `_headers` file to ensure WASM files use the correct MIME type
+- ✅ **Vite Configuration**: Automatically configures `optimizeDeps`, `assetsInclude`, `assetsInlineLimit`, and other options
 
-### 手动配置（不使用插件）
+### Manual Configuration (Without Plugin)
 
-如果你不使用 Vite 插件，需要手动配置以下内容：
+If you don't use the Vite plugin, you need to manually configure the following:
 
 ```typescript
 // vite.config.ts
@@ -74,7 +95,7 @@ export default defineConfig({
       },
     },
   },
-  // 开发服务器需要手动配置中间件设置 WASM MIME 类型
+  // Development server needs to manually configure middleware to set WASM MIME type
   configureServer(server) {
     server.middlewares.use((req, res, next) => {
       if (req.url?.endsWith('.wasm')) {
@@ -86,6 +107,53 @@ export default defineConfig({
 })
 ```
 
+## 🔐 Authentication
+
+All environments require an **App ID** and **Session Token** for authentication.
+
+### App ID
+
+The App ID is used to identify your application. You can obtain your App ID by:
+
+1. **For Testing**: Use the default test App ID provided in demo repositories (paired with test Session Token, only works with publicly available test avatars like Rohan, Dr.Kellan, Priya, Josh, etc.)
+2. **For Production**: Visit the [Developer Platform](https://dash.spatialreal.ai) to create your own App and avatars. You will receive your own App ID after creating an App.
+
+### Session Token
+
+The Session Token is required for WebSocket authentication and must be obtained from your SDK provider.
+
+**⚠️ Important Notes:**
+- The Session Token must be valid and not expired
+- In production applications, you **must** manually inject a valid Session Token obtained from your SDK provider
+- The default Session Token provided in demo repositories is **only for demonstration purposes** and can only be used with test avatars
+- If you want to create your own avatars and test them, please visit the [Developer Platform](https://dash.spatialreal.ai) to create your own App and generate Session Tokens
+
+**How to Set Session Token:**
+
+```typescript
+// Initialize SDK with App ID
+await AvatarSDK.initialize('your-app-id', configuration)
+
+// Set Session Token (can be called before or after initialization)
+// If called before initialization, the token will be automatically set when you initialize the SDK
+AvatarSDK.setSessionToken('your-session-token')
+
+// Get current Session Token
+const sessionToken = AvatarSDK.sessionToken
+```
+
+**Token Management:**
+- The Session Token can be set at any time using `AvatarSDK.setSessionToken(token)`
+- If you set the token before initializing the SDK, it will be automatically applied during initialization
+- If you set the token after initialization, it will be applied immediately
+- Handle token refresh logic in your application as needed (e.g., when token expires)
+
+**For Production Integration:**
+- Obtain a valid Session Token from your SDK provider
+- Store the token securely (never expose it in client-side code if possible)
+- Implement token refresh logic to handle token expiration
+- Use `AvatarSDK.setSessionToken(token)` to inject the token programmatically
+
 ## 🎯 Quick Start
 
 ### ⚠️ Important: Audio Context Initialization
@@ -126,8 +194,10 @@ const configuration: Configuration = {
 
 await AvatarSDK.initialize('your-app-id', configuration)
 
-// Set sessionToken (if needed, call separately)
-// AvatarSDK.setSessionToken('your-session-token')
+// Set Session Token (required for authentication)
+// You must obtain a valid Session Token from your SDK provider
+// See Authentication section above for more details
+AvatarSDK.setSessionToken('your-session-token')
 
 // 2. Load avatar
 const avatarManager = AvatarManager.shared
@@ -408,7 +478,9 @@ const appId = AvatarSDK.appId
 // Get configuration
 const config = AvatarSDK.configuration
 
-// Set sessionToken (if needed, call separately)
+// Set Session Token (required for authentication)
+// You must obtain a valid Session Token from your SDK provider
+// See Authentication section for more details
 AvatarSDK.setSessionToken('your-session-token')
 
 // Set userId (optional, for telemetry)
@@ -437,7 +509,7 @@ const manager = AvatarManager.shared
 
 // Load avatar
 const avatar = await manager.load(
-  characterId: string, 
+  id: string, 
   onProgress?: (progress: LoadProgressInfo) => void
 )
 
@@ -505,7 +577,7 @@ const newAvatar = await avatarManager.load('new-character-id')
 currentAvatarView = new AvatarView(newAvatar, container)
 
 // SDK mode: start connection (will throw error if not in SDK mode)
-  await currentAvatarView.controller.start()
+await currentAvatarView.controller.start()
 ```
 
 ### AvatarController
@@ -581,24 +653,30 @@ button.addEventListener('click', async () => {
 
 ```typescript
 
+// Pause playback (from playing state)
+avatarView.controller.pause()
+
+// Resume playback (from paused state)
+await avatarView.controller.resume()
+
 // Interrupt current playback (stops and clears data)
-avatarView.avatarController.interrupt()
+avatarView.controller.interrupt()
 
 // Clear all data and resources
-avatarView.avatarController.clear()
+avatarView.controller.clear()
 
 // Get current conversation ID (for Host mode)
-const conversationId = avatarView.avatarController.getCurrentConversationId()
+const conversationId = avatarView.controller.getCurrentConversationId()
 // Returns: Current conversationId for the active audio session, or null if no active session
 
 // Volume control (affects only avatar audio player, not system volume)
-avatarView.avatarController.setVolume(0.5)  // Set volume to 50% (0.0 to 1.0)
-const currentVolume = avatarView.avatarController.getVolume()  // Get current volume (0.0 to 1.0)
+avatarView.controller.setVolume(0.5)  // Set volume to 50% (0.0 to 1.0)
+const currentVolume = avatarView.controller.getVolume()  // Get current volume (0.0 to 1.0)
 
 // Set event callbacks
-avatarView.avatarController.onConnectionState = (state: ConnectionState) => {} // SDK mode only
-avatarView.avatarController.onConversationState = (state: ConversationState) => {}
-avatarView.avatarController.onError = (error: Error) => {}
+avatarView.controller.onConnectionState = (state: ConnectionState) => {} // SDK mode only
+avatarView.controller.onConversationState = (state: ConversationState) => {}
+avatarView.controller.onError = (error: Error) => {}
 ```
 
 #### Avatar Transform Methods
@@ -674,7 +752,7 @@ enum LogLevel {
     - Supported values: 8000, 16000, 22050, 24000, 32000, 44100, 48000
     - The configured sample rate will be used for both audio recording and playback
 - `characterApiBaseUrl`: Internal debug config, can be ignored
-- `sessionToken`: Set separately via `AvatarSDK.setSessionToken()`, not in Configuration
+- `sessionToken`: **Required for authentication**. Set separately via `AvatarSDK.setSessionToken()`, not in Configuration. See [Authentication](#-authentication) section for details
 
 ```typescript
 enum Environment {
@@ -734,7 +812,7 @@ enum ConversationState {
 The SDK supports two rendering backends:
 
 - **WebGPU** - High-performance rendering for modern browsers
-- **WebGL** - Better compatibility traditional rendering
+- **WebGL** - Better compatibility for traditional rendering
 
 The rendering system automatically selects the best backend, no manual configuration needed.
 
@@ -748,7 +826,7 @@ The SDK uses custom error types, providing more detailed error information:
 import { AvatarError } from '@spatialwalk/avatarkit'
 
 try {
-  await avatarView.avatarController.start()
+  await avatarView.controller.start()
 } catch (error) {
   if (error instanceof AvatarError) {
     console.error('SDK Error:', error.message, error.code)
@@ -761,7 +839,7 @@ try {
 ### Error Callbacks
 
 ```typescript
-avatarView.avatarController.onError = (error: Error) => {
+avatarView.controller.onError = (error: Error) => {
   console.error('AvatarController error:', error)
   // Handle error, such as reconnection, user notification, etc.
 }
@@ -777,14 +855,13 @@ avatarView.avatarController.onError = (error: Error) => {
 // Initialize
 const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
-await avatarView.avatarController.start()
+await avatarView.controller.start()
 
 // Use
-avatarView.avatarController.send(audioData, false)
+avatarView.controller.send(audioData, false)
 
-// Cleanup
-avatarView.avatarController.close()
-avatarView.dispose() // Automatically cleans up all resources
+// Cleanup - dispose() automatically cleans up all resources including WebSocket connections
+avatarView.dispose()
 ```
 
 #### Host Mode Lifecycle
@@ -795,19 +872,21 @@ const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
 
 // Use
-const conversationId = avatarView.avatarController.yieldAudioData(audioChunk, false)
-avatarView.avatarController.yieldFramesData(keyframesDataArray, conversationId) // keyframesDataArray: (Uint8Array | ArrayBuffer)[]
+const conversationId = avatarView.controller.yieldAudioData(audioChunk, false)
+avatarView.controller.yieldFramesData(keyframesDataArray, conversationId) // keyframesDataArray: (Uint8Array | ArrayBuffer)[]
 
-// Cleanup
-avatarView.avatarController.clear() // Clear all data and resources
-avatarView.dispose() // Automatically cleans up all resources
+// Cleanup - dispose() automatically cleans up all resources including playback data
+avatarView.dispose()
 ```
 
 **⚠️ Important Notes:** 
-- When disposing AvatarView instances, must call `dispose()` to properly clean up resources
-- Not properly cleaning up may cause resource leaks and rendering errors
-- In SDK mode, call `close()` before `dispose()` to properly close WebSocket connections
-- In Host mode, call `clear()` before `dispose()` to clear all playback data
+- `dispose()` automatically cleans up all resources, including:
+  - WebSocket connections (SDK mode)
+  - Playback data and animation resources (both modes)
+  - Render system and canvas elements
+  - All event listeners and callbacks
+- Not properly calling `dispose()` may cause resource leaks and rendering errors
+- If you need to manually close WebSocket connections or clear playback data before disposing, you can call `avatarView.controller.close()` (SDK mode) or `avatarView.controller.clear()` (both modes) first, but it's not required as `dispose()` handles this automatically
 
 ### Memory Optimization
 

package/dist/{StreamingAudioPlayer-D8Q8WiEg.js → StreamingAudioPlayer-C8IqtjfL.js}

@@ -1,7 +1,7 @@
 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);
-import { A as APP_CONFIG, l as logger, e as errorToMessage, a as logEvent } from "./index-U8QcNdma.js";
+import { A as APP_CONFIG, l as logger, e as errorToMessage, a as logEvent } from "./index-AtEuBzqP.js";
 class StreamingAudioPlayer {
   // Mark if AudioContext is being resumed, avoid concurrent resume requests
   constructor(options) {

package/dist/{index-U8QcNdma.js → index-AtEuBzqP.js}

@@ -7350,74 +7350,249 @@ class AvatarError extends Error {
     this.name = "AvatarError";
   }
 }
-{
-  setGlobalLogLevel(LogLevel$1.Warning);
-}
-const logger = useLogger("Web").withErrorProcessor((err) => {
-  captureErrorContext("error", err);
-  return err;
-}).useGlobalConfig();
-let originalLogger = null;
-function setLogLevel(level) {
-  switch (level) {
-    case LogLevel.off:
-      if (!originalLogger) {
-        originalLogger = { ...logger };
+const _LogSink = class _LogSink {
+  constructor() {
+    __publicField(this, "db", null);
+    __publicField(this, "dbName", "avatarkit_logs");
+    __publicField(this, "storeName", "logs");
+    __publicField(this, "version", 1);
+    __publicField(this, "trimThreshold", 5e3);
+    __publicField(this, "trimBufferSize", 1e3);
+    __publicField(this, "isFlushing", false);
+  }
+  static getInstance() {
+    if (!_LogSink.instance) {
+      _LogSink.instance = new _LogSink();
+    }
+    return _LogSink.instance;
+  }
+  /**
+   * Initialize IndexedDB
+   */
+  async initialize() {
+    if (this.db) {
+      return;
+    }
+    return new Promise((resolve2, reject) => {
+      const request = indexedDB.open(this.dbName, this.version);
+      request.onerror = () => {
+        reject(new Error("Failed to open IndexedDB"));
+      };
+      request.onsuccess = () => {
+        this.db = request.result;
+        resolve2();
+      };
+      request.onupgradeneeded = (event) => {
+        const db = event.target.result;
+        if (!db.objectStoreNames.contains(this.storeName)) {
+          const store = db.createObjectStore(this.storeName, { keyPath: "id", autoIncrement: true });
+          store.createIndex("ts", "ts", { unique: false });
+        }
+      };
+    });
+  }
+  /**
+   * Append log entry to IndexedDB
+   */
+  async append(entry) {
+    if (!this.db) {
+      try {
+        await this.initialize();
+      } catch {
+        return;
       }
-      Object.assign(logger, {
-        debug: () => {
-        },
-        verbose: () => {
-        },
-        log: () => {
-        },
-        warn: () => {
-        },
-        error: () => {
-        },
-        errorWithError: () => {
+    }
+    if (!this.db) {
+      return;
+    }
+    try {
+      const transaction = this.db.transaction([this.storeName], "readwrite");
+      const store = transaction.objectStore(this.storeName);
+      await new Promise((resolve2, reject) => {
+        const request = store.add(entry);
+        request.onsuccess = () => resolve2();
+        request.onerror = () => reject(new Error("Failed to add log"));
+      });
+      this.getCount().then((count) => {
+        if (count > this.trimThreshold) {
+          this.trim().catch(() => {
+          });
         }
+      }).catch(() => {
       });
-      break;
-    case LogLevel.error:
-      if (originalLogger) {
-        Object.assign(logger, originalLogger);
-        originalLogger = null;
+    } catch (error) {
+    }
+  }
+  /**
+   * Get total log count
+   */
+  async getCount() {
+    if (!this.db) {
+      return 0;
+    }
+    return new Promise((resolve2, reject) => {
+      const transaction = this.db.transaction([this.storeName], "readonly");
+      const store = transaction.objectStore(this.storeName);
+      const request = store.count();
+      request.onsuccess = () => {
+        resolve2(request.result);
+      };
+      request.onerror = () => {
+        reject(new Error("Failed to count logs"));
+      };
+    });
+  }
+  /**
+   * Trim logs to keep only recent entries
+   */
+  async trim() {
+    if (!this.db || this.isFlushing) {
+      return;
+    }
+    try {
+      const transaction = this.db.transaction([this.storeName], "readwrite");
+      const store = transaction.objectStore(this.storeName);
+      const getAllRequest = store.getAll();
+      const entries = await new Promise((resolve2, reject) => {
+        getAllRequest.onsuccess = () => {
+          resolve2(getAllRequest.result);
+        };
+        getAllRequest.onerror = () => {
+          reject(new Error("Failed to get logs"));
+        };
+      });
+      const keepCount = this.trimThreshold - this.trimBufferSize;
+      if (entries.length <= keepCount) {
+        return;
       }
-      setGlobalLogLevel(LogLevel$1.Error);
-      break;
-    case LogLevel.warning:
-      if (originalLogger) {
-        Object.assign(logger, originalLogger);
-        originalLogger = null;
+      entries.sort((a2, b2) => a2.ts - b2.ts);
+      const toDelete = entries.slice(0, entries.length - keepCount);
+      for (const entry of toDelete) {
+        if (entry.id !== void 0) {
+          await new Promise((resolve2, reject) => {
+            const deleteRequest = store.delete(entry.id);
+            deleteRequest.onsuccess = () => resolve2();
+            deleteRequest.onerror = () => reject(new Error("Failed to delete log"));
+          });
+        }
       }
-      setGlobalLogLevel(LogLevel$1.Warning);
-      break;
-    case LogLevel.all:
-      if (originalLogger) {
-        Object.assign(logger, originalLogger);
-        originalLogger = null;
+    } catch (error) {
+    }
+  }
+  /**
+   * Flush logs to server
+   */
+  async flush() {
+    if (!this.db || this.isFlushing) {
+      return;
+    }
+    this.isFlushing = true;
+    try {
+      const transaction = this.db.transaction([this.storeName], "readonly");
+      const store = transaction.objectStore(this.storeName);
+      const getAllRequest = store.getAll();
+      const entries = await new Promise((resolve2, reject) => {
+        getAllRequest.onsuccess = () => {
+          resolve2(getAllRequest.result);
+        };
+        getAllRequest.onerror = () => {
+          reject(new Error("Failed to get logs"));
+        };
+      });
+      if (entries.length === 0) {
+        this.isFlushing = false;
+        return;
       }
-      setGlobalLogLevel(LogLevel$1.Debug);
-      break;
-    default:
-      if (originalLogger) {
-        Object.assign(logger, originalLogger);
-        originalLogger = null;
+      const entriesWithPlatform = entries.map((entry) => ({
+        ...entry,
+        extra: {
+          ...entry.extra,
+          platform: "Web"
+        }
+      }));
+      const requestBody = { logs: entriesWithPlatform };
+      const jsonData = JSON.stringify(requestBody);
+      const gzippedData = await this.gzip(jsonData);
+      const response = await fetch("https://hogtool.spatialwalk.ai/batch-upload-log", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Encoding": "gzip"
+        },
+        body: gzippedData,
+        signal: AbortSignal.timeout(15e3)
+        // 15 second timeout
+      });
+      if (!response.ok) {
+        throw new Error(`Failed to upload logs: ${response.status} ${response.statusText}`);
       }
-      setGlobalLogLevel(LogLevel$1.Warning);
-      break;
+      await this.clearFirst(entries.length);
+    } catch (error) {
+      console.warn("[LogSink] Failed to flush logs:", error);
+      throw error;
+    } finally {
+      this.isFlushing = false;
+    }
   }
-}
-function captureErrorContext(level, error) {
-  const errorMessage = error instanceof Error ? error.message : String(error);
-  trackEvent("logger_error", level, {
-    error: errorMessage,
-    timestamp: Date.now(),
-    environment: "library",
-    user_agent: typeof navigator !== "undefined" ? navigator.userAgent : ""
-  });
-}
+  /**
+   * Clear first N log entries
+   */
+  async clearFirst(count) {
+    if (!this.db || count <= 0) {
+      return;
+    }
+    try {
+      const transaction = this.db.transaction([this.storeName], "readwrite");
+      const store = transaction.objectStore(this.storeName);
+      const getAllRequest = store.getAll();
+      const entries = await new Promise((resolve2, reject) => {
+        getAllRequest.onsuccess = () => {
+          resolve2(getAllRequest.result);
+        };
+        getAllRequest.onerror = () => {
+          reject(new Error("Failed to get logs"));
+        };
+      });
+      entries.sort((a2, b2) => a2.ts - b2.ts);
+      const toDelete = entries.slice(0, count);
+      for (const entry of toDelete) {
+        if (entry.id !== void 0) {
+          await new Promise((resolve2, reject) => {
+            const deleteRequest = store.delete(entry.id);
+            deleteRequest.onsuccess = () => resolve2();
+            deleteRequest.onerror = () => reject(new Error("Failed to delete log"));
+          });
+        }
+      }
+    } catch (error) {
+    }
+  }
+  /**
+   * Gzip string data
+   */
+  async gzip(data) {
+    try {
+      const encoder = new TextEncoder();
+      const encoded = encoder.encode(data);
+      const readableStream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(encoded);
+          controller.close();
+        }
+      });
+      const compressedStream = readableStream.pipeThrough(new CompressionStream("gzip"));
+      const response = new Response(compressedStream);
+      const blob = await response.blob();
+      return blob;
+    } catch (error) {
+      console.error("[LogSink] gzip() error:", error);
+      throw error;
+    }
+  }
+};
+__publicField(_LogSink, "instance", null);
+let LogSink = _LogSink;
+const logSink = LogSink.getInstance();
 const urlAlphabet = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
 let random = (bytes) => crypto.getRandomValues(new Uint8Array(bytes));
 let customRandom = (alphabet, defaultSize, getRandom) => {
@@ -7579,6 +7754,176 @@ class IdManager {
   }
 }
 const idManager = new IdManager();
+const ALGORITHM_TERMS = [
+  "flame",
+  "keyframe",
+  "keyframes",
+  "splat",
+  "splats",
+  "covariance",
+  "gaussian",
+  "cov6",
+  "packeddata",
+  "sortorder",
+  "sortindex",
+  "avatar_core",
+  "emscripten",
+  "wasm",
+  "blendshape",
+  "expressionparam",
+  "rig"
+];
+const ALGORITHM_REG = new RegExp(
+  `\\b(${ALGORITHM_TERMS.join("|")})\\b`,
+  "gi"
+);
+const CHINESE_REG = /[\u4e00-\u9fff\u3400-\u4dbf\uf900-\ufaff]/;
+const SENSITIVE_PATTERNS = [
+  { reg: /\b(token|sessiontoken|accesstoken|apikey|apisecret|secret|password|auth)=([^\s,}\]'"]+)/gi, replacement: "$1=***" },
+  { reg: /\b(conversationid|connectionid|clientid|sessionid)=([^\s,}\]'"]+)/gi, replacement: "$1=***" },
+  { reg: /\b(appid|app_id)=([^\s,}\]'"]+)/gi, replacement: "$1=***" },
+  { reg: /\b(userid|user_id)=([^\s,}\]'"]+)/gi, replacement: "$1=***" },
+  { reg: /(https?:\/\/)[^\s,}\]'"]+/gi, replacement: "$1***" },
+  { reg: /(wss?:\/\/)[^\s,}\]'"]+/gi, replacement: "$1***" }
+];
+function hasChinese(msg) {
+  return CHINESE_REG.test(msg);
+}
+function hasAlgorithmTerms(msg) {
+  return ALGORITHM_REG.test(msg);
+}
+function redactSensitive(msg) {
+  let out = msg;
+  for (const { reg, replacement } of SENSITIVE_PATTERNS) {
+    out = out.replace(reg, replacement);
+  }
+  return out;
+}
+function sanitizeForLocalLog(message) {
+  if (hasChinese(message) || hasAlgorithmTerms(message)) {
+    return { shouldPersist: false, sanitized: message };
+  }
+  return {
+    shouldPersist: true,
+    sanitized: redactSensitive(message)
+  };
+}
+{
+  setGlobalLogLevel(LogLevel$1.Warning);
+}
+const baseLogger = useLogger("Web").withErrorProcessor((err) => {
+  captureErrorContext("error", err);
+  return err;
+}).useGlobalConfig();
+logSink.initialize().catch(() => {
+});
+let currentLogLevel = LogLevel.off;
+async function writeToLocalLog(message, level, extra = {}) {
+  try {
+    const { shouldPersist, sanitized } = sanitizeForLocalLog(message);
+    if (!shouldPersist) {
+      return;
+    }
+    const { AvatarSDK: AvatarSDK2 } = await Promise.resolve().then(() => AvatarSDK$1);
+    const version = AvatarSDK2.version;
+    const appId = idManager.getAppId();
+    const userId = idManager.getUserId();
+    const logEntry = {
+      level,
+      ts: Date.now(),
+      msg: sanitized,
+      extra: {
+        ...extra,
+        _category: "Web",
+        sdk_version: version || "",
+        app_id: appId || "",
+        user_id: userId || "",
+        platform: "Web",
+        framework: "",
+        framework_version: ""
+      }
+    };
+    await logSink.append(logEntry);
+  } catch {
+  }
+}
+function formatConsoleMessage(message) {
+  return `[AvatarKit] ${message}`;
+}
+const logger = {
+  debug: (message, ...args) => {
+    writeToLocalLog(message, "info", {}).catch(() => {
+    });
+    if (currentLogLevel === LogLevel.all) {
+      baseLogger.debug(formatConsoleMessage(message), ...args);
+    }
+  },
+  verbose: (message, ...args) => {
+    writeToLocalLog(message, "info", {}).catch(() => {
+    });
+    if (currentLogLevel === LogLevel.all) {
+      baseLogger.verbose(formatConsoleMessage(message), ...args);
+    }
+  },
+  log: (message, ...args) => {
+    writeToLocalLog(message, "info", {}).catch(() => {
+    });
+    if (currentLogLevel === LogLevel.all) {
+      baseLogger.log(formatConsoleMessage(message), ...args);
+    }
+  },
+  warn: (message, ...args) => {
+    writeToLocalLog(message, "warn", {}).catch(() => {
+    });
+    if (currentLogLevel === LogLevel.warning || currentLogLevel === LogLevel.all) {
+      baseLogger.warn(formatConsoleMessage(message), ...args);
+    }
+  },
+  error: (message, ..._args) => {
+    writeToLocalLog(message, "error", {}).catch(() => {
+    });
+    if (currentLogLevel !== LogLevel.off) {
+      baseLogger.error(formatConsoleMessage(message));
+    }
+  },
+  errorWithError: (message, error) => {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    writeToLocalLog(`${message}: ${errorMessage}`, "error", {}).catch(() => {
+    });
+    if (currentLogLevel !== LogLevel.off) {
+      baseLogger.errorWithError(formatConsoleMessage(message), error);
+    }
+  }
+};
+function setLogLevel(level) {
+  currentLogLevel = level;
+  switch (level) {
+    case LogLevel.off:
+      setGlobalLogLevel(LogLevel$1.Error);
+      break;
+    case LogLevel.error:
+      setGlobalLogLevel(LogLevel$1.Error);
+      break;
+    case LogLevel.warning:
+      setGlobalLogLevel(LogLevel$1.Warning);
+      break;
+    case LogLevel.all:
+      setGlobalLogLevel(LogLevel$1.Debug);
+      break;
+    default:
+      setGlobalLogLevel(LogLevel$1.Warning);
+      break;
+  }
+}
+function captureErrorContext(level, error) {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  trackEvent("logger_error", level, {
+    error: errorMessage,
+    timestamp: Date.now(),
+    environment: "library",
+    user_agent: typeof navigator !== "undefined" ? navigator.userAgent : ""
+  });
+}
 let sdkVersion = "1.0.0";
 let currentEnvironment = null;
 let isInitialized = false;
@@ -7593,10 +7938,26 @@ function shouldFilterHostname() {
   const hostname = window.location.hostname;
   return FILTERED_HOSTNAMES.includes(hostname);
 }
+function getCommonFields() {
+  const logContext = idManager.getLogContext();
+  return {
+    platform: "Web",
+    sdk_version: sdkVersion,
+    environment: currentEnvironment || "unknown",
+    app_id: logContext.app_id || "",
+    user_id: logContext.user_id || "",
+    // 没有就传空字符串
+    client_id: logContext.client_id,
+    framework: "",
+    // Web native 传空字符串
+    framework_version: ""
+    // Web native 传空字符串
+  };
+}
 function initializePostHog(environment, version) {
-  if (shouldFilterHostname()) {
-    logger.log(`[PostHog] Tracking disabled due to filtered hostname: ${window.location.hostname}`);
-    return;
+  const isHostnameFiltered = shouldFilterHostname();
+  if (isHostnameFiltered) {
+    logger.log(`[PostHog] Event tracking disabled due to filtered hostname: ${window.location.hostname}, but PostHog will still be initialized for feature flags`);
   }
   const { host, apiKey, disableCompression } = getPostHogConfig();
   if (isInitialized) {
@@ -7624,23 +7985,13 @@ function initializePostHog(environment, version) {
         logger.log(`[PostHog] Initialized successfully - environment: ${environment}, host: ${host}, instance: ${SDK_POSTHOG_INSTANCE_NAME}`);
         isInitialized = true;
         sdkPosthogInstance = posthogInstance;
+        const userProperties = getCommonFields();
         if (logContext.user_id) {
-          posthogInstance.identify(logContext.user_id, {
-            app_id: logContext.app_id,
-            client_id: logContext.client_id,
-            sdk_version: sdkVersion,
-            platform: "Web",
-            environment
-          });
+          posthogInstance.identify(logContext.user_id, userProperties);
         } else {
-          posthogInstance.register({
-            app_id: logContext.app_id,
-            client_id: logContext.client_id,
-            sdk_version: sdkVersion,
-            platform: "Web",
-            environment
-          });
+          posthogInstance.register(userProperties);
         }
+        posthogInstance.setPersonPropertiesForFlags(userProperties);
         flushEventQueue();
       }
     }, SDK_POSTHOG_INSTANCE_NAME);
@@ -7660,6 +8011,50 @@ function getSdkPosthogInstance() {
     return null;
   }
 }
+async function getLogsFeatureFlag() {
+  let instance = getSdkPosthogInstance();
+  if (!instance) {
+    const maxWaitTime = 5e3;
+    const checkInterval = 100;
+    const startTime = Date.now();
+    while (!instance && Date.now() - startTime < maxWaitTime) {
+      await new Promise((resolve2) => setTimeout(resolve2, checkInterval));
+      instance = getSdkPosthogInstance();
+    }
+  }
+  if (!instance) {
+    logger.log("[PostHog] PostHog not initialized after waiting, logs feature flag disabled (default: false)");
+    return false;
+  }
+  try {
+    const commonFields = getCommonFields();
+    instance.setPersonPropertiesForFlags(commonFields);
+    instance.reloadFeatureFlags();
+    await new Promise((resolve2) => {
+      instance.onFeatureFlags((_flags, _variants, { errorsLoading } = {}) => {
+        if (errorsLoading) {
+          logger.warn("[PostHog] Error loading feature flags");
+        }
+        resolve2();
+      });
+    });
+    const flagValue = instance.isFeatureEnabled("logs_feature_flag");
+    const isEnabled = flagValue === true;
+    logger.log(`[PostHog] Logs feature flag: ${isEnabled ? "enabled" : "disabled"}`);
+    return isEnabled;
+  } catch (error) {
+    logger.warn("[PostHog] Failed to get logs feature flag:", error instanceof Error ? error.message : String(error));
+    return false;
+  }
+}
+function updatePostHogPersonPropertiesForFlags() {
+  const instance = getSdkPosthogInstance();
+  if (!instance) {
+    return;
+  }
+  const commonFields = getCommonFields();
+  instance.setPersonPropertiesForFlags(commonFields);
+}
 function flushEventQueue() {
   if (!sdkPosthogInstance || eventQueue.length === 0) {
     return;
@@ -7669,15 +8064,11 @@ function flushEventQueue() {
     for (const { event, level, contents } of eventQueue) {
       try {
         const logContext = idManager.getLogContext();
+        const commonFields = getCommonFields();
         const properties = {
-          service_module: "sdk",
-          platform: "Web",
-          sdk_version: sdkVersion,
+          ...commonFields,
           level,
-          environment: currentEnvironment || "unknown",
-          app_id: logContext.app_id,
-          user_id: logContext.user_id,
-          client_id: logContext.client_id,
+          service_module: "sdk",
           timestamp: Date.now(),
           ...contents
         };
@@ -7704,20 +8095,12 @@ function trackEvent(event, level = "info", contents = {}) {
   sdkPosthogInstance = instance;
   try {
     const logContext = idManager.getLogContext();
+    const commonFields = getCommonFields();
     const properties = {
-      // Basic properties
-      service_module: "sdk",
-      platform: "Web",
-      sdk_version: sdkVersion,
+      ...commonFields,
       level,
-      environment: currentEnvironment || "unknown",
-      // ID information
-      app_id: logContext.app_id,
-      user_id: logContext.user_id,
-      client_id: logContext.client_id,
-      // Timestamp
+      service_module: "sdk",
       timestamp: Date.now(),
-      // Custom contents
       ...contents
     };
     if (logContext.connection_id) {
@@ -7860,7 +8243,7 @@ const _AnimationPlayer = class _AnimationPlayer {
     if (this.streamingPlayer) {
       return;
     }
-    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-D8Q8WiEg.js");
+    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-C8IqtjfL.js");
     const { AvatarSDK: AvatarSDK2 } = await Promise.resolve().then(() => AvatarSDK$1);
     const audioFormat = AvatarSDK2.getAudioFormat();
     this.streamingPlayer = new StreamingAudioPlayer({
@@ -9331,6 +9714,10 @@ class AvatarSDK {
         });
       }
       logger.log(`[AvatarSDK] Successfully initialized`);
+      setTimeout(() => {
+        this.flushLogsIfNeeded().catch(() => {
+        });
+      }, 0);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       logger.error("Failed to initialize AvatarSDK:", errorMessage);
@@ -9422,6 +9809,7 @@ class AvatarSDK {
    */
   static setUserId(userId) {
     idManager.setUserId(userId);
+    updatePostHogPersonPropertiesForFlags();
   }
   // 只读属性
   static get isInitialized() {
@@ -9528,10 +9916,27 @@ class AvatarSDK {
       driveningressWsUrl
     };
   }
+  /**
+   * Flush logs if feature flag is enabled (private method)
+   * First fetches latest feature flag from server, then decides whether to upload logs
+   * @internal
+   */
+  static async flushLogsIfNeeded() {
+    try {
+      const isEnabled = await getLogsFeatureFlag();
+      if (!isEnabled) {
+        return;
+      }
+      await logSink.flush();
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logger.warn("[AvatarSDK] Failed to flush logs:", errorMessage);
+    }
+  }
 }
 __publicField(AvatarSDK, "_isInitialized", false);
 __publicField(AvatarSDK, "_configuration", null);
-__publicField(AvatarSDK, "_version", "1.0.0-beta.71");
+__publicField(AvatarSDK, "_version", "1.0.0-beta.73");
 __publicField(AvatarSDK, "_avatarCore", null);
 __publicField(AvatarSDK, "_dynamicSdkConfig", null);
 const AvatarSDK$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
@@ -11407,8 +11812,7 @@ class AvatarController {
       tap1Timestamp: 0,
       tap2Timestamp: 0,
       recvFirstFlameTimestamp: 0,
-      didRecvFirstFlame: false,
-      didReportLatency: false
+      didRecvFirstFlame: false
     });
     __publicField(this, "audioBytesPerSecond", 16e3 * 2);
     this.avatar = avatar;
@@ -11820,10 +12224,6 @@ class AvatarController {
       if (this.playbackMode === DrivingServiceMode.host && !this.hostModeMetrics.didRecvFirstFlame) {
         this.hostModeMetrics.didRecvFirstFlame = true;
         this.hostModeMetrics.recvFirstFlameTimestamp = Date.now();
-        if (conversationId && !this.hostModeMetrics.didReportLatency) {
-          this.reportDrivingServiceLatency(conversationId);
-          this.hostModeMetrics.didReportLatency = true;
-        }
       }
     } else {
       this.currentKeyframes.push(...flameKeyframes);
@@ -11952,8 +12352,7 @@ class AvatarController {
         tap1Timestamp: 0,
         tap2Timestamp: 0,
         recvFirstFlameTimestamp: 0,
-        didRecvFirstFlame: false,
-        didReportLatency: false
+        didRecvFirstFlame: false
       };
     }
   }
@@ -11976,8 +12375,7 @@ class AvatarController {
         tap1Timestamp: 0,
         tap2Timestamp: 0,
         recvFirstFlameTimestamp: 0,
-        didRecvFirstFlame: false,
-        didReportLatency: false
+        didRecvFirstFlame: false
       };
     }
   }
@@ -12672,30 +13070,6 @@ class AvatarController {
     }
     return result2;
   }
-  /**
-   * 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) {
-      return;
-    }
-    const metrics = this.hostModeMetrics;
-    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
-      // 必须有非零值
-    });
-  }
 }
 function errorToMessage(err) {
   if (err instanceof Error) {

package/dist/index.js

@@ -1,4 +1,4 @@
-import { b, c, m, f, d, j, g, C, i, D, E, k, h, L, R, n } from "./index-U8QcNdma.js";
+import { b, c, m, f, d, j, g, C, i, D, E, k, h, L, R, n } from "./index-AtEuBzqP.js";
 export {
   b as Avatar,
   c as AvatarController,

package/dist/utils/log-sanitizer.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Log sanitizer for local log persistence.
+ * Ensures: no sensitive content, no Chinese, no algorithm/internal terms (e.g. Flame, splat).
+ * @internal
+ */
+export interface SanitizeResult {
+    shouldPersist: boolean;
+    sanitized: string;
+}
+/**
+ * Sanitize a log message for local persistence.
+ * - Do not persist if message contains Chinese or algorithm terms.
+ * - Otherwise persist, but redact sensitive content first.
+ */
+export declare function sanitizeForLocalLog(message: string): SanitizeResult;

package/dist/utils/log-sink.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Log Sink - Local log storage and upload
+ * Stores logs in IndexedDB and provides upload functionality
+ * @internal
+ */
+declare class LogSink {
+    private static instance;
+    private db;
+    private readonly dbName;
+    private readonly storeName;
+    private readonly version;
+    private readonly trimThreshold;
+    private readonly trimBufferSize;
+    private isFlushing;
+    private constructor();
+    static getInstance(): LogSink;
+    /**
+     * Initialize IndexedDB
+     */
+    initialize(): Promise<void>;
+    /**
+     * Append log entry to IndexedDB
+     */
+    append(entry: LogEntry): Promise<void>;
+    /**
+     * Get total log count
+     */
+    private getCount;
+    /**
+     * Trim logs to keep only recent entries
+     */
+    private trim;
+    /**
+     * Flush logs to server
+     */
+    flush(): Promise<void>;
+    /**
+     * Clear first N log entries
+     */
+    private clearFirst;
+    /**
+     * Gzip string data
+     */
+    private gzip;
+}
+export declare const logSink: LogSink;
+export {};

package/dist/utils/logger.d.ts

@@ -1,26 +1,25 @@
-import { LogLevel as GuiiaiLogLevel } from '@guiiai/logg';
-export declare const logger: import('@guiiai/logg').Logg;
+/**
+ * Logger Utility
+ * Environment-aware logger wrapper with local log persistence
+ * - Always writes to local log file (IndexedDB) regardless of logLevel
+ * - Console output is controlled by logLevel
+ * - Errors and warnings are always reported to PostHog (when enabled)
+ *
+ * Usage: Replace `console.log()` with `logger.log()`
+ */
+export declare const logger: {
+    debug: (message: string, ...args: unknown[]) => void;
+    verbose: (message: string, ...args: unknown[]) => void;
+    log: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ..._args: unknown[]) => void;
+    errorWithError: (message: string, error: Error | unknown) => void;
+};
 export declare const loggerWithUnknown: {
     error: (message: string, error?: unknown) => void;
     warn: (message: string, error?: unknown) => void;
-    useGlobalConfig: () => import('@guiiai/logg').Logg;
-    child: (fields?: Record<string, any>) => import('@guiiai/logg').Logg;
-    withContext: (context: string) => import('@guiiai/logg').Logg;
-    withLogLevel: (logLevel: GuiiaiLogLevel) => import('@guiiai/logg').Logg;
-    withLogLevelString: (logLevelString: import('@guiiai/logg').LogLevelString) => import('@guiiai/logg').Logg;
-    withFormat: (format: import('@guiiai/logg').Format) => import('@guiiai/logg').Logg;
-    withFields: (fields: Record<string, any>) => import('@guiiai/logg').Logg;
-    withField: (key: string, value: any) => import('@guiiai/logg').Logg;
-    withError: (err: Error | unknown) => import('@guiiai/logg').Logg;
-    withCallStack: (errorLike: {
-        message: string;
-        stack?: string;
-    }) => import('@guiiai/logg').Logg;
-    debug: (message: any, ...optionalParams: [...any, string?]) => void;
-    verbose: (message: any, ...optionalParams: [...any, string?]) => void;
-    log: (message: any, ...optionalParams: any[]) => void;
-    errorWithError: (message: any, err: Error | unknown, ...optionalParams: any[]) => void;
-    withTimeFormat: (format: string) => import('@guiiai/logg').Logg;
-    withTimeFormatter: (fn: (inputDate: Date) => string) => import('@guiiai/logg').Logg;
-    withErrorProcessor: (fn: (err: Error | unknown) => Error | unknown) => import('@guiiai/logg').Logg;
+    debug: (message: string, ...args: unknown[]) => void;
+    verbose: (message: string, ...args: unknown[]) => void;
+    log: (message: string, ...args: unknown[]) => void;
+    errorWithError: (message: string, error: Error | unknown) => void;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spatialwalk/avatarkit",
   "type": "module",
-  "version": "1.0.0-beta.71",
+  "version": "1.0.0-beta.73",
   "packageManager": "pnpm@10.18.2",
   "description": "AvatarKit SDK - 3D Gaussian Splatting Avatar Rendering SDK",
   "author": "AvatarKit Team",