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

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.93]
+
+### 🐛 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-DWVeTI7D.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-CDywZ8iv.js";
 class StreamingAudioPlayer {
   // Mark if AudioContext is being resumed, avoid concurrent resume requests
   constructor(options) {