@spatialwalk/avatarkit 1.0.0-beta.82 → 1.0.0-beta.84

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.84] - 2026-03-03
+
+### 🐛 Bugfixes
+- **End-Transition Continuity** - Fixed the visual jump after conversation end transition by resetting idle frame cursor when returning to `Idle` state
+
+## [1.0.0-beta.83] - 2026-03-03
+
+### 🐛 Bugfixes
+- **Playback Startup Sync** - Improved startup sequencing for SDK mode playback to reduce transition/audio desync at conversation start
+- **Initialization Guard** - Added explicit `appId` validation in `AvatarSDK.initialize()` to fail fast when `appId` is empty
+
+### 🔧 Improvements
+- **Server Error Propagation** - `onError` now consistently receives `AvatarError` with server message and mapped error code for `MESSAGE_SERVER_ERROR` in SDK mode
+
+### 📚 Documentation
+- **README Error Callback** - Added detailed `onError` callback behavior and server error code mapping documentation
+
 ## [1.0.0-beta.82] - 2026-02-12
 
 ### 🔧 Improvements

package/README.md

@@ -1,14 +1,12 @@
 # AvatarKit SDK
 
-Real-time virtual avatar rendering SDK based on 3D Gaussian Splatting, supporting audio-driven animation rendering and high-quality 3D rendering.
+Real-time virtual avatar rendering SDK for Web, supporting audio-driven animation and high-quality 3D rendering.
 
 ## 🚀 Features
 
-- **3D Gaussian Splatting Rendering** - Based on the latest point cloud rendering technology, providing high-quality 3D virtual avatars
-- **Audio-Driven Real-Time Animation Rendering** - Users provide audio data, SDK handles receiving animation data and rendering
+- **High-Quality 3D Rendering** - GPU-accelerated avatar rendering with automatic backend selection
+- **Audio-Driven Real-Time Animation** - Send audio data, SDK handles animation and rendering
 - **Multi-Avatar Support** - Support multiple avatar instances simultaneously, each with independent state and rendering
-- **WebGPU/WebGL Dual Rendering Backend** - Automatically selects the best rendering backend for compatibility
-- **WASM High-Performance Computing** - Uses C++ compiled WebAssembly modules for geometric calculations
 - **TypeScript Support** - Complete type definitions and IntelliSense
 - **Modular Architecture** - Clear component separation, easy to integrate and extend
 
@@ -65,10 +63,6 @@ The plugin automatically handles:
 
 - ✅ **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
 
