@spatialwalk/avatarkit 1.0.0-beta.10 → 1.0.0-beta.100

package/CHANGELOG.md

@@ -5,13 +5,774 @@ 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.100]
+
+### ✨ Features
+
+- **RTC rendering support** — Added protobuf-based rendering methods to `AvatarView` for RTC mode integration.
+
+### 🐛 Bugfixes
+
+- **Transform Y-axis direction** — Fixed `avatarTransform.y` direction being inverted compared to iOS/Android. Positive Y now moves avatar upward on all platforms.
+
+## [1.0.0-beta.99]
+
+### ✨ Features
+
+- **Playback diagnostics** — Added telemetry events for audio buffer stall and frame starvation detection, improving visibility into playback interruption issues.
+
+## [1.0.0-beta.98]
+
+### 🐛 Bugfixes
+
+- **Build artifact fix** — beta.97 npm package contained stale build artifacts. This release contains the correct build with all beta.97 changes.
+
+### ⚡ Breaking Changes
+
+- **`setVolume()` / `getVolume()` replaced by `volume` property** — `controller.setVolume(0.5)` is now `controller.volume = 0.5`. Aligned with Android and iOS SDKs.
+
+## [1.0.0-beta.97]
+
+### ⚡ Breaking Changes
+
+- **`transform` renamed to `avatarTransform`** — `avatarView.transform` is now `avatarView.avatarTransform`. Aligned naming across Web, Android, and iOS SDKs.
+
+### ✨ Features
+
+- **Avatar transform from character settings** — Avatar automatically applies position and scale from character settings. User-set `avatarTransform` stacks on top of the base values.
+
+### 🐛 Bugfixes
+
+- **Rendering quality improvement** — Improved color accuracy for avatar rendering.
+
+### 📝 Documentation
+
+- **send() byte alignment** — Documented PCM S16LE byte alignment requirement for `send()`.
+
+## [1.0.0-beta.96]
+
+### 🐛 Bugfixes
+
+- **WASM Loading in Vite Dev Mode** — Fixed WASM pre-validation failing when consumed via Vite dev server. The WASM URL was mangled by the bundler, causing HTTP 431 errors. Now skips pre-validation when the resolved URL is not a valid `.wasm` path, falling back to Emscripten's built-in loader.
+
+## [1.0.0-beta.95]
+
+### 🐛 Bugfixes
+
+- **WebGPU Jacobian Matrix Fix** — Fixed incorrect Jacobian matrix column order in `calcCovariance2D` (WebGPU renderer). The `mat3x3f` constructor takes column vectors, but values were passed in row order, causing transposed 2D covariance and blurry splat edges (especially visible on arms/hands). Android (Vulkan GLSL) and iOS (Metal) were not affected.
+
+### ⚡ Performance
+
+- **WASM Download Integrity & Retry** — Added binary integrity validation (magic number + Content-Length check) and automatic retry (up to 3 attempts) for WASM module loading. Also added Content-Length validation for all resource downloads. Prevents cryptic `CompileError` from truncated or corrupted downloads (e.g. in WeChat browser).
+
+## [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
+
+- **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
+
+- **Inline CPU Benchmark Worker** — Consumers using Vite could not build: `Could not resolve entry module "public/assets/cpu-benchmark-worker-*.js"`. Root cause: `new URL()` worker pattern in Vite library mode compiles to absolute path that downstream bundlers cannot resolve. Fixed by replacing with inline Blob URL worker.
+
+## [1.0.0-beta.90] - 2026-03-18
+
+### 🐛 Bugfixes
+
+- **WASM Core Update** — Updated WASM binary to include CSPLAT v4 compressed point cloud decoder; `useCompressedModel` previously failed with `avatar_core_load_character returned NULL` because the WASM build predated the CSPLAT decoder addition
+
+## [Unreleased]
+
+### ⚡ Breaking Changes
+
+- **Enum Rename** — `ConversationState.pausing` renamed to `ConversationState.paused` for cross-SDK consistency
+- **FrameRateInfo** — Unified as pre-computed fields; sub-stage data (decode/render/present) now available via `FrameRenderInfo`
+
+### ✨ Features
+
+- **FrameRateMonitor** — Unified public API for frame rate monitoring with enable/disable switch
+- **Device Benchmark** — `deviceScore` and `isDeviceSupported` APIs for runtime device capability assessment
+- **Telemetry Enhancements** — `avatar_playback_fps` now reports `cpu_score`, `gpu_score`, and `renderer_backend` (webgl/webgpu)
+- **Deprecation Reset** — Deprecation warnings reset on `initialize()` to avoid stale state across re-init cycles
+- **Compressed Model (Beta)** — `load()` accepts optional `useCompressedModel` parameter (default `false`); when `true`, prefers compressed model resource (~30% of original size, minor quality degradation), falls back to standard resource if unavailable。此功能目前为 Beta，请务必验证渲染效果后再用于生产环境
+
+### ⚡ Performance
+
+- **Audio-Clock-Driven Scheduling** — Speaking playback now uses audio clock for tick scheduling, replacing RAF-based timing for more accurate frame pacing
+- **Idle Present Frame Resubmission** — Idle state uses `presentFrameOnly()` to resubmit the current frame, reducing GPU re-computation
+
+### 🐛 Bugfixes
+
+- **Build Packaging** — WASM binary missing from dist in beta.87; added benchmark-demo and marble-test to dts exclude
+- **Deprecation State** — Fixed stale deprecation warnings persisting across SDK re-initialization
+
+## [1.0.0-beta.88] - 2026-03-10
+
+### 🐛 Bugfixes
+
+- **Build Packaging Fix** - WASM binary was missing from dist in beta.87 npm package; added `benchmark-demo` and `marble-test` to dts exclude to prevent type declaration leakage
+- **Release Workflow** - Added build artifact verification step (WASM presence + no leaked directories)
+
+## [1.0.0-beta.87] - 2026-03-09
+
+### 🔧 Performance
+
+- **Playback Cadence Stabilization** - Replaced RAF + `Math.floor(audioTime*25)` frame dispatch with fixed 25fps tick scheduler and bounded async queue, eliminating bursty frame production
+- **Display Decoupling** - Speaking state uses RAF-driven `presentFrameOnly()` to present latest computed frame (WebGPU only), reducing display-side pacing jitter
+- **WebGL Speaking-State Loop Suspension** - WebGL backend pauses realtime animation loop during Speaking state to avoid redundant `reorderPackedData` CPU work and RAF callback competition
+
+### 🐛 Bugfixes
+
+- **Frame Index Floating-Point Precision** - Added epsilon tolerance (`+1e-6`) to `Math.floor(audioTime * fps)` to prevent IEEE 754 precision errors from producing duplicate frame indices at frame boundaries
+- **WebGL Regression Fix** - Fixed severe WebGL performance regression (jank 9.47%→0.16%) caused by WebGPU-only optimization that triggered 60fps `reorderPackedData` calls on WebGL path
+- **SDK Duplicate Initialize** - Deduplicated SDK initialization to prevent repeated setup when `initialize()` is called multiple times
+
+### ✅ Tests
+
+- **Android Init Coverage** - Added Android duplicate-initialize regression coverage
+
+### 📊 Benchmark
+
+- **beta.86 vs beta.87 Baseline** - Full cross-backend performance comparison (WebGPU + WebGL), 1 warmup + 10 measure rounds, 10s/round. Jank rate reduced 94.6% (WebGPU) and 93.9% (WebGL); frame interval stability improved 64-67%
+
+## [1.0.0-beta.86] - 2026-03-03
+
+### 🐛 Bugfixes
+- **Transition Continuity** - Fixed start transition source frame selection to use the currently displayed idle frame, reducing first-frame jump.
+- **Transition Robustness** - Added frame index clamping for realtime callback and speaking->idle transition source lookup, preventing end-transition fallback jumps caused by out-of-range indices.
+
+### ✅ Tests
+- **State Machine Coverage** - Updated `AvatarView` rendering state tests to align with current dual-transition flow, and added boundary tests for start/end transition frame selection.
+
+## [1.0.0-beta.82] - 2026-02-12
+
+### 🔧 Improvements
+- **Proto V2 协议更新** - 更新解码协议
+
+## [1.0.0-beta.80] - 2026-02-08
+
+### ✨ New Features
+- **Next.js Plugin** - Added `@spatialwalk/avatarkit/next` plugin for Next.js (webpack) projects, automatically handles WASM file configuration, Emscripten scriptDirectory fix, and Content-Type headers
+
+## [1.0.0-beta.79] - 2026-02-08
+
+### ✨ New Features
+- **Camera API** - Exposed `getCameraConfig()` and `updateCameraConfig()` on AvatarView for external real-time camera control
+
+## [1.0.0-beta.78] - 2026-02-04
+
+### 🐛 Bugfixes
+- **Telemetry Accuracy** - Fixed environment field reporting issue in analytics events
+
+### ✨ New Features
+- **Performance Monitoring** - Added loading performance metrics for avatar resources
+  - `fetch_avatar_latency` - Total loading time
+  - `fetch_avatar_metadata_latency` - Metadata fetch time
+  - `download_avatar_assets_latency` - Asset download time
+
+### 🔧 Improvements
+- **Internal Architecture** - Unified configuration constants across platforms for better maintainability
+
+## [1.0.0-beta.74] - 2026-01-22
+
+### 🔧 Improvements
+- **Transition API** - Replaced `generateTransitionFromIdle` with `generateTransition` (options-based API: `from`, `to`, `frameCount`, `useLinear`)
+
+## [1.0.0-beta.73] - 2026-01-22
+
+### ✨ New Features
+- **Local Log Upload** - Automatic local log upload functionality
+
+## [1.0.0-beta.72] - 2026-01-17
+
+### 📚 Documentation
+- **README Optimization** - Enhanced README with authentication section and improved API documentation
+
+## [1.0.0-beta.71] - 2026-01-17
+
+### 🔧 Improvements
+- **Internal API** - Marked all audio and animation internal classes with `@internal` to prevent public API exposure
+- **Type Safety** - Hidden `AnimationPlayer`, `StreamingAudioPlayer`, `AnimationWebSocketClient`, and related utilities from public API
+- **Internal Documentation** - Fixed missing English translations in `AnimationWebSocketClient.ts`
+
+## [1.0.0-beta.70] - 2026-01-17
+
+### 🔧 Improvements
+- **Code Cleanup** - Removed unused `FlatSplatData` interface from public API
+- **Internal Documentation** - Translated all internal code comments to English for consistency
+
+## [1.0.0-beta.69] - 2026-01-17
+
+### 🔧 Improvements
+- **API Documentation** - All public API comments are now in English with JSDoc support for better IDE IntelliSense
+- **Type Safety** - Removed internal types from public API exports
+- **Build Configuration** - JSDoc comments are now preserved in generated `.d.ts` files
+
+### 📚 Documentation
+- Enhanced audio data format documentation with WAV and MP3 processing examples
+
+## [1.0.0-beta.68] - 2026-01-17
+
+### 🐛 Bugfixes
+- **Vite Plugin WASM File Detection** - Fixed Vite plugin not finding WASM files with hash in consuming projects
+  - Plugin now reads JS glue file to extract referenced WASM filename (including hash)
+  - Ensures correct WASM file is copied to match JS glue file references
+  - Prevents 404 errors when WASM files have content-based hashes
+  - Fixes issue where `avatar_core_wasm.wasm` was not found after adding hash support
+
+## [1.0.0-beta.67] - 2026-01-17
+
+### 🐛 Bugfixes
+- **WASM File Hash Support** - Fixed critical issue where WASM files were not being hashed during SDK build
+  - WASM files now automatically get content-based hash (e.g., `avatar_core_wasm-{hash}.wasm`)
+  - JS glue files are automatically updated to reference the hashed WASM filename
+  - Prevents browser cache issues when WASM files are updated
+  - Ensures proper version management and cache invalidation
+
+### 🔧 Improvements
+- **Build Process** - Enhanced SDK build process to automatically handle WASM file hashing
+  - Hash is calculated based on WASM file content (SHA256, first 8 characters)
+  - Build logs now show hash generation progress
+  - Compatible with existing Vite plugin for consuming projects
+
+## [1.0.0-beta.65] - 2026-01-14
+
+### 🐛 Bugfixes
+- **Transition Frame Reset Logic** - Fixed issue where `currentPlayingFrame` was not reset after generating transitions, causing jump artifacts on second conversation
+  - Reset `currentPlayingFrame` to `null` after generating idle->speaking transitions
+  - Reset `currentPlayingFrame` to `null` after generating speaking->idle transitions
+  - Reset `currentPlayingFrame` to `null` when entering Idle state
+  - Ensures each transition starts from the correct current frame by re-fetching the current state frame when needed
+
+## [1.0.0-beta.64] - 2026-01-14
+
+### ✨ New Features
+- **Vite Plugin for WASM Configuration** - Added `avatarkitVitePlugin` to automate WASM file configuration
+  - Automatically handles WASM MIME types in dev server
+  - Copies WASM files to dist/assets/ during build
+  - Generates `_headers` file for Cloudflare Pages deployment
+  - Configures Vite's optimizeDeps, assetsInclude, and assetsInlineLimit
+
+### 🔧 Improvements
+- **Unified Transition Logic** - All transitions now start from the current playing frame, ensuring smooth transitions from any state (Idle, Speaking, or Transitioning)
+- **Idle State Performance** - Optimized idle state to avoid unnecessary frame parameter fetching on every frame
+- **Transition Animation** - Idle->Speaking uses linear interpolation, Speaking->Idle uses Bezier curve easing
+
+### 🐛 Bugfixes
+- Fixed vanilla demo audio context initialization issue
+- Fixed recording button only working once in vanilla demo
+- Fixed host mode data loading to use local files instead of API endpoint
+
+### 📚 Documentation
+- Added transition animation technical specification document for cross-platform alignment
+
+## [1.0.0-beta.63] - 2026-01-14
+
+### ✨ New Features
+- **Audio Context Initialization API** - Added `initializeAudioContext()` method to `AvatarController`
+  - Must be called in a user gesture context (click, touchstart, etc.) before any audio operations
+  - Ensures AudioContext is created and initialized in a user gesture context, preventing browser security policy issues
+  - All audio operations (`send()`, `yieldAudioData()`, `start()`, `playback()`, etc.) now require prior initialization
+
+### 🔧 Improvements
+- **Initialization Flow** - Removed all lazy initialization logic for audio context
+  - Audio context initialization is now centralized in `initializeAudioContext()` method
+  - All audio operations check for initialization before proceeding
+  - Clear error messages when audio operations are attempted without initialization
+
+### 🐛 Bugfixes
+- **Audio Context User Gesture Requirement** - Fixed issue where AudioContext could not be properly initialized when external applications request recording permissions
+  - Audio context must now be initialized in user gesture context, ensuring browser security policies are satisfied
+
+## [1.0.0-beta.62] - 2026-01-14
+
+### ✨ New Features
+- **Bezier Curve Transition Animation** - Implemented Bezier curve easing functions for smoother transitions
+  - Added Bezier curve interpolation with different curves for different facial components (jaw, expression, eye, neck, global)
+  - Replaced linear interpolation with Bezier curve interpolation for more natural animation
+  - Split transition duration into start (200ms) and end (1600ms) for different transition types
+
+### 🔧 Improvements
+- **Transition API Enhancement** - Updated `generateTransitionFromIdle()` to support both start and end transitions
+  - Added `transitionType` parameter: `'start'` for idle-to-speaking, `'end'` for speaking-to-idle
+  - Removed deprecated linear interpolation code and unused easing functions
+
+## [1.0.0-beta.61] - 2026-01-14
+
+### 🔧 Improvements
+- **Telemetry Events Update** - Updated telemetry events with new parameters and structure
+  - `sdk_initialized`: Added `env` and `dsm` parameters
+  - `driving_service_latency`: Replaced `driving_latency`, now tracks `tap_0`, `tap_1`, `tap_2`, `tap_f` timestamps (Number type, milliseconds)
+  - `avatar_active`: New event for avatar view activity tracking with `env` and `dsm` parameters, reported on first render and every 10 minutes
+- **Heartbeat Refactoring** - Removed `HeartbeatManager`, integrated heartbeat functionality into `NetworkLayer` (driving service heartbeat) and `AvatarView` (avatar active heartbeat)
+
+## [1.0.0-beta.60] - 2026-01-14
+
+### 🔧 Configuration Changes
+- **PostHog Configuration** - PostHog telemetry now always uses the international site regardless of environment configuration
+
+## [1.0.0-beta.59] - 2026-01-14
+
+### 🐛 Bugfixes
+- **AudioContext Auto-Resume** - Fixed issue where audio playback would get stuck after external applications request recording permissions. AudioContext now automatically resumes when suspended during playback
+- **PostHog Instance Initialization** - Fixed PostHog named instance initialization to avoid conflicts with external PostHog instances
+
+## [1.0.0-beta.58] - 2026-01-14
+
+### ✨ New Features
+- **Pure Rendering Mode APIs** - Added `renderFrame()` and `generateTransitionFromIdle()` methods to `AvatarView` for external-controlled rendering without audio synchronization
+
+## [1.0.0-beta.57] - 2026-01-09
+
+### 🐛 Bugfixes
+- **Idle Animation Jiggle Fix** - Fixed issue where idle animation would "jiggle" before transitioning to speaking when external audio and animation data were sent. The `handleInterrupt()` method now correctly skips processing when already in `Idle` state, preventing unnecessary idle loop restarts.
+
+## [1.0.0-beta.56] - 2026-01-09
+
+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.56] - 2025-01-05
+
+### ✨ New Features
+- **Eye Tracking Config API** - Changed `eyeTrackingEnabled` to complete `eyefocus` configuration object in `PostProcessingConfig`. External callers must provide full `eyefocus` configuration (enabled, auto_eyelid_adjustment, eyelid_threshold, targets) instead of just a boolean flag.
+
+## [1.0.0-beta.55] - 2025-01-05
+
+### ✨ New Features
+- **Eye Tracking Control** - Added `eyeTrackingEnabled` parameter to `PostProcessingConfig`, allowing external control of eye tracking enable/disable state in real-time
+- **Point Count API** - Added `getPointCount()` method to `AvatarController` to get the point cloud count of the current avatar
+
+## [1.0.0-beta.54] - 2025-01-05
+
+### 🐛 Bugfix
+- **Transition Animation Completion** - Fixed issue where `onTransitionComplete()` was not called when `transitionKeyframes` was empty, causing audio playback to freeze after transition animations. Now, when there are no transition frames, the state correctly transitions to `Speaking` and `onTransitionComplete()` is called to start audio playback.
+
+## [1.0.0-beta.53] - 2025-01-05
+
+### 🐛 Bugfix
+- **Race Condition Fix** - Fixed race condition where `startStreamingPlaybackInternal()` could be called multiple times when `yieldKeyframes` received data rapidly, causing audio chunks to be cleared and playback to freeze after transition animations. Added `isStartingPlayback` flag to prevent concurrent execution.
+
+## [1.0.0-beta.52] - 2025-01-05
+
+### 🔧 Performance Improvements
+- **Telemetry Optimization** - Consolidated resource download telemetry: removed individual `resource_download` events and added cache information (`cache_hit`, `cache_type`) to total duration metrics (`template_resources_load_measure` and `download_avatar_assets_total_measure`). This enables analysis of download times for cache misses while reducing telemetry overhead.
+
+## [1.0.0-beta.51] - 2025-01-05
+
+### 🐛 Bugfix
+- **Character Settings Update** - Fixed issue where cached Avatar instances would not update `characterSettings` in resources when `characterMeta` was updated. Now `resources.characterSettings` is synchronized when `characterMeta` changes, ensuring new `AvatarView` instances use the latest configuration.
+
+### ✨ New Features
+- **Post-Processing Config Enhancement** - Added `translation` and `eyePose` fields to `PostProcessingConfig` interface:
+  - `translation`: Position offset (x, y, z)
+  - `eyePose`: Eye pose offset with bias and weights (x, y, z, weightX, weightY, weightZ), applied to both left and right eyes
+
+## [1.0.0-beta.50] - 2025-01-05
+
+### 🔧 Performance Improvements
+- **Removed CORS Preflight for Meta API** - Removed authentication headers (`X-App-Id` and `Authorization`) and unnecessary `Content-Type` header from avatar metadata API requests. This eliminates CORS preflight requests for simple GET requests, improving loading performance.
+
+## [1.0.0-beta.49] - 2025-01-05
+
+### 🐛 Bugfix
+- **Template Cache Version** - Fixed issue where template cache would be incorrectly cleared when switching between different SDK versions. Now uses independent template resource version (1.0.0) instead of SDK version, allowing different SDK versions to share the same template cache when template resources are identical.
+
+## [1.0.0-beta.48] - 2025-01-05
+
+### ✨ New Features
+- **PWA Cache Management** - Added automatic PWA cache management for avatar and template resources to improve loading performance
+
+### 🔧 Performance Improvements
+- **Cache Hit Rate Metrics** - Resource downloads now report cache status for analytics
+
+## [1.0.0-beta.47] - 2025-12-29
+
+### 🐛 Bugfix
+- **Avatar Meta Update** - Fixed issue where cached Avatar instances would return stale avatar metadata even when the latest metadata was fetched. Now the avatar metadata is always updated to the latest version when loading an avatar, even if the version number hasn't changed.
+
+## [1.0.0-beta.46] - 2025-12-29
+
+### 🐛 Bugfix
+- Expose `getCharacterMeta()` method in `Avatar` class as public API
+
+## [1.0.0-beta.45] - 2025-12-29
+
+### ✨ New Features
+- **Immediate Rendering on Pause** - When playback is paused, updating post-processing parameters or camera configuration will immediately re-render the current frame:
+  - Post-processing parameters (rotation, neck pose, jaw pose, eye blink, etc.) now apply immediately when updated during pause
+  - Camera configuration (position, target, FOV, etc.) now applies immediately when updated during pause
+  - During normal playback, these updates still apply on the next frame as before
+
+### 🔄 API Changes
+
+### 🔄 API Changes
+- **AvatarView Ready Promise Replaced with Callback** - Replaced `ready: Promise<void>` property with `onFirstRendering?: () => void` callback for better async handling:
+  - Removed `ready` Promise property
+  - Added `onFirstRendering` optional callback that is called when the first frame is rendered
+  - Callback-based approach is more idiomatic and easier to use than Promise-based approach
+
+### 🗑️ Removed
+- **Removed unused `seek()` method** - Removed unused and buggy `seek()` method from `StreamingAudioPlayer`
+
+## [1.0.0-beta.44] - 2025-12-29
+
+### 🔧 Performance Improvements
+- **Removed unnecessary headers from static resource requests** - Removed `X-App-Id` and `Authorization` headers from static resource downloads (shape.pb, point_cloud.ply, camera.json, etc.) to avoid CORS preflight requests and improve loading performance
+
+## [1.0.0-beta.43] - 2025-12-29
+
+### 🔧 Improvements
+- Remove some unnecessary telemetry reporting
+
+## [1.0.0-beta.42] - 2025-12-29
+
+### ✨ New Features
+- **PostHog Telemetry Configuration** - PostHog telemetry reporting now supports separate configuration for domestic (CN) and international (INTL) environments:
+  - Separate PostHog hosts and API keys for CN and INTL environments
+  - Compression disabled for domestic self-hosted instance, enabled for international official PostHog
+  - Localhost domain filtering to avoid test data pollution
+
+## [1.0.0-beta.41] - 2025-12-29
+
+### 🔄 Breaking Changes
+- **Background Image Support Removed** - Removed background image functionality from `AvatarView`:
+  - Removed `isOpaque` getter/setter property
+  - Removed `setBackgroundImage()` method
+  - Removed background image loading from `AvatarDownloader`
+  - Canvas now always uses transparent background
+
+## [1.0.0-beta.40] - 2025-12-27
+
+### 🔧 API Improvements
+- Extended post-processing parameter configuration interface
+
+## [1.0.0-beta.39] - 2025-12-27
+
+### 🔧 Improvements
+- Filter localhost domain from telemetry reporting to avoid test data pollution
+
+## [1.0.0-beta.38] - 2025-12-27
+
+### 🔄 Breaking Changes
+- Migrated telemetry reporting from Tencent Cloud CLS to PostHog
+
+### ✨ New Features
+- Implemented download queue for character resource loading
+
+## [1.0.0-beta.37] - 2025-12-24
+
+### 🐛 Bugfix
+- Various bug fixes and improvements
+
+## [1.0.0-beta.36] - 2025-12-20
+
+### ✨ New Features
+- **Audio Sample Rate Configuration** - Added configurable audio sample rate support in SDK initialization
+  - Added `audioFormat` configuration option with `channelCount` (fixed to 1) and `sampleRate` (supports: 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz, default: 16000)
+  - Audio recording and playback now automatically use the configured sample rate
+  - Vanilla demo updated with sample rate dropdown selector for easy testing
+
+## [1.0.0-beta.35] - 2025-12-16
+
+### 🔄 API Changes
+- **Avatar Transform API** - Changed `setTransform` method to `transform` getter/setter property for more idiomatic JavaScript API. Now supports both reading and setting transform values.
+
+## [1.0.0-beta.34] - 2025-12-16
+
+### ✨ New Features
+- **Avatar Transform API** - Added `setTransform` method to `AvatarView` for controlling avatar position and scale within the canvas. Supports normalized coordinates (-1 to 1) for position and scale factor.
+
+## [1.0.0-beta.32] - 2025-12-16
+
+### 🔄 Breaking Changes
+- **Host Mode Interface** - Updated `yieldFramesData` method to accept binary data array instead of single binary data. The method now processes multiple protobuf-encoded Message objects in a single call.
+
+## [1.0.0-beta.31] - 2025-12-16
+
+### 🐛 Bugfix
+- **Environment CORS Issue** - Fixed CORS issues when requesting configuration and avatar data APIs. SDK now provides default configuration fallback when config requests fail, ensuring smooth operation across different environments.
+
+## [1.0.0-beta.30] - 2025-12-15
+
+### 🐛 Bugfix
+- **Template Resources Duplicate Download** - Fixed issue where template resources were being re-downloaded for each new avatar load. Template resources are now only loaded once during SDK initialization and reused for all avatars.
+
+## [1.0.0-beta.29] - 2025-12-15
+
+### 🔄 Breaking Changes
+- **Environment Enum** - Removed `Environment.test`. Only `Environment.cn` and `Environment.intl` are now supported. Environment configuration must be explicitly provided.
+- **Log Level Default** - Default log level changed from `LogLevel.all` to `LogLevel.off`. Set `logLevel: LogLevel.all` in configuration to enable all logs.
+
+### ✨ New Features
+- **Avatar Caching** - Added avatar caching methods in `AvatarManager`:
+  - `retrieve(id: string): Avatar | undefined` - Get cached avatar by ID
+  - `clear(id: string): void` - Clear cached avatar for specific ID
+  - `clearAll(): void` - Clear all cached avatars
+  - `clearCache()` is now deprecated, use `clearAll()` instead
+- **Background Image Support** - Added background image control in `AvatarView`:
+  - `isOpaque: boolean` - Getter/setter to control canvas background transparency
+  - `setBackgroundImage(image: HTMLImageElement | string | null): void` - Set or remove background image
+
+### 🔧 Improvements
+- **Avatar Version Checking** - Avatar cache now automatically checks version and reloads if cached avatar version differs from latest metadata
+- **Concurrent Loading** - Multiple concurrent `load()` calls for the same avatar ID now reuse the same loading promise
+
+## [1.0.0-beta.28] - 2025-12-08
+
+### 🔄 Breaking Changes
+- **Class Renamed** - `AvatarKit` class has been renamed to `AvatarSDK` for better consistency
+  - Update all imports: `import { AvatarKit } from '@spatialwalk/avatarkit'` → `import { AvatarSDK } from '@spatialwalk/avatarkit'`
+  - Update all API calls: `AvatarKit.initialize()` → `AvatarSDK.initialize()`
+  - All static methods and properties remain the same, only the class name has changed
+
+### 🔧 Improvements
+- **Rendering Optimizations** - Added fragment shader discard optimization to improve performance and edge quality
+- **Shader Alignment** - Removed view matrix transpose to align with Android SDK implementation
+- **Resource Cleanup** - Removed unused `frameMono` and `audioMono` resources from SDK and tests
+
+## [1.0.0-beta.27] - 2025-12-04
+
+### 🐛 Bugfix
+
+## [1.0.0-beta.26] - 2025-12-03
+
+### ✨ New Features
+- **Log Level Configuration** - Added `logLevel` configuration option to control SDK logging verbosity
+  - `LogLevel.off` - Disable all logs
+  - `LogLevel.error` - Only error logs
+  - `LogLevel.warning` - Warning and error logs
+  - `LogLevel.all` - All logs (default)
+- **Standardized CLS Logging Events** - All CLS logging events now use standardized field names for better querying
+  - Standard events: `sdk_initialized`, `send_audio_failed`, `message_error`, `heartbeat_failed`, `service_restarted`, `session_token_invalid`, `session_token_expired`, `yield_animation_failed`, `fetch_avatar_metadata_failed`, `download_avatar_assets_failed`, `avatar_active`
+  - Standard fields: `req_id`, `con_id`, `avatar_id`, `description`
+- **End-to-End Latency Tracking** - Added `driving_service_latency` event to track latency metrics for both SDK and Host modes
+  - Tracks: `tap_0`, `tap_1`, `tap_2`, `tap_f` timestamps (Number type, milliseconds)
+  - Automatically reported once per conversation when first frame is received
+
+### 🔧 Improvements
+- **CLS Configuration Alignment** - Updated CLS endpoints and Topic IDs to match iOS SDK configuration
+- **Default API Endpoints** - Fixed default API endpoint for `intl` environment to `api.intl.spatialwalk.cloud`
+- **Error Code Enum** - Added new error codes: `appIDUnrecognized`, `sessionTokenInvalid`, `sessionTokenExpired`, `failedToFetchAvatarMetadata`, `failedToDownloadAvatarAssets`
+
+### 🗑️ Removed
+- **Redundant Log Events** - Removed unnecessary log events: `playback_paused`, `playback_resumed`, `reconnecting`, `connect_success`, `server_error`, `decode_failed`
+
+## [1.0.0-beta.25] - 2025-12-03
+
+### 🔧 Improvements
+- **Removed Audio Buffer Limit** - Removed the 100 chunk limit on pending audio buffers to allow unlimited audio data buffering
+
+## [1.0.0-beta.24] - 2025-11-26
+
+### 🔧 API Changes
+- **Backend Endpoints Updated** - Backend API endpoints have been updated for all environments
+
+## [1.0.0-beta.23] - 2025-11-26
+
+### 🔧 API Changes
+- **Breaking Change** - `playback()` method is no longer supported and has been removed from public API
+
+## [1.0.0-beta.22] - 2025-11-26
+
+### 🔧 API Changes
+- **State Callback Renamed** - `onAvatarState` has been renamed to `onConversationState` for better clarity
+  - The callback now uses `ConversationState` enum with states: `idle` and `playing`
+- **Environment Enum Updated** - `Environment.us` has been renamed to `Environment.intl` for better internationalization support
+  - All references to `Environment.us` should be updated to `Environment.intl`
+  - Remote config endpoints now use `intl` instead of `us`
+
+### ✨ New Features
+- **Volume Control** - Added volume control API for audio playback
+  - `setVolume(volume: number)` - Set audio volume (0.0 to 1.0)
+  - `getVolume(): number` - Get current audio volume
+  - Volume control only affects the avatar's audio player, not system volume
+  - Volume changes take effect immediately, including for currently playing audio
+
+## [1.0.0-beta.21] - 2025-11-25
+
+### ✨ New Features
+- **SDK Mode Connection Timeout Fallback** - Enhanced fallback mechanism for SDK mode:
+  - If WebSocket connection fails to establish within 15 seconds, the SDK automatically enters fallback mode
+  - In fallback mode, audio data can still be sent and will play normally, even though no animation data will be received
+  - Connection failures also trigger this fallback mechanism
+  - `ConnectionState.connecting` and `ConnectionState.failed` events are emitted to notify external applications
+  - Concurrent connection attempts are prevented to avoid race conditions
+
+### 🔧 Improvements
+- Improved connection state management: `isConnected` now accurately reflects actual connection status (false in fallback mode)
+- Added `canSend()` method in `NetworkLayer` to check if audio can be sent (including fallback mode)
+- Better separation of concerns: connection state checks are now handled by `NetworkLayer`, while playback logic remains in `AvatarController`
+
+## [1.0.0-beta.20] - 2025-11-25
+
+### 🔧 Improvements
+- Removed 1-second audio buffer requirement for auto-starting playback in Host mode
+
+## [1.0.0-beta.19] - 2025-11-25
+
+### 📚 Documentation
+- **Fixed misleading documentation** - Corrected Host mode API documentation to accurately reflect that `yieldAudioData()` can be called directly to start a new session without requiring `playback()` first
+  - Removed misleading "after playback() is called" comments
+  - Clarified two ways to start a session: using `playback()` for existing data, or `yieldAudioData()` directly for streaming
+  - Updated all examples and workflow descriptions to reflect correct API usage
+
+## [1.0.0-beta.18] - 2025-11-25
+
+### 🔧 API Changes
+- **Renamed `reqId` to `conversationId`** - Updated terminology for better clarity
+  - All methods and parameters that used `reqId` now use `conversationId`
+  - `getCurrentReqId()` → `getCurrentConversationId()`
+  - `generateReqId()` → `generateConversationId()`
+  - Updated all event logs and documentation to use `conversationId`
+  - Note: Protobuf protocol still uses `reqId` field name internally, but SDK API uses `conversationId`
+
+### 📚 Documentation
+- Enhanced Host mode documentation to clearly emphasize the workflow: send audio data first to get conversationId, then use that conversationId to send animation data
+- Updated Host Mode Example and Host Mode Flow sections with clearer step-by-step instructions
+
+## [1.0.0-beta.17] - 2025-11-24
+
+### ✨ New Features
+- **Audio-Only Fallback Mechanism** - SDK now includes automatic fallback to audio-only playback when animation data is unavailable
+  - SDK mode: Automatically enters audio-only mode when server returns an error
+  - Host mode: Automatically enters audio-only mode when empty animation data is provided
+  - Once in audio-only mode, subsequent animation data for that session is ignored
+  - Fallback mode is interruptible, just like normal playback mode
+
+### 🔧 API Changes
+- **Playback Mode Configuration** - Moved playback mode configuration from `AvatarView` constructor to `AvatarSDK.initialize()`
+  - Playback mode is now determined by `drivingServiceMode` in `AvatarSDK.initialize()` configuration
+  - `AvatarView` constructor now only requires `avatar` and `container` parameters
+  - Removed `AvatarViewOptions` interface
+  - `container` parameter is now required (no longer optional)
+- **Method Renames** - Renamed methods in `AvatarController` for Host mode to better reflect their purpose
+  - `play()` → `playback()`: Renamed to better reflect that the method is used for playback of existing data (replay mode)
+    - Old API: `avatarController.play(initialAudioChunks, initialKeyframes)`
+    - New API: `avatarController.playback(initialAudioChunks, initialKeyframes)`
+  - `sendAudioChunk()` → `yieldAudioData()`: Renamed to better reflect that the method yields/streams audio data
+    - Old API: `avatarController.sendAudioChunk(data, isLast)`
+    - New API: `avatarController.yieldAudioData(data, isLast)`
+  - `sendKeyframes()` → `yieldFramesData()`: Renamed to better reflect that the method yields/streams animation keyframes
+    - Old API: `avatarController.sendKeyframes(keyframes, reqId)`
+    - New API: `avatarController.yieldFramesData(keyframes, conversationId)`
+
+### 🔧 Improvements
+- Extended transition animation duration from 200ms to 400ms for smoother end-of-playback transitions
+
+### 📚 Documentation
+- Updated README.md to use "SDK mode" and "Host mode" terminology instead of "Network mode" and "External data mode"
+- Added fallback mechanism documentation
+- Updated API reference to reflect new constructor signature
+
+## [1.0.0-beta.16] - 2025-11-21
+
+### ✨ New Features
+- **Multi-AvatarView Support** - SDK now supports multiple `AvatarView` instances simultaneously
+  - Each `AvatarView` instance can manage its own avatar independently
+  - Multiple avatars can be displayed and controlled at the same time
+  - Each instance maintains its own rendering context, playback state, and network connection
+  - Removed the previous limitation of "only one AvatarView instance at a time"
+
+### 📚 Documentation
+- Updated README.md to reflect multi-avatar support capabilities
+- Added multi-avatar usage examples
+- Removed outdated limitation notes about single AvatarView instance
+
+---
+
+## [1.0.0-beta.15] - 2025-11-20
+
+### ✨ New Features
+- Added authentication support for API requests
+  - `appId` is now automatically included in HTTP headers (`X-App-Id`) and WebSocket URL query parameters
+  - `sessionToken` is now automatically included in HTTP headers (`Authorization: Bearer {token}`) and WebSocket URL query parameters
+  - All network requests (avatar loading, resource downloads, WebSocket connections) now include authentication credentials
+
+### 🔧 Improvements
+- Fixed canvas resize handling for different aspect ratios
+  - Projection matrix is now correctly updated when canvas aspect ratio changes
+  - Rendering system properly handles portrait (9:16) and landscape (16:9) aspect ratios
+  - Canvas automatically adapts to container size changes via ResizeObserver
+
+### 🐛 Bug Fixes
+- Fixed `RenderSystem.handleResize()` to update projection matrix when canvas size changes
+  - Previously only updated aspect ratio, now also updates projection matrix for correct rendering
+
+---
+
+## [1.0.0-beta.14] - 2025-11-18
+
+### ✨ New Features
+- Added pause and resume functionality for avatar playback
+  - New `pause()` method to pause audio and animation playback
+  - New `resume()` method to resume playback from paused state
+  - Added `paused` state to `AvatarState` enum
+  - State changes are communicated via `onAvatarState` callback
+  - Works in both network mode and external data mode
+
+### 🔧 Improvements
+- Canvas now uses container's full dimensions instead of fixed 1:1 aspect ratio
+  - Canvas automatically adapts to container size (width and height)
+  - External developers can control canvas aspect ratio by setting container dimensions
+  - Rendering system correctly handles any aspect ratio without distortion
+
+---
+
+## [1.0.0-beta.13] - 2025-11-17
+
+### 🔒 API Improvements
+- Reduced console noise by setting default log level to Warning
+  - Logger now only outputs warnings and errors by default
+  - Set `VITE_DEBUG_LOG=true` to enable all logs
+  - Simplified logger configuration using `setGlobalLogLevel(LogLevel.Warning)`
+
+### 🐛 Bug Fixes
+- Fixed SDK config loader warning in non-debug mode
+  - Config loading failures are now silently handled in production
+  - Warnings only shown when `VITE_DEBUG_LOG=true`
+
+---
+
+## [1.0.0-beta.12] - 2025-11-17
+
+### 🔒 API Improvements
+- Marked performance monitoring APIs as internal
+  - `RenderPerformanceStats` interface and `getPerformanceStats()` method are now marked with `@internal` tag
+  - These APIs are not exposed in the public TypeScript definitions
+  - Reverted performance monitoring implementation to simpler version (only `renderTime` and `sortTime`)
+
+---
+
+## [1.0.0-beta.11] - 2025-11-17
+
+### 📚 Documentation
+- Updated demo repository link in README.md
+  - Changed example project link from `Avatarkit-web-demo` to `AvatarSDK-Web-Demo` to match the new repository name
+
+---
+
 ## [1.0.0-beta.10] - 2025-11-16
 
 ### 🔒 API Improvements
 - Cleaned up public API to hide internal implementation details
   - Marked internal methods with `@internal` JSDoc tag to exclude them from TypeScript declarations
   - Removed unused environment configuration options (`realtimeApiBaseUrl`, `realtimeWsUrl`)
