@spatialwalk/avatarkit 1.0.0-beta.88 → 1.0.0-beta.89

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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).
 
+## [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

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

package/dist/assets/cpu-benchmark-worker-C6iFEUSO.js

@@ -0,0 +1,36 @@
+(function() {
+  "use strict";
+  const MATRIX_SIZE = 128;
+  const A = new Float32Array(MATRIX_SIZE * MATRIX_SIZE);
+  const B = new Float32Array(MATRIX_SIZE * MATRIX_SIZE);
+  const C = new Float32Array(MATRIX_SIZE * MATRIX_SIZE);
+  for (let i = 0; i < A.length; i++) {
+    A[i] = i % 100 / 100;
+    B[i] = i * 7 % 100 / 100;
+  }
+  function benchmarkMatrixMultiply() {
+    const N = MATRIX_SIZE;
+    for (let i = 0; i < N; i++) {
+      for (let j = 0; j < N; j++) {
+        let sum = 0;
+        for (let k = 0; k < N; k++) {
+          sum += A[i * N + k] * B[k * N + j];
+        }
+        C[i * N + j] = sum;
+      }
+    }
+  }
+  self.onmessage = () => {
+    const warmupEnd = performance.now() + 1e3;
+    while (performance.now() < warmupEnd) {
+      benchmarkMatrixMultiply();
+    }
+    let iterations = 0;
+    const measureEnd = performance.now() + 1e3;
+    while (performance.now() < measureEnd) {
+      benchmarkMatrixMultiply();
+      iterations++;
+    }
+    self.postMessage({ cpuScore: iterations });
+  };
+})();

package/dist/core/Avatar.d.ts

@@ -3,6 +3,8 @@ export declare class Avatar {
     readonly id: string;
     private characterMeta;
     private resources;
+    /** Local-only field: tracks whether cached model is "standard" or "compressed". */
+    _cachedModelType: string;
     /**
      * Get character metadata
      * @returns Character metadata, including all configuration information (version, resource URLs, camera config, etc.)

package/dist/core/AvatarController.d.ts

@@ -1,15 +1,23 @@
 import { Avatar } from './Avatar';
 import { ConnectionState, DrivingServiceMode, ConversationState, PostProcessingConfig, KeyframeData } from '../types';
+import { FrameRateInfo } from '../performance/FrameRateMonitor';
 export declare class AvatarController {
     private networkLayer?;
     private readonly playbackMode;
     private isStartingPlayback;
     private currentConversationId;
     private reqEnd;
-    onConnectionState: ((state: ConnectionState, error?: Error) => void) | null;
+    onConnectionState: ((state: ConnectionState) => void) | null;
     onConversationState: ((state: ConversationState) => void) | null;
     onError: ((error: Error) => void) | null;
     private eventListeners;
+    private readonly frameRateMonitor;
+    /** Frame rate monitoring callback. Fires with aggregated metrics from a 2-second sliding window. */
+    get onFrameRateInfo(): ((info: FrameRateInfo) => void) | null;
+    set onFrameRateInfo(value: ((info: FrameRateInfo) => void) | null);
+    /** Whether frame rate monitoring is enabled. Default is false (zero overhead when disabled). */
+    get frameRateMonitorEnabled(): boolean;
+    set frameRateMonitorEnabled(value: boolean);
     private renderCallback?;
     private characterHandle;
     private characterId;
@@ -32,6 +40,9 @@ export declare class AvatarController {
     constructor(avatar: Avatar, options?: {
         playbackMode?: DrivingServiceMode;
     });
+    private handleVisibilityChange;
+    private shouldReportPlaybackStats;
+    private _getDeviceScoreProps;
     /**
      * Get current conversation ID
      * Returns the current conversation ID for the active audio session

package/dist/core/AvatarManager.d.ts

@@ -18,9 +18,10 @@ export declare class AvatarManager {
      * Load avatar
      * @param id Avatar ID
      * @param onProgress Progress callback
+     * @param useCompressedModel Use compressed model resource (~30% of original size, with minor quality degradation). Defaults to false.
      * @returns Promise<Avatar>
      */
-    load(id: string, onProgress?: (progress: LoadProgressInfo) => void): Promise<Avatar>;
+    load(id: string, onProgress?: (progress: LoadProgressInfo) => void, useCompressedModel?: boolean): Promise<Avatar>;
     /**
      * Cancel a pending or running download task
      * @param id Avatar ID to cancel

package/dist/core/AvatarSDK.d.ts

@@ -6,6 +6,8 @@ export declare class AvatarSDK {
     private static readonly _version;
     private static _avatarCore;
     private static _dynamicSdkConfig;
+    private static _cachedDeviceScore;
+    private static _rendererBackend;
     /**
      * Initialize SDK
      * @param appId Application ID to be included in both HTTP Headers and WebSocket Headers
@@ -34,4 +36,23 @@ export declare class AvatarSDK {
      * Cleanup resources
      */
     static cleanup(): void;
+    /**
+     * Device performance score (CPU + GPU).
+     * CPU: matrix multiply throughput in Web Worker (warmup 1s + measure 1s).
+     * GPU: WebGPU compute shader throughput (warmup 1s + measure 1s).
+     * Returns 0 for GPU if WebGPU is not available.
+     */
+    static deviceScore(): Promise<{
+        cpuScore: number;
+        gpuScore: number;
+    }>;
+    private static readonly CPU_SCORE_THRESHOLD;
+    private static readonly GPU_SCORE_THRESHOLD;
+    /**
+     * Check if the current device can run the avatar.
+     * Runs a ~2s benchmark, reports device info and scores to PostHog.
+     * Currently always returns true — thresholds will be calibrated from production data.
+     */
+    static isDeviceSupported(): Promise<boolean>;
+    private static _getGPURenderer;
 }