@spatius/avatarkit 0.5.0 → 1.1.0-beta.1

package/CHANGELOG.md

@@ -1,22 +1,36 @@
 # Changelog
 
-## [0.5.0] - 2026-05-14
-
-Initial release.
-
-### Features
-- Real-time 3D avatar rendering powered by WebGL/WebGPU + WASM.
-- Streaming audio-driven animation with low-latency lip sync.
-- SDK mode and host mode for the driving service.
-- Animation state callbacks (idle, speaking, fallback transitions).
-- Telemetry built in (PostHog).
-- Vite and Next.js plugins for zero-config WASM asset handling.
-
-### Public API
-- `AvatarSDK` – SDK lifecycle, configuration, session token, device support.
-- `AvatarManager` – avatar resource loading and caching.
-- `Avatar` / `AvatarView` / `AvatarController` – rendering and conversation control.
-- Types: `Configuration`, `AudioFormat`, `ConnectionState`, `ConversationState`, `DrivingServiceMode`, `LogLevel`, `LoadProgressInfo`, `CameraConfig`, `PostProcessingConfig`, `AvatarError`.
-
-### Audio
-- Mono PCM input. Supported sample rates: 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz.
+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.1.0-beta.1] - 2026-06-08
+
+First 1.1 pre-release. Includes breaking changes — see below.
+
+### Added
+- Render quality tiers (`standard` / `high` / `ultra`), selectable at init via the `renderQuality` configuration option or at runtime via `setRenderQuality()`.
+- Render output resolution cap, to bound rendering cost on high-DPI displays.
+- `Configuration.region` is now part of the public API, so consumers can target non-default regions (e.g. `cn`).
+
+### Changed
+- Unified audio playback path with automatic recovery after a fallback.
+- Smoother RTC-mode speak→idle transition with bezier end interpolation.
+
+### Fixed
+- Fixed unfriendly avatar-load error messages that could expose internal request details.
+- Fixed `Configuration.region` being stripped from the published type declarations, which prevented TypeScript consumers from setting the region.
+
+### Breaking Changes
+- `DrivingServiceMode` values renamed from `sdk` / `host` to `direct` / `backend`.
+- Removed the `eyefocus` option (no longer supported in `CharacterSettings` or post-processing configuration).
+
+## [1.0.0] - 2026-05-17
+
+First stable release.
+
+- Real-time avatar rendering with WebGL and WebGPU backends.
+- Audio-driven SDK mode and host-driven mode for custom animation pipelines.
+- Public API: `AvatarSDK`, `AvatarView`, `AvatarController`, `AvatarManager`.
+- See [README.md](README.md) for installation and usage.

package/README.md

@@ -1,4 +1,4 @@
-# AvatarKit SDK
+# @spatius/avatarkit
 
 Real-time virtual avatar rendering SDK for Web, supporting audio-driven animation and high-quality 3D rendering.
 
@@ -55,7 +55,7 @@ We provide complete example code and best practices to help you quickly integrat
 
 **The demo repository includes:**
 - ✅ Complete integration examples
-- ✅ Usage examples for both SDK mode and Host mode  
+- ✅ Usage examples for both Direct mode and Backend mode  
 - ✅ Audio processing examples (PCM16, WAV, MP3, etc.)
 - ✅ Vite configuration examples
 - ✅ Next.js configuration examples
@@ -165,7 +165,7 @@ All environments require an **App ID** and **Session Token** for authentication.
 The App ID is used to identify your application. You can obtain your App ID by:
 
 1. **For Testing**: Use the default test App ID provided in demo repositories (paired with test Session Token, only works with publicly available test avatars like Rohan, Dr.Kellan, Priya, Josh, etc.)