-  - Added `appId` getter to `AvatarKit` for accessing initialized app ID
+  - Added `appId` getter to `AvatarSDK` for accessing initialized app ID
   - Internal methods like `getEnvironmentConfig`, `logEvent`, `getCanvas`, `getCameraConfig`, `updateCameraConfig` are now properly hidden from public API
 
 ### 🐛 Bug Fixes
@@ -58,7 +819,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.0.0-beta.5] - 2025-11-14
 
 ### 🐛 Bug Fixes
-- Fixed missing `AvatarPlaybackMode` enum export in published package
+- Fixed missing `DrivingServiceMode` enum export in published package
 
 ---
 
@@ -87,7 +848,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **External Data Mode**:
   - External components fully control audio and animation data acquisition
   - SDK only responsible for synchronized playback of externally provided data
-  - Use `controller.play()`, `controller.sendAudioChunk()` and `controller.sendKeyframes()` methods
+  - Use `controller.playback()`, `controller.yieldAudioData()` and `controller.yieldFramesData()` methods
 
 ### ✨ New Features
 
@@ -123,7 +884,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   // New API
   new AvatarView(avatar, {
     container: container,
-    playbackMode: AvatarPlaybackMode.network // or AvatarPlaybackMode.external
+    playbackMode: DrivingServiceMode.sdk // or DrivingServiceMode.host
   })
   ```