@@ -128,7 +122,7 @@ export default withAvatarkit({
 
 The plugin automatically handles:
 
-- ✅ **Emscripten Fix**: Patches `scriptDirectory` so the WASM glue file correctly resolves assets at `/_next/static/chunks/` instead of a build-time `file://` path
+- ✅ **Path Fix**: Patches asset path resolution so WASM files are correctly loaded at `/_next/static/chunks/`
 - ✅ **WASM Copying**: Copies `.wasm` files into `static/chunks/` via a custom webpack plugin (client build only)
 - ✅ **Content-Type Headers**: Adds `application/wasm` response header for `/_next/static/chunks/*.wasm`
 - ✅ **Config Chaining**: Preserves your existing `webpack` and `headers` configurations
@@ -146,7 +140,7 @@ The App ID is used to identify your application. You can obtain your App ID by:
 
 ### Session Token
 
-The Session Token is required for WebSocket authentication and must be obtained from your SDK provider.
+The Session Token is required for authentication and must be obtained from your SDK provider.
 
 **⚠️ Important Notes:**
 - The Session Token must be valid and not expired
@@ -204,7 +198,7 @@ import {
 const configuration: Configuration = {
   environment: Environment.cn,
   drivingServiceMode: DrivingServiceMode.sdk, // Optional, 'sdk' is default
-  // - DrivingServiceMode.sdk: SDK mode - SDK handles WebSocket communication
+  // - DrivingServiceMode.sdk: SDK mode - SDK handles network communication
   // - DrivingServiceMode.host: Host mode - Host app provides audio and animation data
   logLevel: LogLevel.off, // Optional, 'off' is default
   // - LogLevel.off: Disable all logs
@@ -233,7 +227,7 @@ const avatar = await avatarManager.load('character-id', (progress) => {
 
 // 3. Create view (automatically creates Canvas and AvatarController)
 // The playback mode is determined by drivingServiceMode in AvatarSDK configuration
-// - DrivingServiceMode.sdk: SDK mode - SDK handles WebSocket communication
+// - DrivingServiceMode.sdk: SDK mode - SDK handles network communication
 // - DrivingServiceMode.host: Host mode - Host app provides audio and animation data
 const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
@@ -290,20 +284,12 @@ This SDK supports two usage modes:
 
 ## 🏗️ Architecture Overview
 
-### Three-Layer Architecture
-
-The SDK uses a three-layer architecture for clear separation of concerns:
-
-1. **Rendering Layer (AvatarView)** - Responsible for 3D rendering only
-2. **Playback Layer (AvatarController)** - Manages audio/animation synchronization and playback
-3. **Network Layer** - Handles WebSocket communication (only in SDK mode, internal implementation)
-
 ### Core Components
 
 - **AvatarSDK** - SDK initialization and management
 - **AvatarManager** - Avatar resource loading and management
-- **AvatarView** - 3D rendering view (rendering layer)
-- **AvatarController** - Audio/animation playback controller (playback layer)
+- **AvatarView** - 3D rendering view
+- **AvatarController** - Audio/animation playback controller
 
 ### Playback Modes
 
@@ -311,7 +297,7 @@ The SDK supports two playback modes, configured in `AvatarSDK.initialize()`:
 
 #### 1. SDK Mode (Default)
 - Configured via `drivingServiceMode: DrivingServiceMode.sdk` in `AvatarSDK.initialize()`
-- SDK handles WebSocket communication automatically
+- SDK handles network communication automatically
 - Send audio data via `AvatarController.send()`
 - SDK receives animation data from backend and synchronizes playback
 - Best for: Real-time audio input scenarios
@@ -329,33 +315,27 @@ The SDK supports two playback modes, configured in `AvatarSDK.initialize()`:
 
 The SDK includes a fallback mechanism to ensure audio playback continues even when animation data is unavailable:
 
-- **SDK Mode Connection Failure**: If WebSocket connection fails to establish within 15 seconds, the SDK automatically enters fallback mode. In this mode, audio data can still be sent and will play normally, even though no animation data will be received from the server. This ensures that audio playback is not interrupted even when the service connection fails.
-- **SDK Mode Server Error**: If the server returns an error after connection is established, the SDK automatically enters audio-only mode for that session and continues playing audio independently.
+- **SDK Mode Connection Failure**: If connection fails to establish within 15 seconds, the SDK automatically enters fallback mode. Audio data can still be sent and will play normally, even though no animation data will be received. This ensures audio playback is not interrupted.
+- **SDK Mode Server Error**: If the server returns an error after connection is established, the SDK automatically enters audio-only mode for that session.
 - **Host Mode**: If empty animation data is provided (empty array or undefined), the SDK automatically enters audio-only mode.
 - Once in audio-only mode, any subsequent animation data for that session will be ignored, and only audio will continue playing.
 - The fallback mode is interruptible, just like normal playback mode.
-- Connection state callbacks (`onConnectionState`) will notify you when connection fails or times out, allowing you to handle the fallback state appropriately.
+- Connection state callbacks (`onConnectionState`) will notify you when connection fails or times out.
 
 ### Data Flow
 
 #### SDK Mode Flow
 
 ```
-User audio input (16kHz mono PCM16) 
-    ↓
-AvatarController.send() 
-    ↓
-WebSocket → Backend processing
+Audio input (PCM16 mono)
     ↓
-Backend returns animation data (FLAME keyframes) 
+AvatarController.send()
     ↓
-AvatarController → AnimationPlayer
+Backend processing → Animation data
     ↓
-FLAME parameters → AvatarCore.computeFrameFlatFromParams() → Splat data
+SDK synchronizes audio + animation playback
     ↓
-AvatarController (playback loop) → AvatarView.renderRealtimeFrame()
-    ↓
-RenderSystem → WebGPU/WebGL → Canvas rendering
+GPU rendering → Canvas
 ```
 
 #### Host Mode Flow
@@ -363,17 +343,12 @@ RenderSystem → WebGPU/WebGL → Canvas rendering
 ```
 External data source (audio + animation)
     ↓
-AvatarController.yieldAudioData(audioChunk) // Returns conversationId
-    ↓
-AvatarController.yieldFramesData(keyframesDataArray, conversationId) // keyframesDataArray: (Uint8Array | ArrayBuffer)[] - each element is a protobuf encoded Message
-    ↓
-AvatarController → AnimationPlayer (synchronized playback)
+AvatarController.yieldAudioData(audioChunk)       → returns conversationId
+AvatarController.yieldFramesData(dataArray, conversationId)
     ↓
-FLAME parameters → AvatarCore.computeFrameFlatFromParams() → Splat data
+SDK synchronizes audio + animation playback
     ↓
-AvatarController (playback loop) → AvatarView.renderRealtimeFrame()
-    ↓
-RenderSystem → WebGPU/WebGL → Canvas rendering
+GPU rendering → Canvas
 ```
 
 ### Audio Format Requirements
@@ -545,7 +520,7 @@ manager.clearAll()
 
 ### AvatarView
 
-3D rendering view (rendering layer), responsible for 3D rendering only. Internally automatically creates and manages `AvatarController`.
+3D rendering view, responsible for 3D rendering only. Internally automatically creates and manages `AvatarController`.
 
 ```typescript
 constructor(avatar: Avatar, container: HTMLElement)
@@ -608,7 +583,7 @@ await currentAvatarView.controller.start()
 
 ### AvatarController
 
-Audio/animation playback controller (playback layer), manages synchronized playback of audio and animation. Automatically handles WebSocket communication in SDK mode.
+Audio/animation playback controller, manages synchronized playback of audio and animation. Automatically handles network communication in SDK mode.
 
 **Two Usage Patterns:**
 
@@ -623,9 +598,9 @@ button.addEventListener('click', async () => {
   // Initialize audio context - MUST be in user gesture context
   await avatarView.controller.initializeAudioContext()
   
-  // Start WebSocket service
+  // Start service
   await avatarView.controller.start()
-  
+
   // Send audio data (must be mono PCM16 format matching configured sample rate)
   const conversationId = avatarView.controller.send(audioData: ArrayBuffer, end: boolean)
   // Returns: conversationId - Conversation ID for this conversation session
@@ -633,7 +608,7 @@ button.addEventListener('click', async () => {
   // 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
 })
 
-// Close WebSocket service
+// Close service
 avatarView.controller.close()
 ```
 
@@ -657,7 +632,7 @@ button.addEventListener('click', async () => {
 
   // Stream animation keyframes (requires conversationId from audio data)
   avatarView.controller.yieldFramesData(
-    keyframesDataArray: (Uint8Array | ArrayBuffer)[],  // Animation keyframes binary data array (each element is a protobuf encoded Message)
+    keyframesDataArray: (Uint8Array | ArrayBuffer)[],  // Animation keyframes binary data array
     conversationId: string                              // Conversation ID (required)
   )
 })
@@ -702,7 +677,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) => {}
+avatarView.controller.onError = (error: Error) => {} // Usually AvatarError (includes code for SDK/server errors)
 ```
 
 #### Avatar Transform Methods
@@ -763,9 +738,9 @@ enum LogLevel {
 **Note:** `LogLevel.off` completely disables all logging, including error logs. Use with caution in production environments.
 
 **Description:**
-- `environment`: Specifies the environment (cn/intl), SDK will automatically use the corresponding API address and WebSocket address based on the environment
+- `environment`: Specifies the environment (cn/intl), SDK will automatically use the corresponding server addresses based on the environment
 - `drivingServiceMode`: Specifies the driving service mode
-  - `DrivingServiceMode.sdk` (default): SDK mode - SDK handles WebSocket communication automatically
+  - `DrivingServiceMode.sdk` (default): SDK mode - SDK handles network communication automatically
   - `DrivingServiceMode.host`: Host mode - Host application provides audio and animation data
 - `logLevel`: Controls the verbosity of SDK logs
   - `LogLevel.off` (default): Disable all logs
@@ -835,12 +810,7 @@ enum ConversationState {
 
 ## 🎨 Rendering System
 
-The SDK supports two rendering backends:
-
-- **WebGPU** - High-performance rendering for modern browsers
-- **WebGL** - Better compatibility for traditional rendering
-
-The rendering system automatically selects the best backend, no manual configuration needed.
+The SDK automatically selects the best rendering backend for your browser, no manual configuration needed.
 
 ## 🚨 Error Handling
 
@@ -865,12 +835,26 @@ try {
 ### Error Callbacks
 
 ```typescript
+import { AvatarError } from '@spatialwalk/avatarkit'
+
 avatarView.controller.onError = (error: Error) => {
-  console.error('AvatarController error:', error)
-  // Handle error, such as reconnection, user notification, etc.
+  if (error instanceof AvatarError) {
+    console.error('AvatarController error:', error.message, error.code)
+    return
+  }
+
+  console.error('AvatarController unknown error:', error)
 }
 ```
 
+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"`)
+
 ## 🔄 Resource Management
 
 ### Lifecycle Management
@@ -886,7 +870,7 @@ await avatarView.controller.start()
 // Use
 avatarView.controller.send(audioData, false)
 
-// Cleanup - dispose() automatically cleans up all resources including WebSocket connections
+// Cleanup - dispose() automatically cleans up all resources including connections
 avatarView.dispose()
 ```
 
@@ -899,26 +883,25 @@ const avatarView = new AvatarView(avatar, container)
 
 // Use
 const conversationId = avatarView.controller.yieldAudioData(audioChunk, false)
-avatarView.controller.yieldFramesData(keyframesDataArray, conversationId) // keyframesDataArray: (Uint8Array | ArrayBuffer)[]
+avatarView.controller.yieldFramesData(keyframesDataArray, conversationId)
 
 // Cleanup - dispose() automatically cleans up all resources including playback data
 avatarView.dispose()
 ```
 
-**⚠️ Important Notes:** 
+**⚠️ Important Notes:**
 - `dispose()` automatically cleans up all resources, including:
-  - WebSocket connections (SDK mode)
+  - Network 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
+- If you need to manually close 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
 
-- SDK automatically manages WASM memory allocation
+- SDK automatically manages memory allocation
 - Supports dynamic loading/unloading of avatar and animation resources
-- Provides memory usage monitoring interface
 
 ## 🌐 Browser Compatibility
 

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

package/dist/core/AvatarController.d.ts

@@ -6,7 +6,7 @@ export declare class AvatarController {
     private isStartingPlayback;
     private currentConversationId;
     private reqEnd;
-    onConnectionState: ((state: ConnectionState) => void) | null;
+    onConnectionState: ((state: ConnectionState, error?: Error) => void) | null;
     onConversationState: ((state: ConversationState) => void) | null;
     onError: ((error: Error) => void) | null;
     private eventListeners;
@@ -21,7 +21,7 @@ export declare class AvatarController {
     private readonly KEYFRAMES_CLEANUP_THRESHOLD;
     private lastSyncLogTime;
     private lastOutOfBoundsState;
-    private isAudioOnlyMode;
+    private isFallbackMode;
     private playbackStuckCheckState;
     private readonly MAX_AUDIO_TIME_ZERO_COUNT;
     private readonly MAX_AUDIO_TIME_STUCK_COUNT;

package/dist/core/AvatarView.d.ts

@@ -13,16 +13,14 @@ export declare class AvatarView {
     private currentKeyframes;
     private lastRenderedFrameIndex;
     private lastRealtimeProtoFrame;
-    private idleAnimationLoopId;
-    private realtimeAnimationLoopId;
+    private renderLoopId;
+    private endTransitionFrames;
+    private isConversationActive;
     private resizeObserver;
     private onWindowResize;
     private frameCount;
     private lastFpsUpdate;
     private currentFPS;
-    private transitionKeyframes;
-    private transitionStartTime;
-    private readonly startTransitionDurationMs;
     private readonly endTransitionDurationMs;
     private cachedIdleFirstFrame;
     private idleCurrentFrameIndex;