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

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.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

package/README.md

@@ -16,6 +16,35 @@ Real-time virtual avatar rendering SDK for Web, supporting audio-driven animatio
 npm install @spatialwalk/avatarkit
 ```
 
+## 🚧 Release Gate (Hard Rule)
+
+Release must pass gates before publish. Do not publish by manual ad-hoc commands.
+
+Required gate checks:
+
+```bash
+pnpm typecheck
+pnpm test
+pnpm build
+./tools/check_perf_baseline_release_gate.sh
+```
+
+If iteration includes bugfixes, `docs/bugfix-history.md` must have completed rows (test mapping + red/green evidence).
+
+Hotfix bypass is allowed only for emergency and must be recorded:
+
+```bash
+HOTFIX_BYPASS=1 ./tools/check_perf_baseline_release_gate.sh
+```
+
+## 🧪 Benchmark Demo (Web SDK)
+
+Use the dedicated benchmark demo (independent from `vanilla/`) for perf/render baseline runs:
+
+```bash
+pnpm demo:benchmark
+```
+
 ## 🚀 Demo Repository
 
 <div align="center">

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

package/dist/core/AvatarController.d.ts

@@ -15,6 +15,7 @@ export declare class AvatarController {
     private characterId;
     private postProcessingConfig;
     private playbackLoopId;
+    private playbackLoopGeneration;
     private lastRenderedFrameIndex;
     private keyframesOffset;
     private readonly MAX_KEYFRAMES;

package/dist/core/AvatarSDK.d.ts

@@ -1,6 +1,7 @@
 import { Configuration } from '../types';
 export declare class AvatarSDK {
-    private static _isInitialized;
+    private static _initializationState;
+    private static _initializingPromise;
     private static _configuration;
     private static readonly _version;
     private static _avatarCore;
@@ -11,6 +12,7 @@ export declare class AvatarSDK {
      * @param configuration Configuration parameters
      */
     static initialize(appId: string, configuration: Configuration): Promise<void>;
+    private static _initializeInternal;
     /**
      * Set sessionToken
      * Developer Client -> Developer Server -> AvatarKit Server -> return sessionToken (max 1 hour validity)

package/dist/{index-Z9AXSJw3.js → index-Ow7xDTS3.js}

@@ -9491,7 +9491,7 @@ const _AnimationPlayer = class _AnimationPlayer {
     if (this.streamingPlayer) {
       return;
     }
-    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-pfCQ3Bn7.js");
+    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-D0H3vuGE.js");
     const { AvatarSDK: AvatarSDK2 } = await Promise.resolve().then(() => AvatarSDK$1);
     const audioFormat = AvatarSDK2.getAudioFormat();
     this.streamingPlayer = new StreamingAudioPlayer({
@@ -10959,17 +10959,36 @@ class AvatarSDK {
    * @param configuration Configuration parameters
    */
   static async initialize(appId, configuration) {
+    logEvent("sdk_init_start", "info", {
+      env: configuration.environment,
+      dsm: configuration.drivingServiceMode || DrivingServiceMode.sdk,
+      init_state: this._initializationState,
+      already_initialized: this._initializationState === "initialized"
+      /* Initialized */
+    });
+    if (!appId) {
+      throw new Error("Failed to initialize AvatarSDK: appId is required. Get your appId at https://docs.spatialreal.ai/");
+    }
+    if (this._initializationState === "initialized") {
+      logger.log(`[AvatarSDK] Re-initializing with new environment: ${configuration.environment}`);
+      idManager.setAppId(appId);
+      this._configuration = configuration;
+      return;
+    }
+    if (this._initializationState === "initializing") {
+      logger.log("[AvatarSDK] Initialization already in progress, waiting for existing initialization...");
+      if (this._initializingPromise) {
+        return this._initializingPromise;
+      }
+      return;
+    }
+    this._initializationState = "initializing";
+    this._initializingPromise = this._initializeInternal(appId, configuration);
+    return this._initializingPromise;
+  }
+  static async _initializeInternal(appId, configuration) {
     var _a;
     try {
-      if (!appId) {
-        throw new Error("Failed to initialize AvatarSDK: appId is required. Get your appId at https://docs.spatialreal.ai/");
-      }
-      if (this._isInitialized) {
-        logger.log(`[AvatarSDK] Re-initializing with new environment: ${configuration.environment}`);
-        idManager.setAppId(appId);
-        this._configuration = configuration;
-        return;
-      }
       logger.log(`[AvatarSDK] Initializing with appId: ${appId}, environment: ${configuration.environment}`);
       this._configuration = configuration;
       setLogLevel(configuration.logLevel ?? LogLevel.off);
@@ -10986,7 +11005,7 @@ class AvatarSDK {
       });
       await this.initializeWASMModule();
       await this.initializeTemplateResources();
-      this._isInitialized = true;
+      this._initializationState = "initialized";
       logEvent("sdk_initialized", "info", {
         env: configuration.environment,
         dsm: configuration.drivingServiceMode || DrivingServiceMode.sdk
@@ -11008,7 +11027,10 @@ class AvatarSDK {
       logEvent("sdk_startup", "error", {
         reason: errorMessage
       });
+      this._initializationState = "uninitialized";
       throw error;
+    } finally {
+      this._initializingPromise = null;
     }
   }
   /**
@@ -11059,6 +11081,9 @@ class AvatarSDK {
       throw new Error("AvatarCore not available");
     }
     logger.log("[AvatarSDK] Loading template resources...");
+    logEvent("template_init_start", "info", {
+      stage: "sdk_init"
+    });
     try {
       const { AvatarDownloader: AvatarDownloader2 } = await Promise.resolve().then(() => AvatarDownloader$1);
       const downloader = new AvatarDownloader2();
@@ -11097,7 +11122,7 @@ class AvatarSDK {
   }
   // 只读属性
   static get isInitialized() {
-    return this._isInitialized;
+    return this._initializationState === "initialized";
   }
   static get appId() {
     return idManager.getAppId();
@@ -11141,7 +11166,7 @@ class AvatarSDK {
    * Cleanup resources
    */
   static cleanup() {
-    if (!this._isInitialized) {
+    if (this._initializationState === "uninitialized") {
       return;
     }
     try {
@@ -11151,7 +11176,8 @@ class AvatarSDK {
       }
       this._configuration = null;
       this._dynamicSdkConfig = null;
-      this._isInitialized = false;
+      this._initializationState = "uninitialized";
+      this._initializingPromise = null;
       idManager.clear();
       clearSdkConfigCache();
       cleanupPostHog();
@@ -11218,9 +11244,10 @@ class AvatarSDK {
     }
   }
 }
-__publicField(AvatarSDK, "_isInitialized", false);
+__publicField(AvatarSDK, "_initializationState", "uninitialized");
+__publicField(AvatarSDK, "_initializingPromise", null);
 __publicField(AvatarSDK, "_configuration", null);
-__publicField(AvatarSDK, "_version", "1.0.0-beta.86");
+__publicField(AvatarSDK, "_version", "1.0.0-beta.88");
 __publicField(AvatarSDK, "_avatarCore", null);
 __publicField(AvatarSDK, "_dynamicSdkConfig", null);
 const AvatarSDK$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
@@ -11796,17 +11823,19 @@ class NetworkLayer {
   setupWebSocketListeners() {
     this.wsClient.removeAllListeners();
     this.wsClient.on("sessionConfirmed", (connectionId) => {
+      var _a, _b;
       if (connectionId) {
         logger.log(`[NetworkLayer] Session confirmed, connection_id: ${connectionId}, ready to send audio`);
       } else {
         logger.log("[NetworkLayer] Session confirmed, ready to send audio");
       }
+      if (!this.dataController.connected) {
+        this.isFallbackMode = false;
+        this.dataController.setConnected(true);
+        (_b = (_a = this.dataController).onConnectionState) == null ? void 0 : _b.call(_a, ConnectionState.connected);
+      }
     });
     this.wsClient.on("connected", () => {
-      var _a, _b;
-      this.isFallbackMode = false;
-      this.dataController.setConnected(true);
-      (_b = (_a = this.dataController).onConnectionState) == null ? void 0 : _b.call(_a, ConnectionState.connected);
     });
     this.wsClient.on("disconnected", () => {
       var _a, _b;
@@ -12114,6 +12143,8 @@ class AvatarController {
     __publicField(this, "postProcessingConfig", null);
     // ========== Playback Loop ==========
     __publicField(this, "playbackLoopId", null);
+    __publicField(this, "playbackLoopGeneration", 0);
+    // invalidates stale async frame computes across stop/resume
     __publicField(this, "lastRenderedFrameIndex", -1);
     __publicField(this, "keyframesOffset", 0);
     // Offset to track how many frames were removed from the beginning
@@ -12136,10 +12167,10 @@ class AvatarController {
       audioTimeStuckCount: 0,
       reported: false
     });
-    __publicField(this, "MAX_AUDIO_TIME_ZERO_COUNT", 60);
-    // 约 1 秒（60fps）
-    __publicField(this, "MAX_AUDIO_TIME_STUCK_COUNT", 60);
-    // 约 1 秒（60fps）
+    __publicField(this, "MAX_AUDIO_TIME_ZERO_COUNT", FLAME_FRAME_RATE);
+    // 约 1 秒（25fps）
+    __publicField(this, "MAX_AUDIO_TIME_STUCK_COUNT", FLAME_FRAME_RATE);
+    // 约 1 秒（25fps）
     __publicField(this, "AUDIO_TIME_STUCK_THRESHOLD", 1e-3);
     // 1ms，小于此值视为卡住
     // ========== Host Mode Latency Metrics ==========
@@ -13050,6 +13081,74 @@ class AvatarController {
     }
     return false;
   }
+  /**
+   * Reset playback stuck detection counters
+   * @internal
+   */
+  resetPlaybackStuckCheckState() {
+    this.playbackStuckCheckState.audioTimeZeroCount = 0;
+    this.playbackStuckCheckState.audioTimeStuckCount = 0;
+    this.playbackStuckCheckState.lastAudioTime = 0;
+    this.playbackStuckCheckState.reported = false;
+  }
+  /**
+   * Compute and render one animation frame by absolute frame index.
+   * Uses loop generation guard to drop stale async outputs after stop/pause/resume.
+   * @internal
+   */
+  async computeAndRenderFrame(frameIndex, loopGeneration) {
+    let arrayIndex = frameIndex - this.keyframesOffset;
+    if (arrayIndex < 0) {
+      arrayIndex = 0;
+    }
+    const isOutOfBounds = arrayIndex >= this.currentKeyframes.length;
+    if (isOutOfBounds) {
+      arrayIndex = this.currentKeyframes.length - 1;
+      const now = Date.now();
+      const stateChanged = isOutOfBounds !== this.lastOutOfBoundsState;
+      const timeSinceLastLog = now - this.lastSyncLogTime;
+      if (stateChanged || timeSinceLastLog >= 1e3) {
+        logger.warn(`[PlaybackLoop] Frame index out of bounds! frameIndex: ${frameIndex}, maxAvailable: ${this.currentKeyframes.length - 1 + this.keyframesOffset}, using last frame`);
+        this.lastSyncLogTime = now;
+        this.lastOutOfBoundsState = isOutOfBounds;
+      }
+    } else if (isOutOfBounds !== this.lastOutOfBoundsState) {
+      this.lastOutOfBoundsState = isOutOfBounds;
+    }
+    if (this.currentKeyframes.length > this.MAX_KEYFRAMES) {
+      const framesToKeep = this.KEYFRAMES_CLEANUP_THRESHOLD;
+      const framesToRemove = frameIndex - framesToKeep;
+      if (framesToRemove > 0 && framesToRemove < frameIndex) {
+        this.currentKeyframes.splice(0, framesToRemove);
+        this.keyframesOffset += framesToRemove;
+        arrayIndex = frameIndex - this.keyframesOffset;
+        if (arrayIndex < 0) arrayIndex = 0;
+        if (arrayIndex >= this.currentKeyframes.length) {
+          arrayIndex = this.currentKeyframes.length - 1;
+        }
+        logger.log(`[AvatarController] Cleaned up ${framesToRemove} old frames (kept ${this.currentKeyframes.length} frames, offset: ${this.keyframesOffset})`);
+      }
+    }
+    if (arrayIndex < 0 || arrayIndex >= this.currentKeyframes.length) {
+      return;
+    }
+    const currentFrame = this.currentKeyframes[arrayIndex];
+    let wasmParams = convertProtoFlameToWasmParams(currentFrame);
+    if (this.postProcessingConfig) {
+      wasmParams = this.applyPostProcessingToParams(wasmParams);
+    }
+    const avatarCore = AvatarSDK.getAvatarCore();
+    if (!avatarCore) {
+      return;
+    }
+    const splatData = await avatarCore.computeFrameFlatFromParams(wasmParams, this.characterHandle ?? void 0);
+    if (loopGeneration !== this.playbackLoopGeneration || !this.isPlaying || this.currentState === AvatarState.paused) {
+      return;
+    }
+    if (splatData && this.renderCallback) {
+      this.renderCallback(splatData, frameIndex);
+    }
+  }
   /**
    * Start playback loop
    * @internal
@@ -13059,92 +13158,72 @@ class AvatarController {
       return;
     }
     const fps = FLAME_FRAME_RATE;
-    const playLoop = async () => {
-      if (!this.isPlaying || this.currentState === AvatarState.paused || !this.animationPlayer) {
+    const frameIntervalMs = 1e3 / fps;
+    const loopGeneration = ++this.playbackLoopGeneration;
+    let computeInFlight = false;
+    let queuedFrameIndex = null;
+    let nextTickTime = performance.now();
+    const scheduleNextTick = () => {
+      if (loopGeneration !== this.playbackLoopGeneration || !this.isPlaying || this.currentState === AvatarState.paused || !this.animationPlayer) {
+        this.playbackLoopId = null;
+        return;
+      }
+      nextTickTime += frameIntervalMs;
+      const delay = Math.max(0, nextTickTime - performance.now());
+      this.playbackLoopId = window.setTimeout(tick, delay);
+    };
+    const tryDispatchFrame = (frameIndex) => {
+      if (frameIndex <= this.lastRenderedFrameIndex) {
+        return;
+      }
+      if (computeInFlight) {
+        if (queuedFrameIndex === null || frameIndex > queuedFrameIndex) {
+          queuedFrameIndex = frameIndex;
+        }
+        return;
+      }
+      this.lastRenderedFrameIndex = frameIndex;
+      computeInFlight = true;
+      void this.computeAndRenderFrame(frameIndex, loopGeneration).catch((error) => {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error("[AvatarController] Playback frame compute error:", errorMessage);
+      }).finally(() => {
+        computeInFlight = false;
+        if (loopGeneration !== this.playbackLoopGeneration || !this.isPlaying || this.currentState === AvatarState.paused) {
+          queuedFrameIndex = null;
+          return;
+        }
+        if (queuedFrameIndex !== null) {
+          const pending = queuedFrameIndex;
+          queuedFrameIndex = null;
+          tryDispatchFrame(pending);
+        }
+      });
+    };
+    const tick = () => {
+      if (!this.isPlaying || this.currentState === AvatarState.paused || !this.animationPlayer || loopGeneration !== this.playbackLoopGeneration) {
         this.playbackLoopId = null;
-        this.playbackStuckCheckState.audioTimeZeroCount = 0;
-        this.playbackStuckCheckState.audioTimeStuckCount = 0;
-        this.playbackStuckCheckState.lastAudioTime = 0;
-        this.playbackStuckCheckState.reported = false;
+        this.resetPlaybackStuckCheckState();
         return;
       }
       try {
         const audioTime = this.animationPlayer.getCurrentTime();
         this.checkPlaybackStuck(audioTime);
-        if (audioTime === 0) {
-          this.playbackLoopId = requestAnimationFrame(playLoop);
-          return;
-        }
         if (audioTime > 0 && Math.abs(audioTime - this.playbackStuckCheckState.lastAudioTime) >= this.AUDIO_TIME_STUCK_THRESHOLD) {
           this.playbackStuckCheckState.audioTimeZeroCount = 0;
           this.playbackStuckCheckState.audioTimeStuckCount = 0;
         }
-        let frameIndex = Math.floor(audioTime * fps);
-        if (frameIndex < 0) frameIndex = 0;
-        let arrayIndex = frameIndex - this.keyframesOffset;
-        if (arrayIndex < 0) {
-          arrayIndex = 0;
-        }
-        const isOutOfBounds = arrayIndex >= this.currentKeyframes.length;
-        if (isOutOfBounds) {
-          arrayIndex = this.currentKeyframes.length - 1;
-          const now = Date.now();
-          const stateChanged = isOutOfBounds !== this.lastOutOfBoundsState;
-          const timeSinceLastLog = now - this.lastSyncLogTime;
-          if (stateChanged || timeSinceLastLog >= 1e3) {
-            logger.warn(`[PlaybackLoop] Frame index out of bounds! audioTime: ${audioTime.toFixed(3)}s, frameIndex: ${frameIndex}, maxAvailable: ${this.currentKeyframes.length - 1 + this.keyframesOffset}, using last frame`);
-            this.lastSyncLogTime = now;
-            this.lastOutOfBoundsState = isOutOfBounds;
-          }
-        } else {
-          if (isOutOfBounds !== this.lastOutOfBoundsState) {
-            this.lastOutOfBoundsState = isOutOfBounds;
-          }
-        }
-        if (frameIndex === this.lastRenderedFrameIndex) {
-          this.playbackLoopId = requestAnimationFrame(playLoop);
-          return;
-        }
-        this.lastRenderedFrameIndex = frameIndex;
-        if (this.currentKeyframes.length > this.MAX_KEYFRAMES) {
-          const framesToKeep = this.KEYFRAMES_CLEANUP_THRESHOLD;
-          const framesToRemove = frameIndex - framesToKeep;
-          if (framesToRemove > 0 && framesToRemove < frameIndex) {
-            this.currentKeyframes.splice(0, framesToRemove);
-            this.keyframesOffset += framesToRemove;
-            arrayIndex = frameIndex - this.keyframesOffset;
-            if (arrayIndex < 0) arrayIndex = 0;
-            if (arrayIndex >= this.currentKeyframes.length) {
-              arrayIndex = this.currentKeyframes.length - 1;
-            }
-            logger.log(`[AvatarController] Cleaned up ${framesToRemove} old frames (kept ${this.currentKeyframes.length} frames, offset: ${this.keyframesOffset})`);
-          }
-        }
-        if (arrayIndex >= 0 && arrayIndex < this.currentKeyframes.length) {
-          const currentFrame = this.currentKeyframes[arrayIndex];
-          let wasmParams = convertProtoFlameToWasmParams(currentFrame);
-          if (this.postProcessingConfig) {
-            wasmParams = this.applyPostProcessingToParams(wasmParams);
-          }
-          const avatarCore = AvatarSDK.getAvatarCore();
-          if (avatarCore) {
-            const splatData = await avatarCore.computeFrameFlatFromParams(wasmParams, this.characterHandle ?? void 0);
-            if (splatData && this.renderCallback) {
-              this.renderCallback(splatData, frameIndex);
-            }
-          }
+        if (audioTime > 0) {
+          const frameIndex = Math.max(0, Math.floor(audioTime * fps + 1e-6));
+          tryDispatchFrame(frameIndex);
         }
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         logger.error("[AvatarController] Playback loop error:", errorMessage);
       }
-      if (this.isPlaying) {
-        this.playbackLoopId = requestAnimationFrame(playLoop);
-      } else {
-        this.playbackLoopId = null;
-      }
+      scheduleNextTick();
     };
-    this.playbackLoopId = requestAnimationFrame(playLoop);
+    this.playbackLoopId = window.setTimeout(tick, 0);
   }
   /**
    * Stop playback loop
@@ -13152,9 +13231,11 @@ class AvatarController {
    */
   stopPlaybackLoop() {
     if (this.playbackLoopId) {
+      clearTimeout(this.playbackLoopId);
       cancelAnimationFrame(this.playbackLoopId);
       this.playbackLoopId = null;
     }
+    this.playbackLoopGeneration++;
   }
   // ========== Fallback Mode ==========
   /**
@@ -15784,6 +15865,18 @@ class RenderSystem {
     // 总渲染耗时
     __publicField(this, "sortTime", 0);
     // 排序耗时
+    __publicField(this, "reorderTime", 0);
+    // 重排耗时（WebGL）
+    __publicField(this, "renderSubmitTime", 0);
+    // CPU 提交耗时（load + render 调用）
+    __publicField(this, "frameSerial", 0);
+    // 实际渲染帧序号（每次 renderFrame 成功执行后 +1）
+    __publicField(this, "frameEndTimeMs", 0);
+    // 实际渲染结束时间戳（performance.now）
+    __publicField(this, "presentFrameSerial", 0);
+    // 展示帧序号（每次实际提交 draw 后 +1）
+    __publicField(this, "presentFrameEndTimeMs", 0);
+    // 展示帧完成时间戳（performance.now）
     // Transform for render texture blit
     __publicField(this, "offsetX", 0);
     __publicField(this, "offsetY", 0);
@@ -15858,10 +15951,14 @@ class RenderSystem {
     );
     const sortTime = performance.now() - startSort;
     this.sortTime = sortTime;
+    const startSubmit = performance.now();
     if (this.backend === "webgpu") {
+      this.reorderTime = 0;
       this.renderer.loadSplatsFromPackedData(this.originalPackedData, pointCount, sortOrder);
     } else {
+      const startReorder = performance.now();
       const reorderedData = reorderPackedData(this.originalPackedData, sortOrder);
+      this.reorderTime = performance.now() - startReorder;
       this.renderer.loadSplatsFromPackedData(reorderedData, pointCount);
     }
     const startRender = performance.now();
@@ -15874,6 +15971,28 @@ class RenderSystem {
     );
     const renderTime = performance.now() - startRender;
     this.renderTime = renderTime;
+    this.renderSubmitTime = performance.now() - startSubmit;
+    this.frameEndTimeMs = performance.now();
+    this.frameSerial += 1;
+    this.presentFrameEndTimeMs = this.frameEndTimeMs;
+    this.presentFrameSerial += 1;
+  }
+  /**
+   * 仅提交展示（复用最新上传的 GPU 数据，不做排序/重排）
+   */
+  presentFrameOnly() {
+    if (!this.renderer || !this.originalPackedData) {
+      return;
+    }
+    this.updateCameraMatrices();
+    this.renderer.render(
+      this.viewMatrix,
+      this.projectionMatrix,
+      [this.canvas.width, this.canvas.height],
+      this.offsetX !== 0 || this.offsetY !== 0 || this.scale !== 1 ? { x: this.offsetX, y: this.offsetY, scale: this.scale } : void 0
+    );
+    this.presentFrameEndTimeMs = performance.now();
+    this.presentFrameSerial += 1;
   }
   /**
    * Set transform for render texture blit
@@ -16636,7 +16755,7 @@ class AvatarView {
     }
   }
   /**
-   * Update FPS statistics (called in requestAnimationFrame callback)
+   * Update FPS statistics (called only when a frame is actually rendered)
    * @internal
    */
   updateFPS() {
@@ -16679,7 +16798,6 @@ class AvatarView {
         if (!this.renderSystem) {
           return;
         }
-        this.updateFPS();
         if (this.renderingState !== "idle") {
           this.idleAnimationLoopId = requestAnimationFrame(renderFrame);
           return;
@@ -16738,11 +16856,17 @@ class AvatarView {
     const renderFrame = async (currentTime) => {
       try {
         const state = this.renderingState;
-        this.updateFPS();
         if (!this.renderSystem || state === "idle") {
           this.realtimeAnimationLoopId = null;
           return;
         }
+        if (state === "speaking") {
+          if (this._renderingEnabled && !this.isPureRenderingMode) {
+            this.renderSystem.presentFrameOnly();
+          }
+          this.realtimeAnimationLoopId = requestAnimationFrame(renderFrame);
+          return;
+        }
         const elapsed = currentTime - lastTime;
         if (elapsed < frameInterval) {
           this.realtimeAnimationLoopId = requestAnimationFrame(renderFrame);
@@ -16814,10 +16938,6 @@ class AvatarView {
           this.realtimeAnimationLoopId = requestAnimationFrame(renderFrame);
           return;
         }
-        if (state === "speaking") {
-          this.realtimeAnimationLoopId = requestAnimationFrame(renderFrame);
-          return;
-        }
       } catch (error) {
         logger.error("[AvatarView] Realtime animation loop error:", error instanceof Error ? error.message : String(error));
         this.stopRealtimeAnimationLoop();
@@ -16868,6 +16988,7 @@ class AvatarView {
     if (!this.renderSystem || !this._renderingEnabled) {
       return;
     }
+    this.updateFPS();
     this.renderSystem.loadSplatsFromPackedData(splatData);
     this.renderSystem.renderFrame();
   }
@@ -17406,6 +17527,12 @@ class AvatarView {
     return {
       renderTime: this.renderSystem.renderTime,
       sortTime: this.renderSystem.sortTime,
+      reorderTime: this.renderSystem.reorderTime,
+      renderSubmitTime: this.renderSystem.renderSubmitTime,
+      frameSerial: this.renderSystem.frameSerial,
+      frameEndTimeMs: this.renderSystem.frameEndTimeMs,
+      presentFrameSerial: this.renderSystem.presentFrameSerial,
+      presentFrameEndTimeMs: this.renderSystem.presentFrameEndTimeMs,
       backend: this.renderSystem.getBackend(),
       fps: this.currentFPS
       // pointCount 可后续通过 AvatarCoreAdapter 添加公开方法获取

package/dist/index.js

@@ -1,4 +1,4 @@
-import { b, c, m, f, d, j, g, C, i, D, E, k, h, L, R, n } from "./index-Z9AXSJw3.js";
+import { b, c, m, f, d, j, g, C, i, D, E, k, h, L, R, n } from "./index-Ow7xDTS3.js";
 export {
   b as Avatar,
   c as AvatarController,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spatialwalk/avatarkit",
   "type": "module",
-  "version": "1.0.0-beta.86",
+  "version": "1.0.0-beta.88",
   "packageManager": "pnpm@10.18.2",
   "description": "AvatarKit SDK - 3D Gaussian Splatting Avatar Rendering SDK",
   "author": "AvatarKit Team",
@@ -49,6 +49,7 @@
     "build:vite-plugin": "tsc vite.ts --outDir . --module esnext --target es2020 --moduleResolution bundler --esModuleInterop --skipLibCheck --declaration --declarationMap",
     "build:next-plugin": "tsc next.ts --outDir . --module esnext --target es2020 --moduleResolution bundler --esModuleInterop --skipLibCheck --declaration --declarationMap",
     "dev": "vite build --mode library --watch",
+    "demo:benchmark": "vite --config benchmark-demo/vite.config.mjs",
     "clean": "rm -rf dist",
     "typecheck": "tsc --noEmit",
     "test": "cd tests && pnpm test",
@@ -62,8 +63,12 @@
     "next": ">=13.0.0"
   },
   "peerDependenciesMeta": {
-    "vite": { "optional": true },
-    "next": { "optional": true }
+    "vite": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@bufbuild/protobuf": "^2.10.0",

package/dist/marble-test/src/billboard.d.ts

@@ -1,22 +0,0 @@
-/**
- * Billboard transform for avatar splats.
- * Uses CYLINDRICAL billboard (Y-axis only rotation) so the avatar
- * stays upright regardless of camera pitch, only rotating left/right.
- *
- * Packed format per splat: 13 floats = [pos3, color4, cov6]
- * Covariance layout: [xx, xy, xz, yy, yz, zz]
- */
-/**
- * Apply billboard transform to avatar splat data.
- *
- * - Rotates each splat position by R, then translates to avatarWorldPos
- * - Rotates covariance: C' = R * C * R^T
- * - Color (4 floats) is copied unchanged
- *
- * @param avatarSplats  Source packed Float32Array from SDK (13 floats/splat)
- * @param avatarWorldPos  Where to place the avatar in the scene
- * @param cameraPos  Current camera position (avatar faces this)
- * @param scale  Optional uniform scale for the avatar (default 1.0)
- * @returns New Float32Array with transformed splats
- */
-export declare function applyBillboardTransform(avatarSplats: Float32Array, avatarWorldPos: [number, number, number], cameraPos: [number, number, number], scale?: number): Float32Array;

package/dist/marble-test/src/main.d.ts

@@ -1,6 +0,0 @@
-/**
- * Marble SPZ Viewer + Avatar Compositing
- * Renders a marble (WorldLabs) 3DGS scene with an SDK avatar composited in.
- * Avatar always faces the camera (billboard effect).
- */
-export {};

package/dist/marble-test/src/spzLoader.d.ts

@@ -1,18 +0,0 @@
-/**
- * SPZ (Splat Zip) decoder → packed format [pos3, color4, cov6] × N
- *
- * SPZ format (Niantic Labs):
- * - gzip-compressed stream
- * - 16-byte header + column-based attribute data
- *
- * Reference: https://github.com/nianticlabs/spz
- */
-/**
- * Load and decode an SPZ file into packed format [pos3, color4, cov6] × N
- */
-export declare function loadSpz(buffer: ArrayBuffer, onProgress?: (msg: string) => void): Promise<{
-    packedData: Float32Array;
-    pointCount: number;
-    center: [number, number, number];
-    extent: number;
-}>;

package/dist/marble-test/vite.config.d.ts

@@ -1,2 +0,0 @@
-declare const _default: any;
-export default _default;