@spatius/avatarkit 0.5.0 → 1.0.0

package/CHANGELOG.md

@@ -1,22 +1,15 @@
 # Changelog
 
-## [0.5.0] - 2026-05-14
+All notable changes to this project will be documented in this file.
 
-Initial release.
+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).
 
-### 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.
+## [1.0.0] - 2026-05-17
 
-### 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`.
+First stable release.
 
-### Audio
-- Mono PCM input. Supported sample rates: 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz.
+- 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.
 
@@ -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:**
 
@@ -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)
@@ -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,13 +703,6 @@ 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)
@@ -742,7 +733,7 @@ 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
+- `pause()`, `resume()`, `interrupt()`, `setVolume()`, and `getVolume()` are available in both modes
 - The playback mode is determined when creating `AvatarView` and cannot be changed
 
 ## 🔧 Configuration
@@ -754,7 +745,6 @@ interface Configuration {
   drivingServiceMode?: DrivingServiceMode  // Optional, default is 'sdk' (SDK 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 {
@@ -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
@@ -947,7 +936,7 @@ avatarView.dispose()
   - 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()` (SDK 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-Cq5jTVny.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-zTpDp_Pv.js";
 class StreamingAudioPlayer {
   // Mark if AudioContext is being resumed, avoid concurrent resume requests
   constructor(options) {

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. */
@@ -22,8 +24,7 @@ export declare class AvatarController {
     private characterHandle;
     private characterId;
     private postProcessingConfig;
-    private playbackLoopId;
-    private playbackLoopGeneration;
+    private audioMonitorLoopId;
     private lastRenderedFrameIndex;
     private keyframesOffset;
     private readonly MAX_KEYFRAMES;
@@ -43,14 +44,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 +92,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 +112,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 +132,5 @@ export declare class AvatarController {
      * @returns Current volume value (0.0 - 1.0)
      */
     getVolume(): number;
+    protected stopPlayback(): void;
 }

package/dist/core/AvatarSDK.d.ts

@@ -25,7 +25,6 @@ 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;
     static get sessionToken(): string | null;

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 cachedIdleFirstFrame;
-    private idleCurrentFrameIndex;
     private currentPlayingFrame;
+    private cachedIdleFirstFrame;
     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,28 @@ export declare class AvatarView {
      * Get controller (public interface)
      */
     get controller(): AvatarController;
+    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
@@ -167,4 +186,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;
 }