@spatialwalk/avatarkit 1.0.0-beta.91 → 1.0.0-beta.92

package/CHANGELOG.md

@@ -5,6 +5,12 @@ 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.92]
+
+### ✨ Features
+
+- **Host Mode Animation End Signal** — `yieldFramesData()` now returns a `boolean` indicating whether the server has sent all animation data for the current conversation (`end` flag from protobuf). Non-breaking: callers that ignore the return value are unaffected.
+
 ## [1.0.0-beta.91] - 2026-03-19
 
 ### 🐛 Bugfixes

package/dist/{StreamingAudioPlayer-CGUA8-w0.js → StreamingAudioPlayer-eQ2RRq5U.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-BYr_FIpm.js";
+import { A as APP_CONFIG, l as logger, e as errorToMessage, a as logEvent } from "./index-C2higMlc.js";
 class StreamingAudioPlayer {
   // Mark if AudioContext is being resumed, avoid concurrent resume requests
   constructor(options) {

package/dist/core/AvatarController.d.ts

@@ -91,8 +91,9 @@ export declare class AvatarController {
      * @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.
+     * @returns `true` if the server has sent all animation data for this conversation (end signal received), `false` otherwise.
      */
-    yieldFramesData(keyframesDataArray: (Uint8Array | ArrayBuffer)[], conversationId: string): void;
+    yieldFramesData(keyframesDataArray: (Uint8Array | ArrayBuffer)[], conversationId: string): boolean;
     /**
      * Send animation keyframes (host mode)
      * Stream animation keyframes data after yieldAudioData()

package/dist/{index-BYr_FIpm.js → index-C2higMlc.js}

@@ -9495,7 +9495,7 @@ const _AnimationPlayer = class _AnimationPlayer {
     if (this.streamingPlayer) {
       return;
     }
-    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-CGUA8-w0.js");
+    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-eQ2RRq5U.js");
     const { AvatarSDK: AvatarSDK2 } = await Promise.resolve().then(() => AvatarSDK$1);
     const audioFormat = AvatarSDK2.getAudioFormat();
     this.streamingPlayer = new StreamingAudioPlayer({
@@ -11473,7 +11473,7 @@ class AvatarSDK {
 __publicField(AvatarSDK, "_initializationState", "uninitialized");
 __publicField(AvatarSDK, "_initializingPromise", null);
 __publicField(AvatarSDK, "_configuration", null);
-__publicField(AvatarSDK, "_version", "1.0.0-beta.91");
+__publicField(AvatarSDK, "_version", "1.0.0-beta.92");
 __publicField(AvatarSDK, "_avatarCore", null);
 __publicField(AvatarSDK, "_dynamicSdkConfig", null);
 __publicField(AvatarSDK, "_cachedDeviceScore", null);
@@ -11904,6 +11904,8 @@ class NetworkLayer {
     __publicField(this, "audioMetrics", this.createAudioMetrics());
     __publicField(this, "isFallbackMode", false);
     // 连接超时降级模式标记
+    /** @internal 降级原因，供 AvatarController 读取 */
+    __publicField(this, "_fallbackReason", "");
     __publicField(this, "isConnecting", false);
     // 避免并发连接
     // 驱动服务心跳检测相关
@@ -11943,6 +11945,7 @@ class NetworkLayer {
     }
     (_b = (_a = this.dataController).onConnectionState) == null ? void 0 : _b.call(_a, ConnectionState.connecting);
     this.isFallbackMode = false;
+    this._fallbackReason = "";
     this.setupWebSocketListeners();
     this.isConnecting = true;
     const CONNECTION_TIMEOUT_MS = 15e3;
@@ -11953,6 +11956,7 @@ class NetworkLayer {
         var _a2, _b2;
         if (!this.dataController.connected) {
           this.isFallbackMode = true;
+          this._fallbackReason = "connection_timeout";
           logger.warn(`[NetworkLayer] WebSocket connection timeout (${CONNECTION_TIMEOUT_MS}ms) - entering fallback mode`);
           (_b2 = (_a2 = this.dataController).onConnectionState) == null ? void 0 : _b2.call(_a2, ConnectionState.failed);
         }
@@ -11970,6 +11974,7 @@ class NetworkLayer {
       }
       if (!this.isFallbackMode) {
         this.isFallbackMode = true;
+        this._fallbackReason = "connection_failed";
         logger.warn("[NetworkLayer] WebSocket connection failed - entering fallback mode");
       }
       (_d = (_c = this.dataController).onConnectionState) == null ? void 0 : _d.call(_c, ConnectionState.failed);
@@ -12034,6 +12039,7 @@ class NetworkLayer {
    */
   disconnect() {
     this.isFallbackMode = false;
+    this._fallbackReason = "";
     this.isConnecting = false;
     this.wsClient.removeAllListeners();
     this.wsClient.disconnect();
@@ -12069,6 +12075,7 @@ class NetworkLayer {
       }
       if (!this.dataController.connected) {
         this.isFallbackMode = false;
+        this._fallbackReason = "";
         this.dataController.setConnected(true);
         (_b = (_a = this.dataController).onConnectionState) == null ? void 0 : _b.call(_a, ConnectionState.connected);
       }
@@ -12665,7 +12672,7 @@ class AvatarController {
       case AvatarState.idle:
         if (this.shouldReportPlaybackStats) {
           const stats = this.frameRateMonitor.getPlaybackStats();
-          if (stats.durationMs >= 2e3) {
+          if (stats.durationMs >= 2e3 && stats.frameCount > 0 && Math.random() < 0.3) {
             const props = {
               avg_fps: Number(stats.avgFps.toFixed(1)),
               frame_count: stats.frameCount,
@@ -12788,7 +12795,7 @@ class AvatarController {
    * @returns conversationId - Conversation ID for this audio session
    */
   send(audioData, end = false) {
-    var _a, _b, _c;
+    var _a, _b;
     try {
       this.checkAudioContextInitialized();
     } catch (error) {
@@ -12799,14 +12806,6 @@ class AvatarController {
       (_b = this.onError) == null ? void 0 : _b.call(this, new AvatarError("Network layer not available", "NETWORK_LAYER_NOT_AVAILABLE"));
       return null;
     }
-    if (!this.networkLayer.canSend()) {
-      (_c = this.onError) == null ? void 0 : _c.call(this, new AvatarError("Service not connected", "NOT_CONNECTED"));
-      logEvent("character_manager", "warning", {
-        avatar_id: this.avatar.id,
-        event: "send_not_connected"
-      });
-      return null;
-    }
     const networkConversationId = this.networkLayer.getCurrentConversationId();
     if (this.reqEnd && this.isPlaying && networkConversationId) {
       this.interrupt();
@@ -12865,12 +12864,7 @@ class AvatarController {
       this.emit("keyframesUpdate", this.currentKeyframes);
     } else {
       logger.warn("[AvatarController] Empty animation data in playback - enabling fallback mode");
-      logEvent("character_manager", "info", {
-        avatar_id: this.avatar.id,
-        event: "empty_animation_data_audio_only_fallback",
-        conversationId: this.currentConversationId
-      });
-      this.isFallbackMode = true;
+      this.enableFallbackMode("empty_animation");
     }
     if (this.pendingAudioChunks.length === 0) {
       throw new AvatarError("No audio chunks to play", "NO_AUDIO");
@@ -12943,14 +12937,16 @@ class AvatarController {
    * @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.
+   * @returns `true` if the server has sent all animation data for this conversation (end signal received), `false` otherwise.
    */
   yieldFramesData(keyframesDataArray, conversationId) {
-    var _a, _b;
+    var _a, _b, _c;
     if (!keyframesDataArray || keyframesDataArray.length === 0) {
       this.yieldKeyframes([], conversationId);
-      return;
+      return false;
     }
     let allKeyframes = [];
+    let isEnd = false;
     for (let i2 = 0; i2 < keyframesDataArray.length; i2++) {
       const item = keyframesDataArray[i2];
       const binaryData = item instanceof ArrayBuffer ? new Uint8Array(item) : item;
@@ -12966,6 +12962,9 @@ class AvatarController {
         } else {
           logger.warn(`[AvatarController] Message chunk ${i2 + 1} does not contain animation keyframes`);
         }
+        if ((_c = message.serverResponseAnimation) == null ? void 0 : _c.end) {
+          isEnd = true;
+        }
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         logger.error(`[AvatarController] Failed to decode animation data chunk ${i2 + 1}: ${errorMessage}`);
@@ -12983,6 +12982,7 @@ class AvatarController {
       logger.warn(`[AvatarController] No keyframes decoded from ${keyframesDataArray.length} message chunks`);
     }
     this.yieldKeyframes(allKeyframes, conversationId);
+    return isEnd;
   }
   /**
    * Send animation keyframes (host mode)
@@ -12997,6 +12997,7 @@ class AvatarController {
    *                Use getCurrentConversationId() to get the current conversationId.
    */
   yieldKeyframes(keyframes, conversationId) {
+    var _a;
     if (!conversationId || typeof conversationId !== "string") {
       logger.error(`[AvatarController] yieldKeyframes requires a valid conversationId. Use getCurrentConversationId() to get the current conversationId.`);
       logEvent("character_manager", "error", {
@@ -13028,12 +13029,8 @@ class AvatarController {
     }
     if (!keyframes || keyframes.length === 0) {
       logger.warn("[AvatarController] Empty animation data received - enabling fallback mode");
-      logEvent("character_manager", "info", {
-        avatar_id: this.avatar.id,
-        event: "empty_animation_data_audio_only_fallback",
-        conversationId
-      });
-      this.enableFallbackMode();
+      const reason = ((_a = this.networkLayer) == null ? void 0 : _a._fallbackReason) || "empty_animation";
+      this.enableFallbackMode(reason);
       return;
     }
     const flameKeyframes = keyframes;
@@ -13049,10 +13046,10 @@ class AvatarController {
     this.emit("keyframesUpdate", this.currentKeyframes);
     if (!this.isPlaying && !this.isStartingPlayback && this.pendingAudioChunks.length > 0 && this.currentKeyframes.length > 0) {
       this.startStreamingPlayback().catch((error) => {
-        var _a;
+        var _a2;
         this.isStartingPlayback = false;
         logger.error("[AvatarController] Failed to auto-start playback:", error);
-        (_a = this.onError) == null ? void 0 : _a.call(this, new AvatarError("Failed to start playback", "PLAYBACK_START_FAILED"));
+        (_a2 = this.onError) == null ? void 0 : _a2.call(this, new AvatarError("Failed to start playback", "PLAYBACK_START_FAILED"));
       });
     }
   }
@@ -13704,12 +13701,18 @@ class AvatarController {
    * Once enabled, subsequent animation data in this session will be ignored
    * @internal
    */
-  enableFallbackMode() {
+  enableFallbackMode(reason = "empty_animation") {
     if (this.isFallbackMode) {
       return;
     }
     logger.warn("[AvatarController] Enabling fallback mode");
     this.isFallbackMode = true;
+    logEvent("fallback_mode_entered", "warning", {
+      avatar_id: this.avatar.id,
+      reason,
+      con_id: idManager.getConnectionId() || "",
+      req_id: this.currentConversationId || ""
+    });
     if (this.isPlaying) {
       this.stopPlaybackLoop();
       this.emit("stopRendering");
@@ -14479,6 +14482,9 @@ class AvatarDownloader {
         return { key, success: true, size: arrayBuffer.byteLength };
       } catch (error) {
         if (error instanceof Error && (error.name === "AbortError" || error.message === "Download cancelled")) {
+          logEvent("download_avatar_assets_cancelled", "info", {
+            avatar_id: characterMeta.characterId ?? "unknown"
+          });
           throw error;
         }
         if (!optional) {
@@ -14659,6 +14665,12 @@ class AvatarDownloader {
       });
       return response;
     } catch (error) {
+      if (error instanceof Error && (error.name === "AbortError" || error.message === "Request cancelled")) {
+        logEvent("fetch_avatar_metadata_cancelled", "info", {
+          avatar_id: characterId ?? "unknown"
+        });
+        throw error;
+      }
       logger.errorWithError("Failed to fetch character:", error);
       if (error instanceof AvatarError) {
         logEvent("fetch_avatar_metadata_failed", "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-BYr_FIpm.js";
+import { b, c, m, f, d, j, g, C, i, D, E, k, h, L, R, n } from "./index-C2higMlc.js";
 export {
   b as Avatar,
   c as AvatarController,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spatialwalk/avatarkit",
   "type": "module",
-  "version": "1.0.0-beta.91",
+  "version": "1.0.0-beta.92",
   "packageManager": "pnpm@10.18.2",
   "description": "AvatarKit SDK - 3D Gaussian Splatting Avatar Rendering SDK",
   "author": "AvatarKit Team",
@@ -51,6 +51,7 @@
     "dev": "vite build --mode library --watch",
     "demo": "vite --config demo/vite.config.mjs",
     "demo:benchmark": "vite --config benchmark-demo/vite.config.mjs",
+    "test:integration": "vite --config tests/integration-runner/vite.config.mjs",
     "clean": "rm -rf dist",
     "typecheck": "tsc --noEmit",
     "test": "cd tests && pnpm test",

package/dist/demo/src/main.d.ts

@@ -1 +0,0 @@
-export {};