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

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-CDywZ8iv.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-DWVeTI7D.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", {
@@ -15666,6 +15678,9 @@ class WebGPURenderer {
     __publicField(this, "blitUniformBuffer", null);
     __publicField(this, "blitQuadBuffer", null);
     __publicField(this, "blitSampler", null);
+    // 记录上次 configure 时的 canvas 尺寸，用于检测 resize
+    __publicField(this, "configuredWidth", 0);
+    __publicField(this, "configuredHeight", 0);
     this.canvas = canvas;
     this.backgroundColor = backgroundColor || [0, 0, 0, 0];
     this.alpha = alpha;
@@ -15686,15 +15701,34 @@ class WebGPURenderer {
       throw new Error("WebGPU: Failed to get canvas context");
     }
     this.presentationFormat = navigator.gpu.getPreferredCanvasFormat();
+    this.configureContext();
+    this.createUniformBuffer();
+    this.createQuadVertexBuffer();
+    await this.createRenderPipeline();
+    await this.createBlitPipeline();
+  }
+  /**
+   * 配置 WebGPU context 并记录尺寸
+   */
+  configureContext() {
+    if (!this.context || !this.device)
+      return;
     this.context.configure({
       device: this.device,
       format: this.presentationFormat,
       alphaMode: this.alpha ? "premultiplied" : "opaque"
     });
-    this.createUniformBuffer();
-    this.createQuadVertexBuffer();
-    await this.createRenderPipeline();
-    await this.createBlitPipeline();
+    this.configuredWidth = this.canvas.width;
+    this.configuredHeight = this.canvas.height;
+  }
+  /**
+   * 检测 canvas 尺寸变化，必要时重新 configure context
+   * 防止 tab 切换等场景下 surface 尺寸与 canvas 尺寸不一致导致渲染错位
+   */
+  ensureContextSize() {
+    if (this.canvas.width !== this.configuredWidth || this.canvas.height !== this.configuredHeight) {
+      this.configureContext();
+    }
   }
   /**
    * 创建 Uniform Buffer
@@ -16114,6 +16148,7 @@ class WebGPURenderer {
       return;
     if (this.splatCount === 0 || !this.storageBindGroup)
       return;
+    this.ensureContextSize();
     const [width, height] = screenSize;
     const needsTransform = transform && (transform.x !== 0 || transform.y !== 0 || transform.scale !== 1);
     this.updateUniforms(viewMatrix, projectionMatrix, screenSize);
@@ -16346,6 +16381,14 @@ class RenderSystem {
     __publicField(this, "offsetX", 0);
     __publicField(this, "offsetY", 0);
     __publicField(this, "scale", 1);
+    /**
+     * Load packed Splat data (zero-copy, GPU format)
+     * Directly receives WASM packed data
+     *
+     * @param packedData Float32Array [pos3, color4, cov6] x N points
+     */
+    // @debug: dump first frame flag
+    __publicField(this, "_dumpedFirstFrame", false);
     this.options = options;
     this.canvas = options.canvas;
     this.backgroundColor = options.backgroundColor || [0, 0, 0, 0];
@@ -16389,15 +16432,28 @@ class RenderSystem {
     logger.log("✅ Using WebGL renderer");
     this.updateCameraAspect();
   }
-  /**
-   * Load packed Splat data (zero-copy, GPU format)
-   * Directly receives WASM packed data
-   *
-   * @param packedData Float32Array [pos3, color4, cov6] x N points
-   */
   loadSplatsFromPackedData(packedData) {
     if (!this.renderer)
       throw new Error("Renderer not initialized");
+    if (!this._dumpedFirstFrame) {
+      this._dumpedFirstFrame = true;
+      const pointCount = Math.floor(packedData.length / 13);
+      console.log(`[DEBUG] First frame packed data: ${pointCount} points, ${packedData.length} floats`);
+      for (let i2 = 0; i2 < Math.min(5, pointCount); i2++) {
+        const o2 = i2 * 13;
+        console.log(`[DEBUG] Point ${i2}: pos(${packedData[o2]}, ${packedData[o2 + 1]}, ${packedData[o2 + 2]}) color(${packedData[o2 + 3]}, ${packedData[o2 + 4]}, ${packedData[o2 + 5]}, ${packedData[o2 + 6]}) covA(${packedData[o2 + 7]}, ${packedData[o2 + 8]}, ${packedData[o2 + 9]}) covB(${packedData[o2 + 10]}, ${packedData[o2 + 11]}, ${packedData[o2 + 12]})`);
+      }
+      const copy = new ArrayBuffer(packedData.byteLength);
+      new Uint8Array(copy).set(new Uint8Array(packedData.buffer, packedData.byteOffset, packedData.byteLength));
+      const blob = new Blob([copy], { type: "application/octet-stream" });
+      const url = URL.createObjectURL(blob);
+      const a2 = document.createElement("a");
+      a2.href = url;
+      a2.download = "core_packed_first_frame.bin";
+      a2.click();
+      URL.revokeObjectURL(url);
+      console.log("[DEBUG] Packed data downloaded as core_packed_first_frame.bin");
+    }
     this.originalPackedData = packedData;
   }
   /**

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-CDywZ8iv.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.93",
   "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 {};