-2. **For Production**: Visit the [Developer Platform](https://dash.spatialreal.ai) to create your own App and avatars. You will receive your own App ID after creating an App.
+2. **For Production**: Visit the [Developer Platform](https://app.spatius.ai) to create your own App and avatars. You will receive your own App ID after creating an App.
 
 ### Session Token
 
@@ -175,7 +175,7 @@ The Session Token is required for authentication and must be obtained from your
 - The Session Token must be valid and not expired
 - In production applications, you **must** manually inject a valid Session Token obtained from your SDK provider
 - The default Session Token provided in demo repositories is **only for demonstration purposes** and can only be used with test avatars
-- If you want to create your own avatars and test them, please visit the [Developer Platform](https://dash.spatialreal.ai) to create your own App and generate Session Tokens
+- If you want to create your own avatars and test them, please visit the [Developer Platform](https://app.spatius.ai) to create your own App and generate Session Tokens
 
 **How to Set Session Token:**
 
@@ -224,9 +224,9 @@ import {
 // 1. Initialize SDK
 
 const configuration: Configuration = {
-  drivingServiceMode: DrivingServiceMode.sdk, // Optional, 'sdk' is default
-  // - DrivingServiceMode.sdk: SDK mode - SDK handles network communication
-  // - DrivingServiceMode.host: Host mode - Host app provides audio and animation data
+  drivingServiceMode: DrivingServiceMode.direct, // Optional, `direct` is default
+  // - DrivingServiceMode.direct: Direct mode - SDK handles network communication
+  // - DrivingServiceMode.backend: Backend mode - Host app provides audio and animation data
   logLevel: LogLevel.off, // Optional, 'off' is default
   // - LogLevel.off: Disable all logs
   // - LogLevel.error: Only error logs
@@ -237,7 +237,6 @@ const configuration: Configuration = {
     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
 }
 
 await AvatarSDK.initialize('your-app-id', configuration)
@@ -255,8 +254,8 @@ 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 network communication
-// - DrivingServiceMode.host: Host mode - Host app provides audio and animation data
+// - DrivingServiceMode.direct: Direct mode - SDK handles network communication
+// - DrivingServiceMode.backend: Backend mode - Host app provides audio and animation data
 const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
 
@@ -267,7 +266,7 @@ button.addEventListener('click', async () => {
   // Initialize audio context - MUST be in user gesture context
   await avatarView.controller.initializeAudioContext()
   
-  // 5. Start real-time communication (SDK mode only)
+  // 5. Start real-time communication (Direct mode only)
   // Note: start() initiates the WebSocket connection asynchronously.
   // Wait for onConnectionState === 'connected' before calling send().
   await avatarView.controller.start()
@@ -279,7 +278,7 @@ button.addEventListener('click', async () => {
     }
   })
 
-  // 7. Send audio data (SDK mode, must be mono PCM16 format matching configured sample rate)
+  // 7. Send audio data (Direct mode, must be mono PCM16 format matching configured sample rate)
   // audioData: ArrayBuffer or Uint8Array containing PCM16 (S16LE) audio samples
   // ⚠️ Byte length MUST be even (2 bytes per sample). Odd-length data will cause server-side
   //    validation error and WebSocket disconnect.
@@ -296,9 +295,9 @@ button.addEventListener('click', async () => {
 
 ```typescript
 
-// 1-3. Same as SDK mode (initialize SDK, load avatar)
+// 1-3. Same as Direct mode (initialize SDK, load avatar)
 
-// 3. Create view with Host mode
+// 3. Create view with Backend mode
 const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
 
@@ -318,8 +317,8 @@ button.addEventListener('click', async () => {
 ### Complete Examples
 
 This SDK supports two usage modes:
-- SDK mode: Real-time audio input with automatic animation data reception
-- Host mode: Custom data sources with manual audio/animation data management
+- Direct mode: Real-time audio input with automatic animation data reception
+- Backend mode: Custom data sources with manual audio/animation data management
 
 ## 🏗️ Architecture Overview
 
@@ -335,14 +334,14 @@ This SDK supports two usage modes:
 The SDK supports two playback modes, configured in `AvatarSDK.initialize()`:
 
 #### 1. SDK Mode (Default)
-- Configured via `drivingServiceMode: DrivingServiceMode.sdk` in `AvatarSDK.initialize()`
+- Configured via `drivingServiceMode: DrivingServiceMode.direct` in `AvatarSDK.initialize()`
 - 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
 
 #### 2. Host Mode
-- Configured via `drivingServiceMode: DrivingServiceMode.host` in `AvatarSDK.initialize()`
+- Configured via `drivingServiceMode: DrivingServiceMode.backend` in `AvatarSDK.initialize()`
 - Host application manages its own network/data fetching
 - Host application provides both audio and animation data
 - SDK only handles synchronized playback
@@ -619,13 +618,13 @@ const newAvatar = await AvatarManager.shared.load('new-character-id')
 // 3. Create new AvatarView
 currentAvatarView = new AvatarView(newAvatar, container)
 
-// 4. Start connection if SDK mode
+// 4. Start connection if Direct mode
 await currentAvatarView.controller.start()
 ```
 
 ### AvatarController
 
-Audio/animation playback controller, manages synchronized playback of audio and animation. Automatically handles network communication in SDK mode.
+Audio/animation playback controller, manages synchronized playback of audio and animation. Automatically handles network communication in Direct mode.
 
 **Two Usage Patterns:**
 
@@ -690,7 +689,6 @@ button.addEventListener('click', async () => {
 - `yieldAudioData()` returns a conversationId (automatically generates if starting new session)
    - `yieldFramesData()` requires a valid conversationId parameter
    - Animation data with mismatched conversationId will be **discarded**
-   - Use `getCurrentConversationId()` to retrieve the current active conversationId
 
 #### Common Methods (Both Modes)
 
@@ -705,19 +703,12 @@ await avatarView.controller.resume()
 // Interrupt current playback (stops and clears data)
 avatarView.controller.interrupt()
 
-// Clear all data and resources
-avatarView.controller.clear()
-
-// Get current conversation ID (for Host mode)
-const conversationId = avatarView.controller.getCurrentConversationId()
-// Returns: Current conversationId for the active audio session, or null if no active session
-
 // Volume control (affects only avatar audio player, not system volume)
 avatarView.controller.setVolume(0.5)  // Set volume to 50% (0.0 to 1.0)
 const currentVolume = avatarView.controller.getVolume()  // Get current volume (0.0 to 1.0)
 
 // Set event callbacks
-avatarView.controller.onConnectionState = (state: ConnectionState) => {} // SDK mode only
+avatarView.controller.onConnectionState = (state: ConnectionState) => {} // Direct mode only
 avatarView.controller.onConversationState = (state: ConversationState) => {}
 avatarView.controller.onError = (error: AvatarError) => {} // Includes error.code for specific error type
 ```
@@ -740,9 +731,9 @@ avatarView.avatarTransform = { x: 0.5, y: 0, scale: 2.0 } // Right half, double
 ```
 
 **Important Notes:**
-- `start()` and `close()` are only available in SDK mode
-- `yieldAudioData()` and `yieldFramesData()` are only available in Host mode
-- `pause()`, `resume()`, `interrupt()`, `clear()`, `getCurrentConversationId()`, `setVolume()`, and `getVolume()` are available in both modes
+- `start()` and `close()` are only available in Direct mode
+- `yieldAudioData()` and `yieldFramesData()` are only available in Backend mode
+- `pause()`, `resume()`, `interrupt()`, `setVolume()`, and `getVolume()` are available in both modes
 - The playback mode is determined when creating `AvatarView` and cannot be changed
 
 ## 🔧 Configuration
@@ -751,10 +742,9 @@ avatarView.avatarTransform = { x: 0.5, y: 0, scale: 2.0 } // Right half, double
 
 ```typescript
 interface Configuration {
-  drivingServiceMode?: DrivingServiceMode  // Optional, default is 'sdk' (SDK mode)
+  drivingServiceMode?: DrivingServiceMode  // Optional, default is `direct` (Direct mode)
   logLevel?: LogLevel  // Optional, default is 'off' (no logs)
   audioFormat?: AudioFormat  // Optional, default is { channelCount: 1, sampleRate: 16000 }
-  characterApiBaseUrl?: string  // Optional, internal debug config, can be ignored
 }
 
 interface AudioFormat {
@@ -780,8 +770,8 @@ enum LogLevel {
 
 **Description:**
 - `drivingServiceMode`: Specifies the driving service mode
-  - `DrivingServiceMode.sdk` (default): SDK mode - SDK handles network communication automatically
-  - `DrivingServiceMode.host`: Host mode - Host application provides audio and animation data
+  - `DrivingServiceMode.direct` (default): Direct mode - SDK handles network communication automatically
+  - `DrivingServiceMode.backend`: Backend mode - Host application provides audio and animation data
 - `logLevel`: Controls the verbosity of SDK logs
   - `LogLevel.off` (default): Disable all logs
   - `LogLevel.error`: Only error logs
@@ -792,7 +782,6 @@ enum LogLevel {
   - `sampleRate`: Audio sample rate in Hz (default: 16000)
     - Supported values: 8000, 16000, 22050, 24000, 32000, 44100, 48000
     - The configured sample rate will be used for both audio recording and playback
-- `characterApiBaseUrl`: Internal debug config, can be ignored
 - `sessionToken`: **Required for authentication**. Set separately via `AvatarSDK.setSessionToken()`, not in Configuration. See [Authentication](#-authentication) section for details
 
 ### CameraConfig
@@ -896,7 +885,7 @@ avatarView.controller.onError = (error: AvatarError) => {
 | `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 |
+| `networkLayerNotAvailable` | Network layer not available | `send()` in backend mode |
 | `playbackStartFailed` | Failed to start playback | Internal error |
 | `playbackInitFailed` | Playback initialization failed | Internal error |
 | `audioOnlyInitFailed` | Audio-only playback init failed | Fallback mode error |
@@ -942,12 +931,12 @@ avatarView.dispose()
 
 **⚠️ Important Notes:**
 - `dispose()` automatically cleans up all resources, including:
-  - Network connections (SDK mode)
+  - Network connections (Direct 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 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 before disposing, you can call `avatarView.controller.close()` (Direct mode) first, but it's not required as `dispose()` handles this automatically
 
 ### Memory Optimization
 
@@ -973,4 +962,4 @@ Issues and Pull Requests are welcome!
 
 For questions, please contact:
 - Email: code@spatius.net
-- Documentation: https://docs.spatialreal.ai
+- Documentation: https://docs.spatius.ai

package/dist/{StreamingAudioPlayer-D-7zAYjb.js → StreamingAudioPlayer-DrHXn-YA.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-DrRoews_.js";
+import { A as APP_CONFIG, l as logger, e as errorToMessage, a as logEvent } from "./index-CVQn5uEB.js";
 class StreamingAudioPlayer {
   // Mark if AudioContext is being resumed, avoid concurrent resume requests
   constructor(options) {
@@ -87,8 +87,8 @@ class StreamingAudioPlayer {
       });
     } catch (error) {
       const message = errorToMessage(error);
-      logEvent("activeAudioSessionFailed", "warning", {
-        sessionId: this.sessionId,
+      logEvent("audio_session_init_failed", "warning", {
+        session_id: this.sessionId,
         reason: message
       });
       logger.error("Failed to initialize AudioContext:", message);
@@ -144,7 +144,7 @@ class StreamingAudioPlayer {
       } catch (err) {
         logger.errorWithError("[StreamingAudioPlayer] Failed to resume AudioContext:", err);
         logEvent("audio_context_resume_failed", "error", {
-          sessionId: this.sessionId,
+          session_id: this.sessionId,
           reason: err instanceof Error ? err.message : String(err)
         });
       } finally {
@@ -281,7 +281,7 @@ class StreamingAudioPlayer {
       const errorMessage = "Failed to create AudioBuffer from PCM data";
       logger.error(errorMessage);
       logEvent("audio_buffer_creation_failed", "error", {
-        sessionId: this.sessionId
+        session_id: this.sessionId
       });
       return;
     }
@@ -328,7 +328,7 @@ class StreamingAudioPlayer {
     } catch (err) {
       logger.errorWithError("Failed to schedule audio chunk:", err);
       logEvent("schedule_chunk_failed", "error", {
-        sessionId: this.sessionId,
+        session_id: this.sessionId,
         reason: err instanceof Error ? err.message : String(err)
       });
     }

package/dist/core/Avatar.d.ts

@@ -1,6 +1,7 @@
 import { CharacterMeta } from '../types';
 export declare class Avatar {
     readonly id: string;
+    get isFromCache(): boolean;
     private characterMeta;
     private resources;
     /** Local-only field: tracks whether cached model is "standard" or "compressed". */

package/dist/core/AvatarController.d.ts

@@ -1,5 +1,5 @@
 import { Avatar } from './Avatar';
-import { ConnectionState, AvatarError, DrivingServiceMode, ConversationState, PostProcessingConfig } from '../types';
+import { ConnectionState, AvatarError, DrivingServiceMode, ConversationState, AnimationType, PostProcessingConfig } from '../types';
 import { FrameRateInfo } from '../performance/FrameRateMonitor';
 export declare class AvatarController {
     private networkLayer?;
@@ -10,6 +10,8 @@ export declare class AvatarController {
     onConnectionState: ((state: ConnectionState) => void) | null;
     onConversationState: ((state: ConversationState) => void) | null;
     onError: ((error: AvatarError) => void) | null;
+    /** Callback for animation type changes (e.g., idle → mono in fallback mode). Aligned with iOS/Android AvatarController.onAnimationState. */
+    onAnimationState: ((type: AnimationType) => void) | null;
     private eventListeners;
     private readonly frameRateMonitor;
     /** Frame rate monitoring callback. Fires with aggregated metrics from a 2-second sliding window. */
@@ -20,10 +22,7 @@ export declare class AvatarController {
     set frameRateMonitorEnabled(value: boolean);
     private renderCallback?;
     private characterHandle;
-    private characterId;
     private postProcessingConfig;
-    private playbackLoopId;
-    private playbackLoopGeneration;
     private lastRenderedFrameIndex;
     private keyframesOffset;
     private readonly MAX_KEYFRAMES;
@@ -43,14 +42,13 @@ export declare class AvatarController {
         playbackMode?: DrivingServiceMode;
     });
     private handleVisibilityChange;
-    private shouldReportPlaybackStats;
-    private _getDeviceScoreProps;
     /**
-     * Get current conversation ID
-     * Returns the current conversation ID for the active audio session
-     * @returns Current conversation ID, or null if no active session
+     * Playback time of the current audio session, in seconds.
+     * Resets to 0 on each new playback round. Returns 0 when not playing.
      */
-    getCurrentConversationId(): string | null;
+    getAudioTime(): number;
+    private shouldReportPlaybackStats;
+    private _getDeviceScoreProps;
     /**
      * Initialize audio context (must be called in user gesture context)
      *
@@ -92,7 +90,7 @@ export declare class AvatarController {
      * Public API: accepts binary data array (protobuf encoded Message array)
      * @param keyframesDataArray - Animation keyframes binary data array (each element is a protobuf encoded Message) or empty array to trigger audio-only mode
      * @param conversationId - Conversation ID (required). If conversationId doesn't match current conversationId, keyframes will be discarded.
-     *                Use getCurrentConversationId() to get the current conversationId.
+     *                The conversationId is returned by yieldAudioData().
      * @returns `true` if the server has sent all animation data for this conversation (end signal received), `false` otherwise.
      */
     yieldFramesData(keyframesDataArray: (Uint8Array | ArrayBuffer)[], conversationId: string): boolean;
@@ -112,14 +110,9 @@ export declare class AvatarController {
      */
     interrupt(): void;
     /**
-     * Clear all data and resources
-     */
-    clear(): void;
-    /**
-     * Get point cloud count of the current avatar
-     * @returns Point cloud count, or null if avatar is not loaded
+     * The point count of current avatar, or null if avatar is not loaded.
      */
-    getPointCount(): number | null;
+    get pointCount(): number | null;
     /**
      * Set post-processing configuration
      * These parameters will be applied in real-time to animation parameters returned by the server
@@ -137,4 +130,5 @@ export declare class AvatarController {
      * @returns Current volume value (0.0 - 1.0)
      */
     getVolume(): number;
+    protected stopPlayback(): void;
 }

package/dist/core/AvatarSDK.d.ts

@@ -1,4 +1,4 @@
-import { Configuration } from '../types';
+import { Configuration, RenderQuality } from '../types';
 export declare class AvatarSDK {
     private static _initializationState;
     private static _initializingPromise;
@@ -7,6 +7,13 @@ export declare class AvatarSDK {
     private static _avatarCore;
     private static _cachedDeviceScore;
     private static _rendererBackend;
+    /** Render output resolution cap. Disabled by default; when enabled and the
+     *  canvas backing height (css × DPR) exceeds maxHeight, the canvas is sized
+     *  to maxHeight (aspect-preserving) and the browser scales it back up to
+     *  the CSS box. Training material is 1080p so heights above ~1080-1440
+     *  add no real visual information. */
+    static renderResolutionCapEnabled: boolean;
+    static renderResolutionMaxHeight: number;
     /**
      * Initialize SDK
      * @param appId Application ID to be included in both HTTP Headers and WebSocket Headers
@@ -25,9 +32,16 @@ export declare class AvatarSDK {
      * Optional interface for developers, SDK includes this in telemetry logs
      */
     static setUserId(userId: string): void;
-    static get isInitialized(): boolean;
     static get appId(): string | null;
     static get configuration(): Configuration | null;
+    /**
+     * Update the global render quality tier. Takes effect on the next rendered
+     * frame across all active AvatarView instances. Throws if SDK isn't initialized.
+     */
+    static setRenderQuality(quality: RenderQuality): void;
+    /** Toggle the render output resolution cap. Takes effect on the next layout
+     *  pass across all active AvatarView instances. */
+    static setRenderResolutionCap(enabled: boolean, maxHeight?: number): void;
     static get sessionToken(): string | null;
     static get userId(): string | null;
     static get version(): string;

package/dist/core/AvatarView.d.ts

@@ -9,26 +9,23 @@ export declare class AvatarView {
     private renderSystem;
     private isInitialized;
     private cameraConfig;
-    private renderingState;
-    private currentKeyframes;
-    private lastRenderedFrameIndex;
-    private lastRealtimeProtoFrame;
-    private idleAnimationLoopId;
-    private realtimeAnimationLoopId;
+    private renderLoopId;
     private resizeObserver;
     private onWindowResize;
+    private onVisibilityChange;
     private frameCount;
     private lastFpsUpdate;
     private currentFPS;
-    private transitionKeyframes;
-    private transitionStartTime;
-    private readonly startTransitionDurationMs;
-    private readonly endTransitionDurationMs;
+    private currentFrame;
     private cachedIdleFirstFrame;
-    private idleCurrentFrameIndex;
-    private currentPlayingFrame;
     private characterHandle;
     private characterId;
+    private transitionFrames;
+    private onTransitionFramesConsumed;
+    private isConversationActive;
+    private lastRenderedFrameIndex;
+    private animationHandleMap;
+    private activeAnimationState;
     private isPureRenderingMode;
     private _renderingEnabled;
     private avatarActiveTimer;
@@ -44,6 +41,42 @@ export declare class AvatarView {
      * Get controller (public interface)
      */
     get controller(): AvatarController;
+    /**
+     * Current native render surface size in pixels (canvas backing buffer
+     * size, post-DPR).
+     *
+     * Differs from the canvas CSS size (`offsetWidth / offsetHeight`): this
+     * reflects the actual pixel buffer the WebGPU renderer is targeting after
+     * the most recent resize has been applied.
+     *
+     * Returns `{ width: 0, height: 0 }` before the canvas has been initialized.
+     */
+    get renderSize(): {
+        width: number;
+        height: number;
+    };
+    private _exportBitmapResolve;
+    /**
+     * Exports the current rendering as a Blob (PNG).
+     * Returns null if the canvas is not initialized or not rendering.
+     * Aligned with iOS exportBitmap() / Android exportBitmap().
+     *
+     * The capture happens synchronously inside the render loop (after renderFrame)
+     * to work correctly with WebGL preserveDrawingBuffer:false.
+     */
+    exportBitmap(): Promise<Blob | null>;
+    /** @deprecated Use startRenderLoop() */
+    private startIdleAnimationLoop;
+    /**
+     * Render a specific idle frame by index for benchmark capture.
+     * Bypasses animation loop and _renderingEnabled check.
+     */
+    renderIdleFrameForBenchmark(frameIndex: number): Promise<void>;
+    /**
+     * Render a single frame from FlameParams for benchmark capture (transition / speaking).
+     * Bypasses animation loop and _renderingEnabled check.
+     */
+    renderFrameForBenchmark(flameParams: import('../wasm/avatarCoreAdapter').FlameParams): Promise<void>;
     /**
      * Cleanup view resources
      * Closes avatarController and cleans up all related resources
@@ -107,7 +140,17 @@ export declare class AvatarView {
      * @param options.useLinear - Use linear interpolation (default: true)
      * @returns Array of opaque keyframe data for sequential playback
      */
-    generateTransitionFromProtobuf(data: ArrayBuffer | Uint8Array, frameCount: number, options?: {
+    generateTransitionToFrame(data: ArrayBuffer | Uint8Array, frameCount: number, options?: {
+        useLinear?: boolean;
+    }): Promise<unknown[]>;
+    /**
+     * RTC mode: generate `frameCount` interpolated frames from the most recently
+     * rendered frame back to the idle loop start. Caller plays them at 25fps
+     * via `renderFrame`, then hands control back with
+     * `renderFrame(undefined, true)`. Used for speaking → idle and disconnect
+     * soft transitions.
+     */
+    generateTransitionToIdle(frameCount: number, options?: {
         useLinear?: boolean;
     }): Promise<unknown[]>;
     /**
@@ -115,6 +158,12 @@ export declare class AvatarView {
      * Called by renderFromProtobuf when streaming frames arrive during transition.
      */
     cancelFrameSequence(): void;
+    /** 计算 canvas backing-store 像素尺寸. 默认 css × dpr;
+     *  AvatarSDK.setRenderResolutionCap 启用且高度超过阈值时,
+     *  按比例缩到阈值, css 尺寸不变 (浏览器自动拉伸). */
+    private computeCappedBacking;
+    /** Registry hook: AvatarSDK.setRenderResolutionCap 调用时重算 backing size. */
+    applyResolutionCapFromSdk(): void;
     /**
      * Pause rendering loop
      *
@@ -167,4 +216,31 @@ export declare class AvatarView {
         y: number;
         scale: number;
     });
+    /**
+     * Get the approximate bounding rectangle of the avatar in canvas pixel coordinates.
+     * Projects idle first frame positions through current view/projection matrices and transform.
+     * No caching is performed — each call recomputes from scratch.
+     *
+     * **Important:** The result depends on the current canvas size and `avatarTransform`.
+     * You must call this method again after any of the following changes to get an up-to-date result:
+     * - Canvas / container size changes (e.g. window resize)
+     * - `avatarTransform` changes (offset or scale)
+     *
+     * **Performance note:** Each call iterates ~70k splat points. Avoid calling every frame;
+     * call on-demand (e.g. after init, on resize, after transform change).
+     *
+     * @returns Bounding rectangle { x, y, width, height } in CSS pixels (top-left origin), or null if not ready
+     *
+     * @example
+     * const rect = avatarView.getBoundingRect()
+     * if (rect) {
+     *   console.log(`Avatar at (${rect.x}, ${rect.y}), size ${rect.width}x${rect.height}`)
+     * }
+     */
+    getBoundingRect(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
 }

package/dist/core/avatarViewRegistry.d.ts

@@ -0,0 +1,9 @@
+import { AvatarView } from './AvatarView';
+declare class AvatarViewRegistry {
+    private entries;
+    register(view: AvatarView): void;
+    unregister(view: AvatarView): void;
+    applyResolutionCapToAll(): void;
+}
+export declare const avatarViewRegistry: AvatarViewRegistry;
+export {};