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

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.94]
+
+### 🐛 Bugfixes
+
+- **WebGPU Tab Switch Rendering Fix** — Fixed avatar rendering corruption (split/misaligned) when switching back to a tab. Root cause: WebGPU context was not reconfigured after canvas resize, causing surface size and screenSize mismatch in the shader.
+
+### ✨ Features
+
+- **WebSocket Close Code Handling** — Server-defined custom close codes (4010 auth failure, 4001 insufficient balance, 4002 session timeout, 4003 concurrent limit) are now properly recognized and mapped to `ErrorCode`. Non-recoverable errors (4010/4001/4003) no longer trigger reconnection attempts.
+- **Error Transparency** — All non-normal WebSocket close events are now propagated to `onError` callback and reported to PostHog telemetry. Previously, some close codes (e.g. 1006) were only logged internally without notifying the application.
+- **New ErrorCode Values** — Added `insufficientBalance`, `sessionTimeout`, `concurrentLimitExceeded` to the `ErrorCode` enum.
+
 ## [1.0.0-beta.92]
 
 ### ✨ Features

package/README.md

@@ -234,9 +234,10 @@ const configuration: Configuration = {
   // - LogLevel.error: Only error logs
   // - LogLevel.warning: Warning and error logs
   // - LogLevel.all: All logs (info, warning, error)
-  audioFormat: { // Optional, default is { channelCount: 1, sampleRate: 16000 }
+  audioFormat: { // Default is { channelCount: 1, sampleRate: 16000 }
     channelCount: 1, // Fixed to 1 (mono)
     sampleRate: 16000 // Supported: 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz
+    // ⚠️ Must match your actual audio sample rate. Mismatched sample rate will cause playback issues.
   }
   // characterApiBaseUrl: 'https://custom-api.example.com' // Optional, internal debug config, can be ignored
 }
@@ -269,9 +270,18 @@ button.addEventListener('click', async () => {
   await avatarView.controller.initializeAudioContext()
   
   // 5. Start real-time communication (SDK mode only)
+  // Note: start() initiates the WebSocket connection asynchronously.
+  // Wait for onConnectionState === 'connected' before calling send().
   await avatarView.controller.start()
-  
-  // 6. Send audio data (SDK mode, must be mono PCM16 format matching configured sample rate)
+
+  // 6. Wait for connection to be ready
+  await new Promise<void>((resolve) => {
+    avatarView.controller.onConnectionState = (state) => {
+      if (state === ConnectionState.connected) resolve()
+    }
+  })
+
+  // 7. Send audio data (SDK mode, must be mono PCM16 format matching configured sample rate)
   // audioData: ArrayBuffer or Uint8Array containing PCM16 audio samples
   // - PCM files: Can be directly read as ArrayBuffer
   // - WAV files: Extract PCM data from WAV format (may require resampling)
@@ -592,21 +602,25 @@ avatarView.transform = { x, y, scale }
 avatarView.dispose()
 ```
 
-**Avatar Switching Example:**
+**Switching Avatars:**
+
+To switch avatars, dispose the old view and create a new one. Do NOT attempt to reuse or reset an existing AvatarView.
+- `AvatarSDK.initialize()` and session token do not need to be called again.
+- The old AvatarView's internal state is fully cleaned up by `dispose()`.
 
 ```typescript
-// To switch avatars, simply dispose the old view and create a new one
+// 1. Dispose old avatar
 if (currentAvatarView) {
   currentAvatarView.dispose()
 }
 
-// Load new avatar
-const newAvatar = await avatarManager.load('new-character-id')
+// 2. Load new avatar (SDK is already initialized, token is still valid)
+const newAvatar = await AvatarManager.shared.load('new-character-id')
 
-// Create new AvatarView
+// 3. Create new AvatarView
 currentAvatarView = new AvatarView(newAvatar, container)
 
-// SDK mode: start connection (will throw error if not in SDK mode)
+// 4. Start connection if SDK mode
 await currentAvatarView.controller.start()
 ```
 
@@ -634,7 +648,7 @@ button.addEventListener('click', async () => {
   const conversationId = avatarView.controller.send(audioData: ArrayBuffer, end: boolean)
   // Returns: conversationId - Conversation ID for this conversation session
   // end: false (default) - Continue sending audio data for current conversation
-  // end: true - Mark the end of current conversation round. After end=true, sending new audio data will interrupt any ongoing playback from the previous conversation round
+  // end: true - Mark the end of audio input for current conversation round. The avatar will continue playing remaining animation until finished, then automatically return to idle (notified via onConversationState). After end=true, sending new audio data will interrupt any ongoing playback from the previous conversation round
 })
 
 // Close service
@@ -706,7 +720,7 @@ const currentVolume = avatarView.controller.getVolume()  // Get current volume (
 // Set event callbacks
 avatarView.controller.onConnectionState = (state: ConnectionState) => {} // SDK mode only
 avatarView.controller.onConversationState = (state: ConversationState) => {}
-avatarView.controller.onError = (error: Error) => {} // Usually AvatarError (includes code for SDK/server errors)
+avatarView.controller.onError = (error: AvatarError) => {} // Includes error.code for specific error type
 ```
 
 #### Avatar Transform Methods
@@ -866,23 +880,41 @@ try {
 ```typescript
 import { AvatarError } from '@spatialwalk/avatarkit'
 
-avatarView.controller.onError = (error: Error) => {
-  if (error instanceof AvatarError) {
-    console.error('AvatarController error:', error.message, error.code)
-    return
-  }
-
-  console.error('AvatarController unknown error:', error)
+avatarView.controller.onError = (error: AvatarError) => {
+  console.error('Error:', error.code, error.message)
 }
 ```
 
-In SDK mode, server `MESSAGE_SERVER_ERROR` is forwarded to `onError` as `AvatarError`:
-- `error.message`: server-returned error message
-- `error.code` mapping:
-  - `401` -> `sessionTokenExpired`
-  - `400` -> `sessionTokenInvalid`
-  - `404` -> `avatarIDUnrecognized`
-  - other HTTP status -> original status code string (for example, `"500"`)
+`error.code` values (from `ErrorCode` enum):
+
+| Code | Description | Trigger |
+|------|-------------|---------|
+| **Authentication & Authorization** | | |
+| `appIDUnrecognized` | App ID not recognized | Reserved |
+| `sessionTokenInvalid` | Token invalid or appId mismatch | WebSocket close code 4010 |
+| `sessionTokenExpired` | Token expired | WebSocket close code 4010 |
+| `insufficientBalance` | Insufficient balance | WebSocket close code 4001 |
+| `concurrentLimitExceeded` | Concurrent connection limit exceeded | WebSocket close code 4003 |
+| **Resource Loading** | | |
+| `avatarIDUnrecognized` | Avatar ID not found | Server error |
+| `failedToFetchAvatarMetadata` | Metadata fetch failed | Network/server error |
+| `failedToDownloadAvatarAssets` | Asset download failed | Network/server error |
+| **Connection** | | |
+| `websocketError` | WebSocket handshake or network error | Connection failure |
+| `websocketClosedAbnormally` | Connection closed abnormally | Close code 1006 |
+| `websocketClosedUnexpected` | Unexpected close code | Unknown close code |
+| `sessionTimeout` | Session timeout | WebSocket close code 4002 |
+| `connectionInProgress` | Connection already in progress | Duplicate `start()` call |
+| **Playback** | | |
+| `networkLayerNotAvailable` | Network layer not available | `send()` in host mode |
+| `playbackStartFailed` | Failed to start playback | Internal error |
+| `playbackInitFailed` | Playback initialization failed | Internal error |
+| `audioOnlyInitFailed` | Audio-only playback init failed | Fallback mode error |
+| `noAudio` | No audio data to play | Empty audio input |
+| `audioContextNotInitialized` | Audio context not initialized | `send()` before `initializeAudioContext()` |
+| `animationPlayerNotInitialized` | Animation player not initialized | Internal error |
+| **Server** | | |
+| `serverError` | Server-side error | Server MESSAGE_SERVER_ERROR |
 
 ## 🔄 Resource Management
 

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

package/dist/core/AvatarController.d.ts

@@ -1,5 +1,5 @@
 import { Avatar } from './Avatar';
-import { ConnectionState, DrivingServiceMode, ConversationState, PostProcessingConfig, KeyframeData } from '../types';
+import { ConnectionState, AvatarError, DrivingServiceMode, ConversationState, PostProcessingConfig, KeyframeData } from '../types';
 import { FrameRateInfo } from '../performance/FrameRateMonitor';
 export declare class AvatarController {
     private networkLayer?;
@@ -9,7 +9,7 @@ export declare class AvatarController {
     private reqEnd;
     onConnectionState: ((state: ConnectionState) => void) | null;
     onConversationState: ((state: ConversationState) => void) | null;
-    onError: ((error: Error) => void) | null;
+    onError: ((error: AvatarError) => void) | null;
     private eventListeners;
     private readonly frameRateMonitor;
     /** Frame rate monitoring callback. Fires with aggregated metrics from a 2-second sliding window. */

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

@@ -8588,11 +8588,26 @@ var AvatarState = /* @__PURE__ */ ((AvatarState2) => {
 })(AvatarState || {});
 var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
   ErrorCode2["appIDUnrecognized"] = "appIDUnrecognized";
-  ErrorCode2["avatarIDUnrecognized"] = "avatarIDUnrecognized";
   ErrorCode2["sessionTokenInvalid"] = "sessionTokenInvalid";
   ErrorCode2["sessionTokenExpired"] = "sessionTokenExpired";
+  ErrorCode2["insufficientBalance"] = "insufficientBalance";
+  ErrorCode2["concurrentLimitExceeded"] = "concurrentLimitExceeded";
+  ErrorCode2["avatarIDUnrecognized"] = "avatarIDUnrecognized";
   ErrorCode2["failedToFetchAvatarMetadata"] = "failedToFetchAvatarMetadata";
   ErrorCode2["failedToDownloadAvatarAssets"] = "failedToDownloadAvatarAssets";
+  ErrorCode2["websocketError"] = "websocketError";
+  ErrorCode2["websocketClosedAbnormally"] = "websocketClosedAbnormally";
+  ErrorCode2["websocketClosedUnexpected"] = "websocketClosedUnexpected";
+  ErrorCode2["sessionTimeout"] = "sessionTimeout";
+  ErrorCode2["connectionInProgress"] = "connectionInProgress";
+  ErrorCode2["networkLayerNotAvailable"] = "networkLayerNotAvailable";
+  ErrorCode2["playbackStartFailed"] = "playbackStartFailed";
+  ErrorCode2["playbackInitFailed"] = "playbackInitFailed";
+  ErrorCode2["audioOnlyInitFailed"] = "audioOnlyInitFailed";
+  ErrorCode2["noAudio"] = "noAudio";
+  ErrorCode2["audioContextNotInitialized"] = "audioContextNotInitialized";
+  ErrorCode2["animationPlayerNotInitialized"] = "animationPlayerNotInitialized";
+  ErrorCode2["serverError"] = "serverError";
   return ErrorCode2;
 })(ErrorCode || {});
 class AvatarError extends Error {
@@ -9495,7 +9510,7 @@ const _AnimationPlayer = class _AnimationPlayer {
     if (this.streamingPlayer) {
       return;
     }
-    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-eQ2RRq5U.js");
+    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-BAjzNT1N.js");
     const { AvatarSDK: AvatarSDK2 } = await Promise.resolve().then(() => AvatarSDK$1);
     const audioFormat = AvatarSDK2.getAudioFormat();
     this.streamingPlayer = new StreamingAudioPlayer({
@@ -11473,7 +11488,7 @@ class AvatarSDK {
 __publicField(AvatarSDK, "_initializationState", "uninitialized");
 __publicField(AvatarSDK, "_initializingPromise", null);
 __publicField(AvatarSDK, "_configuration", null);
-__publicField(AvatarSDK, "_version", "1.0.0-beta.92");
+__publicField(AvatarSDK, "_version", "1.0.0-beta.94");
 __publicField(AvatarSDK, "_avatarCore", null);
 __publicField(AvatarSDK, "_dynamicSdkConfig", null);
 __publicField(AvatarSDK, "_cachedDeviceScore", null);
@@ -11701,22 +11716,17 @@ class AnimationWebSocketClient extends EventEmitter {
             logger.warn("[AnimationWebSocketClient] Received non-binary data:", typeof event.data);
           }
         };
-        this.ws.onerror = (error) => {
+        this.ws.onerror = () => {
           var _a;
-          const errorMessage = error instanceof Error ? error.message : String(error);
           const readyState = (_a = this.ws) == null ? void 0 : _a.readyState;
           const readyStateText = readyState === WebSocket.CONNECTING ? "CONNECTING" : readyState === WebSocket.OPEN ? "OPEN" : readyState === WebSocket.CLOSING ? "CLOSING" : readyState === WebSocket.CLOSED ? "CLOSED" : "UNKNOWN";
-          const errorDetails = `ReadyState: ${readyState} (${readyStateText}), URL: ${urlForLog}, Error: ${errorMessage}`;
-          logger.error("[AnimationWebSocketClient] WebSocket error:", errorDetails);
-          if (readyState === WebSocket.CLOSED) {
-            logger.warn("[AnimationWebSocketClient] Connection failed immediately. Possible causes:");
-            logger.warn("  1. Server may not support v2 protocol yet");
-            logger.warn("  2. Incorrect URL path or server configuration");
-            logger.warn("  3. Authentication or authorization issue");
-            logger.warn("  4. Network/firewall blocking the connection");
-            logger.warn(`  Please check browser Network tab for detailed error information`);
-          }
-          this.emit("error", new Error(`WebSocket error (readyState: ${readyState})`));
+          logger.error(`[AnimationWebSocketClient] WebSocket error: readyState=${readyStateText}, url=${urlForLog}`);
+          logEvent("websocket_error", "error", {
+            con_id: idManager.getConnectionId() || "",
+            readyState: readyStateText,
+            description: `WebSocket error (readyState: ${readyStateText})`
+          });
+          this.emit("error", new AvatarError(`WebSocket error (readyState: ${readyStateText})`, ErrorCode.websocketError));
           if (!this.isManuallyDisconnected && this.currentRetryCount < this.reconnectAttempts) {
             this.scheduleReconnect();
           }
@@ -11735,47 +11745,76 @@ class AnimationWebSocketClient extends EventEmitter {
           this.sessionConfigured = false;
           let sdkErrorCode = null;
           const reason = event.reason || "";
-          const reasonLower = reason.toLowerCase();
-          if (event.code === 1008 || reasonLower.includes("401") || reasonLower.includes("unauth") || reasonLower.includes("expired") || reasonLower.includes("token expired")) {
-            sdkErrorCode = ErrorCode.sessionTokenExpired;
-            logEvent("session_token_expired", "warning", {
-              con_id: idManager.getConnectionId() || "",
-              description: reason || "Session token expired",
-              session_duration_ms: sessionDurationMs
-            });
-          } else if (reasonLower.includes("400") || reasonLower.includes("invalid") || reasonLower.includes("bad request")) {
-            sdkErrorCode = ErrorCode.sessionTokenInvalid;
-            logEvent("session_token_invalid", "warning", {
-              con_id: idManager.getConnectionId() || "",
-              description: reason || "Session token invalid",
-              session_duration_ms: sessionDurationMs
-            });
-          } else if (reasonLower.includes("404") || reasonLower.includes("notfound") || reasonLower.includes("not found")) {
-            sdkErrorCode = ErrorCode.avatarIDUnrecognized;
-            logEvent("avatar_id_unrecognized", "error", {
-              avatar_id: this.currentCharacterId || "",
-              description: reason || "Avatar ID unrecognized",
-              session_duration_ms: sessionDurationMs
-            });
+          switch (event.code) {
+            case 4010:
+              sdkErrorCode = ErrorCode.sessionTokenInvalid;
+              logEvent("session_token_invalid", "warning", {
+                sessionToken: this.jwtToken || "",
+                userId: "",
+                con_id: idManager.getConnectionId() || "",
+                description: reason || "Authentication failed",
+                session_duration_ms: sessionDurationMs
+              });
+              break;
+            case 4001:
+              sdkErrorCode = ErrorCode.insufficientBalance;
+              logEvent("insufficient_balance", "warning", {
+                con_id: idManager.getConnectionId() || "",
+                description: reason || "Insufficient balance",
+                session_duration_ms: sessionDurationMs
+              });
+              break;
+            case 4002:
+              sdkErrorCode = ErrorCode.sessionTimeout;
+              logEvent("session_timeout", "warning", {
+                con_id: idManager.getConnectionId() || "",
+                description: reason || "Session timeout",
+                session_duration_ms: sessionDurationMs
+              });
+              break;
+            case 4003:
+              sdkErrorCode = ErrorCode.concurrentLimitExceeded;
+              logEvent("concurrent_limit_exceeded", "warning", {
+                con_id: idManager.getConnectionId() || "",
+                description: reason || "Concurrent connection limit exceeded",
+                session_duration_ms: sessionDurationMs
+              });
+              break;
+            case 1006:
+              logEvent("websocket_closed_abnormally", "error", {
+                con_id: idManager.getConnectionId() || "",
+                code: event.code,
+                description: reason || "Connection closed abnormally",
+                session_duration_ms: sessionDurationMs
+              });
+              break;
+            case 1012:
+              logEvent("service_restarted", "warning", {
+                con_id: idManager.getConnectionId() || "",
+                description: reason || "Service restart",
+                session_duration_ms: sessionDurationMs
+              });
+              break;
           }
           if (sdkErrorCode) {
-            const error = new AvatarError(
+            this.emit("error", new AvatarError(
               reason || `WebSocket connection failed with code ${event.code}`,
               sdkErrorCode
-            );
-            this.emit("error", error);
-          }
-          if (event.code === 1006) {
-            logger.warn("[AnimationWebSocketClient] Connection closed abnormally (1006) - possible causes: network issue, server rejection, or protocol mismatch");
-          }
-          if (event.code === 1012) {
-            logEvent("service_restarted", "warning", {
+            ));
+          } else if (event.code !== 1e3) {
+            logEvent("websocket_closed_unexpected", "error", {
               con_id: idManager.getConnectionId() || "",
-              description: event.reason || "Service restart",
+              code: event.code,
+              description: reason || `Unexpected close (code: ${event.code})`,
               session_duration_ms: sessionDurationMs
             });
+            this.emit("error", new AvatarError(
+              reason || `WebSocket connection closed (code: ${event.code})`,
+              ErrorCode.websocketClosedUnexpected
+            ));
           }
-          if (!this.isManuallyDisconnected && this.currentRetryCount < this.reconnectAttempts) {
+          const isNonRecoverable = sdkErrorCode === ErrorCode.sessionTokenInvalid || sdkErrorCode === ErrorCode.insufficientBalance || sdkErrorCode === ErrorCode.concurrentLimitExceeded;
+          if (!isNonRecoverable && !this.isManuallyDisconnected && this.currentRetryCount < this.reconnectAttempts) {
             this.scheduleReconnect();
           }
         };
@@ -11941,7 +11980,7 @@ class NetworkLayer {
     var _a, _b, _c, _d;
     if (this.isConnecting) {
       logger.warn("[NetworkLayer] Connection already in progress, waiting for current connection to complete");
-      throw new AvatarError("Connection already in progress", "CONNECTION_IN_PROGRESS");
+      throw new AvatarError("Connection already in progress", ErrorCode.connectionInProgress);
     }
     (_b = (_a = this.dataController).onConnectionState) == null ? void 0 : _b.call(_a, ConnectionState.connecting);
     this.isFallbackMode = false;
@@ -12091,10 +12130,12 @@ class NetworkLayer {
     this.wsClient.on("reconnecting", () => {
     });
     this.wsClient.on("error", (error) => {
-      var _a, _b;
+      var _a, _b, _c, _d;
       const message = error instanceof Error ? error.message : String(error);
       logger.error("[NetworkLayer] WebSocket error:", message);
       (_b = (_a = this.dataController).onConnectionState) == null ? void 0 : _b.call(_a, ConnectionState.failed);
+      const avatarError = error instanceof AvatarError ? error : new AvatarError(message, ErrorCode.websocketError);
+      (_d = (_c = this.dataController).onError) == null ? void 0 : _d.call(_c, avatarError);
     });
     this.wsClient.on("message", (message) => {
       this.handleMessage(message);
@@ -12187,7 +12228,6 @@ class NetworkLayer {
       description: message.serverError.message || `Server error: code=${message.serverError.code}`
     });
     const httpStatusCode = message.serverError.code;
-    const errorCodeStr = (httpStatusCode == null ? void 0 : httpStatusCode.toString()) ?? "";
     let sdkErrorCode;
     let errorMessage = message.serverError.message || "Server error occurred";
     if (httpStatusCode === 401) {
@@ -12206,7 +12246,7 @@ class NetworkLayer {
       sdkErrorCode = ErrorCode.avatarIDUnrecognized;
       errorMessage = errorMessage || "Avatar ID not recognized";
     } else {
-      sdkErrorCode = errorCodeStr || "SERVER_ERROR";
+      sdkErrorCode = ErrorCode.serverError;
     }
     (_b = (_a = this.dataController).onError) == null ? void 0 : _b.call(_a, new AvatarError(
       errorMessage,
@@ -12745,7 +12785,7 @@ class AvatarController {
         logger.error("[AvatarController] Failed to initialize audio context:", message);
         throw new AvatarError(
           `Failed to initialize audio context: ${message}`,
-          "AUDIO_CONTEXT_INIT_FAILED"
+          ErrorCode.audioContextNotInitialized
         );
       }
     }
@@ -12771,7 +12811,7 @@ class AvatarController {
     if (!((_a = this.animationPlayer) == null ? void 0 : _a.isStreamingReady())) {
       throw new AvatarError(
         "Audio context not initialized. Call initializeAudioContext() in a user gesture context first.",
-        "AUDIO_CONTEXT_NOT_INITIALIZED"
+        ErrorCode.audioContextNotInitialized
       );
     }
   }
@@ -12783,7 +12823,7 @@ class AvatarController {
     if (!this.networkLayer) {
       throw new AvatarError(
         "Network layer not available. Use SDK mode.",
-        "NETWORK_LAYER_NOT_AVAILABLE"
+        ErrorCode.networkLayerNotAvailable
       );
     }
     this.checkAudioContextInitialized();
@@ -12803,7 +12843,7 @@ class AvatarController {
       return null;
     }
     if (!this.networkLayer) {
-      (_b = this.onError) == null ? void 0 : _b.call(this, new AvatarError("Network layer not available", "NETWORK_LAYER_NOT_AVAILABLE"));
+      (_b = this.onError) == null ? void 0 : _b.call(this, new AvatarError("Network layer not available", ErrorCode.networkLayerNotAvailable));
       return null;
     }
     const networkConversationId = this.networkLayer.getCurrentConversationId();
@@ -12867,7 +12907,7 @@ class AvatarController {
       this.enableFallbackMode("empty_animation");
     }
     if (this.pendingAudioChunks.length === 0) {
-      throw new AvatarError("No audio chunks to play", "NO_AUDIO");
+      throw new AvatarError("No audio chunks to play", ErrorCode.noAudio);
     }
     if (this.isFallbackMode) {
       await this.startAudioOnlyPlayback();
@@ -13049,7 +13089,7 @@ class AvatarController {
         var _a2;
         this.isStartingPlayback = false;
         logger.error("[AvatarController] Failed to auto-start playback:", error);
-        (_a2 = this.onError) == null ? void 0 : _a2.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", ErrorCode.playbackStartFailed));
       });
     }
   }
@@ -13409,7 +13449,7 @@ class AvatarController {
     }
     try {
       if (!this.animationPlayer) {
-        throw new AvatarError("Animation player not initialized", "ANIMATION_PLAYER_NOT_INITIALIZED");
+        throw new AvatarError("Animation player not initialized", ErrorCode.animationPlayerNotInitialized);
       }
       await this.animationPlayer.prepareStreamingPlayer(() => {
         var _a2;
@@ -13453,7 +13493,7 @@ class AvatarController {
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       logger.error("[AvatarController] Failed to start streaming playback:", message);
-      (_b = this.onError) == null ? void 0 : _b.call(this, new AvatarError("Failed to start streaming playback", "INIT_FAILED"));
+      (_b = this.onError) == null ? void 0 : _b.call(this, new AvatarError("Failed to start streaming playback", ErrorCode.playbackInitFailed));
       this.isPlaying = false;
       this.isStartingPlayback = false;
     }
@@ -13731,7 +13771,7 @@ class AvatarController {
   async startAudioOnlyPlayback() {
     var _a;
     if (!this.animationPlayer) {
-      throw new AvatarError("Animation player not initialized", "ANIMATION_PLAYER_NOT_INITIALIZED");
+      throw new AvatarError("Animation player not initialized", ErrorCode.animationPlayerNotInitialized);
     }
     try {
       await this.animationPlayer.prepareStreamingPlayer(() => {
@@ -13767,7 +13807,7 @@ class AvatarController {
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       logger.error("[AvatarController] Failed to start audio-only playback:", message);
-      (_a = this.onError) == null ? void 0 : _a.call(this, new AvatarError("Failed to start audio-only playback", "AUDIO_ONLY_INIT_FAILED"));
+      (_a = this.onError) == null ? void 0 : _a.call(this, new AvatarError("Failed to start audio-only playback", ErrorCode.audioOnlyInitFailed));
       this.isPlaying = false;
       this.isFallbackMode = false;
       throw error;
@@ -15678,6 +15718,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;
@@ -15698,15 +15741,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
@@ -16126,6 +16188,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);

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-C2higMlc.js";
+import { b, c, m, f, d, j, g, C, i, D, E, k, h, L, R, n } from "./index-BDOaKeXW.js";
 export {
   b as Avatar,
   c as AvatarController,

package/dist/types/index.d.ts

@@ -65,20 +65,50 @@ export declare enum ConversationState {
 export declare enum ErrorCode {
     /** AppID not recognized (reserved, future appID validation logic) */
     appIDUnrecognized = "appIDUnrecognized",
-    /** AvatarID not recognized */
-    avatarIDUnrecognized = "avatarIDUnrecognized",
-    /** Session Token invalid */
+    /** Session Token invalid (WebSocket close code 4010) */
     sessionTokenInvalid = "sessionTokenInvalid",
-    /** Session Token expired */
+    /** Session Token expired (WebSocket close code 4010) */
     sessionTokenExpired = "sessionTokenExpired",
+    /** Insufficient balance (WebSocket close code 4001) */
+    insufficientBalance = "insufficientBalance",
+    /** Concurrent connection limit exceeded (WebSocket close code 4003) */
+    concurrentLimitExceeded = "concurrentLimitExceeded",
+    /** AvatarID not recognized */
+    avatarIDUnrecognized = "avatarIDUnrecognized",
     /** Failed to fetch avatar metadata */
     failedToFetchAvatarMetadata = "failedToFetchAvatarMetadata",
     /** Failed to download avatar assets */
-    failedToDownloadAvatarAssets = "failedToDownloadAvatarAssets"
+    failedToDownloadAvatarAssets = "failedToDownloadAvatarAssets",
+    /** WebSocket connection error (handshake failure, network error) */
+    websocketError = "websocketError",
+    /** WebSocket connection closed abnormally (close code 1006) */
+    websocketClosedAbnormally = "websocketClosedAbnormally",
+    /** WebSocket closed with unexpected close code */
+    websocketClosedUnexpected = "websocketClosedUnexpected",
+    /** Session timeout (WebSocket close code 4002) */
+    sessionTimeout = "sessionTimeout",
+    /** Connection already in progress */
+    connectionInProgress = "connectionInProgress",
+    /** Network layer not available (SDK mode required) */
+    networkLayerNotAvailable = "networkLayerNotAvailable",
+    /** Failed to start playback */
+    playbackStartFailed = "playbackStartFailed",
+    /** Playback initialization failed */
+    playbackInitFailed = "playbackInitFailed",
+    /** Audio-only playback initialization failed */
+    audioOnlyInitFailed = "audioOnlyInitFailed",
+    /** No audio data to play */
+    noAudio = "noAudio",
+    /** Audio context not initialized */
+    audioContextNotInitialized = "audioContextNotInitialized",
+    /** Animation player not initialized */
+    animationPlayerNotInitialized = "animationPlayerNotInitialized",
+    /** Server-side error */
+    serverError = "serverError"
 }
 export declare class AvatarError extends Error {
-    code?: (string | ErrorCode) | undefined;
-    constructor(message: string, code?: (string | ErrorCode) | undefined);
+    code: ErrorCode;
+    constructor(message: string, code: ErrorCode);
 }
 export interface CameraConfig {
     position: [number, number, number];

package/package.json

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