@spatius/avatarkit 1.3.0 → 1.3.1-beta.2

package/CHANGELOG.md

@@ -5,6 +5,11 @@ 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.3.1-beta.1] - 2026-07-16
+
+### Changed
+- The `region` configuration now defaults to automatic selection: when left unset, the SDK picks the closest serving region at initialization. Passing an explicit `region` continues to force that region, unchanged. If automatic selection can't be reached, the SDK falls back to a default region and continues initializing.
+
 ## [1.3.0] - 2026-07-04
 
 ### Added

package/dist/{StreamingAudioPlayer-DmOtqI_a.js → StreamingAudioPlayer-2bLnaLam.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-BDFs1WRg.js";
+import { A as APP_CONFIG, l as logger, e as errorToMessage, a as logEvent } from "./index-CPolDcOo.js";
 class StreamingAudioPlayer {
   // Mark if AudioContext is being resumed, avoid concurrent resume requests
   constructor(options) {
@@ -46,6 +46,8 @@ class StreamingAudioPlayer {
     // Default volume 1.0 (0.0 - 1.0)
     // Event callbacks
     __publicField(this, "onEndedCallback");
+    // 音频缓冲卡顿（缓冲耗尽自动暂停 / 有数据自动恢复）通知：true=进入卡顿，false=恢复。
+    __publicField(this, "onAudioStallCallback");
     // AudioContext state management
     __publicField(this, "stateChangeHandler");
     __publicField(this, "isResuming", false);
@@ -156,6 +158,7 @@ class StreamingAudioPlayer {
    * Add audio chunk (16-bit PCM)
    */
   addChunk(pcmData, isLast = false) {
+    var _a;
     if (!this.audioContext) {
       logger.error("AudioContext not initialized");
       return;
@@ -176,6 +179,7 @@ class StreamingAudioPlayer {
     if (this.autoContinue && this.isPaused) {
       this.log("[StreamingAudioPlayer] autoContinue=true, auto-resuming playback");
       this.autoContinue = false;
+      (_a = this.onAudioStallCallback) == null ? void 0 : _a.call(this, false);
       this.resume().catch((err) => {
         logger.error("Failed to auto-resume playback:", err);
       });
@@ -229,13 +233,13 @@ class StreamingAudioPlayer {
       this.log("[StreamingAudioPlayer] Cannot start playback: Already playing");
       return;
     }
-    await this.ensureAudioContextRunning();
     this.isPlaying = true;
     this.sessionStartTime = this.audioContext.currentTime;
     this.scheduledTime = this.sessionStartTime;
     this.lastScheduledChunkEndTime = 0;
     this.scheduledChunkInfo = [];
     this.autoContinue = false;
+    await this.ensureAudioContextRunning();
     this.log("[StreamingAudioPlayer] Starting playback", {
       sessionStartTime: this.sessionStartTime,
       bufferedChunks: this.audioChunks.length,
@@ -304,18 +308,17 @@ class StreamingAudioPlayer {
       });
       this.activeSources.add(source);
       source.onended = () => {
+        var _a;
         this.activeSources.delete(source);
         if (this.activeSources.size === 0) {
           const lastChunk = this.audioChunks[this.scheduledChunks - 1];
-          if (lastChunk && !lastChunk.isLast) {
+          const sessionEnded = !!(lastChunk == null ? void 0 : lastChunk.isLast);
+          if (!sessionEnded) {
             this.log("All audio chunks ended but end=false, pausing and setting autoContinue");
-            logEvent("audio_buffer_stall", "warning", {
-              scheduled_chunks: this.scheduledChunks,
-              audio_time: this.getCurrentTime()
-            });
+            (_a = this.onAudioStallCallback) == null ? void 0 : _a.call(this, true);
             this.autoContinue = true;
             this.pause();
-          } else if (isLast) {
+          } else {
             this.log("Last audio chunk ended, marking playback as ended");
             this.markEnded();
           }
@@ -557,6 +560,12 @@ class StreamingAudioPlayer {
   onEnded(callback) {
     this.onEndedCallback = callback;
   }
+  /**
+   * 设置音频缓冲卡顿回调：缓冲耗尽自动暂停时 stalled=true，有数据自动恢复时 stalled=false。
+   */
+  onAudioStall(callback) {
+    this.onAudioStallCallback = callback;
+  }
   /**
    * Check if playing
    */

package/dist/core/AvatarController.d.ts

@@ -46,6 +46,11 @@ export declare class AvatarController {
     private isFallbackMode;
     private frameStarvationEvents;
     private isFrameStarved;
+    private audioStallEvents;
+    private isAudioBufferStalled;
+    private playbackEndReason;
+    private receivedAudioBytes;
+    private receivedAnimationFrames;
     /**
      * Whether this round's final animation batch (ServerResponseAnimation.end) has arrived.
      * Frame starvation is only possible BEFORE this — once all frames are in, any remaining

package/dist/{index-BDFs1WRg.js → index-CPolDcOo.js}

@@ -4189,6 +4189,7 @@ const RENDER_QUALITY_PARAMS = {
   ]: { renderScale: 1, splatRadius: 3 }
 };
 const DEFAULT_REGION = "us-west";
+const DEFAULT_REGION_REQUEST = "auto";
 var LoadProgress = /* @__PURE__ */ ((LoadProgress2) => {
   LoadProgress2["downloading"] = "downloading";
   LoadProgress2["completed"] = "completed";
@@ -11586,11 +11587,287 @@ class EventStore {
   }
 }
 const eventStore = new EventStore();
+const BOOTSTRAP_URL = "https://global.spatialwalk.top/bootstrap";
+async function fetchBootstrap(opts, signal, onResponse) {
+  const res = await fetch(BOOTSTRAP_URL, {
+    method: "POST",
+    body: JSON.stringify({
+      app_id: opts.appId,
+      sdk_version: opts.sdkVersion,
+      region: opts.region ?? "auto",
+      platform: opts.platform ?? "web"
+    }),
+    cache: "no-store",
+    signal
+  });
+  onResponse == null ? void 0 : onResponse();
+  if (!res.ok) {
+    throw new Error(`bootstrap HTTP ${res.status}`);
+  }
+  return await res.json();
+}
+const PROBE_TIMEOUT_MS = 5e3;
+const SAMPLE_COUNT = 3;
+const RECALIBRATE_INTERVAL_MS = 20 * 60 * 1e3;
+class ClockSync {
+  constructor() {
+    __publicField(this, "localBase", Date.now());
+    __publicField(this, "serverBase", null);
+    __publicField(this, "monoAtCalibrate", performance.now());
+    /** 首次校准是否已落定（落定前埋点应挂队列） */
+    __publicField(this, "calibrated", false);
+    __publicField(this, "appId", "");
+    __publicField(this, "sdkVersion", "");
+    __publicField(this, "platform", "web");
+    __publicField(this, "timer", null);
+    __publicField(this, "visibilityHandler", null);
+    __publicField(this, "syncing", false);
+    /** 首次校准落定后触发的回调（供上报层 flush 挂起队列） */
+    __publicField(this, "readyCallbacks", []);
+  }
+  /** 首次校准是否已完成（供上报闸门判断） */
+  isReady() {
+    return this.calibrated;
+  }
+  /**
+   * 注册"首次校准落定"回调（成功或失败都算落定）。
+   * 若已落定则立即同步触发一次。
+   */
+  onReady(cb) {
+    if (this.calibrated) {
+      cb();
+      return;
+    }
+    this.readyCallbacks.push(cb);
+  }
+  fireReady() {
+    const cbs = this.readyCallbacks;
+    this.readyCallbacks = [];
+    for (const cb of cbs) {
+      try {
+        cb();
+      } catch {
+      }
+    }
+  }
+  /** 本地时间戳：本地基准 + 单调流逝。一定有值。 */
+  localNow() {
+    return this.localAt(performance.now());
+  }
+  /** 后台时间戳：后台基准 + 单调流逝。未校准到后台时返回 null（上报留空）。 */
+  serverNow() {
+    return this.serverAt(performance.now());
+  }
+  /**
+   * 仅供单测：直接设定基准，绕过真实网络校准。
+   * @internal
+   */
+  __setBaselineForTest(opts) {
+    this.localBase = opts.localBase;
+    this.serverBase = opts.serverBase;
+    this.monoAtCalibrate = opts.monoAtCalibrate;
+    this.calibrated = opts.calibrated ?? true;
+  }
+  /** 用"指定单调读数"算本地时间戳（供入队事件按入队时刻还原）。取整到毫秒。 */
+  localAt(mono) {
+    return Math.round(this.localBase + (mono - this.monoAtCalibrate));
+  }
+  /** 用"指定单调读数"算后台时间戳；未校准到后台时返回 null。取整到毫秒。 */
+  serverAt(mono) {
+    if (this.serverBase === null) return null;
+    return Math.round(this.serverBase + (mono - this.monoAtCalibrate));
+  }
+  /**
+   * 用时间戳做逻辑（端到端延迟 tap_N/anim_N 等）时用：优先后台时间戳，
+   * 拿不到后台才退本地，保证与后台时刻同一时间线对齐。
+   */
+  timelineNow() {
+    return this.serverNow() ?? this.localNow();
+  }
+  /**
+   * 把"采集时刻的单调读数"换算成时间线时刻（优先后台、退本地）。
+   * 供标记解析用——采集时若校准未完成，先记单调读数，上报时再用最新基准换算。
+   * @param mono 采集那一刻的 performance.now()
+   */
+  resolveMono(mono) {
+    const drift = mono - this.monoAtCalibrate;
+    const base = this.serverBase ?? this.localBase;
+    return Math.round(base + drift);
+  }
+  /**
+   * 启动：立即校准一次，并注册定时 + 页面可见性重校准。
+   * 幂等；fire-and-forget，不阻塞初始化。
+   * @internal
+   */
+  start(opts) {
+    this.appId = opts.appId;
+    this.sdkVersion = opts.sdkVersion;
+    void this.calibrate();
+    if (this.timer === null) {
+      this.timer = setInterval(() => void this.calibrate(), RECALIBRATE_INTERVAL_MS);
+    }
+    if (this.visibilityHandler === null && typeof document !== "undefined") {
+      this.visibilityHandler = () => {
+        if (document.visibilityState === "visible") {
+          void this.calibrate();
+        }
+      };
+      document.addEventListener("visibilitychange", this.visibilityHandler);
+    }
+  }
+  /**
+   * 校准一次：多采样取最小 RTT 的样本，同时刷新本地/后台基准与单调零点。
+   * - 拿到后台：serverBase 更新为估算值。
+   * - 拿不到后台：serverBase 置空（后台时间戳留空），localBase 照常更新为当前墙钟。
+   * 已校准过后若本次全失败：保留旧基准、跳过（不把好基准换成更差的）。
+   * @internal
+   */
+  async calibrate() {
+    if (this.syncing) return;
+    this.syncing = true;
+    try {
+      const samples = [];
+      for (let i2 = 0; i2 < SAMPLE_COUNT; i2++) {
+        const s2 = await this.probe();
+        if (s2) samples.push(s2);
+      }
+      if (samples.length > 0) {
+        const best = samples.reduce((a2, b2) => b2.rttNet < a2.rttNet ? b2 : a2);
+        const firstCalibration = !this.calibrated;
+        this.serverBase = best.serverBase;
+        this.localBase = best.localBase;
+        this.monoAtCalibrate = best.monoAtCalibrate;
+        this.calibrated = true;
+        if (firstCalibration) this.fireReady();
+        logMetric("time_calibrated", "info", {
+          has_server: true,
+          rtt_ms: Math.round(best.rttNet)
+        });
+        return;
+      }
+      if (this.calibrated) {
+        logger.log("[ClockSync] recalibrate got no server time, keeping previous baseline");
+        return;
+      }
+      this.localBase = Date.now();
+      this.monoAtCalibrate = performance.now();
+      this.serverBase = null;
+      this.calibrated = true;
+      this.fireReady();
+      logMetric("time_calibrated", "info", { has_server: false });
+    } finally {
+      this.syncing = false;
+    }
+  }
+  /** 单次采样：请求 bootstrap，返回一组 (rttNet, serverBase, monoAtCalibrate, localBase)；失败返回 null。 */
+  async probe() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+    try {
+      let t1 = 0;
+      let localAtT1 = 0;
+      const t0 = performance.now();
+      const body = await fetchBootstrap(
+        {
+          appId: this.appId,
+          sdkVersion: this.sdkVersion,
+          region: "auto",
+          platform: this.platform
+        },
+        controller.signal,
+        () => {
+          t1 = performance.now();
+          localAtT1 = Date.now();
+        }
+      );
+      const ts2 = body == null ? void 0 : body.time_sync;
+      if (!ts2 || typeof ts2.server_receive_ms !== "number" || typeof ts2.server_send_ms !== "number") {
+        return null;
+      }
+      const rttNet = t1 - t0 - (ts2.server_send_ms - ts2.server_receive_ms);
+      const serverBase = ts2.server_send_ms + rttNet / 2;
+      return {
+        rttNet: Math.max(0, rttNet),
+        serverBase,
+        monoAtCalibrate: t1,
+        localBase: localAtT1
+      };
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /** 清理定时器与监听器。 */
+  cleanup() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.visibilityHandler !== null && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.visibilityHandler);
+      this.visibilityHandler = null;
+    }
+  }
+}
+const clockSync = new ClockSync();
+const FILTERED_HOSTNAMES = ["localhost", "127.0.0.1", "0.0.0.0"];
+function shouldFilterHostname() {
+  if (typeof window === "undefined") {
+    return false;
+  }
+  const hostname = window.location.hostname;
+  return FILTERED_HOSTNAMES.includes(hostname);
+}
+const MARK_KEY = "__mark";
+function monoTimestamp() {
+  return { [MARK_KEY]: "mono", value: performance.now() };
+}
+function isMark(v2) {
+  return typeof v2 === "object" && v2 !== null && MARK_KEY in v2;
+}
+function resolveMark(mark) {
+  switch (mark[MARK_KEY]) {
+    case "mono":
+      return clockSync.resolveMono(mark.value);
+  }
+}
+function resolveMarks(contents) {
+  return resolveValue(contents);
+}
+function resolveValue(value) {
+  if (isMark(value)) return resolveMark(value);
+  if (Array.isArray(value)) {
+    let out = null;
+    for (let i2 = 0; i2 < value.length; i2++) {
+      const resolved = resolveValue(value[i2]);
+      if (resolved !== value[i2]) {
+        if (!out) out = [...value];
+        out[i2] = resolved;
+      }
+    }
+    return out ?? value;
+  }
+  if (typeof value === "object" && value !== null) {
+    const obj = value;
+    let out = null;
+    for (const [k2, v2] of Object.entries(obj)) {
+      const resolved = resolveValue(v2);
+      if (resolved !== v2) {
+        if (!out) out = { ...obj };
+        out[k2] = resolved;
+      }
+    }
+    return out ?? value;
+  }
+  return value;
+}
 const OTEL_LOGGER_NAME = "spatius-avatarkit";
 let sdkVersion$1 = "1.0.0";
 let isInitialized$1 = false;
 let loggerProvider = null;
 const eventQueue$1 = [];
+const preCalibrationQueue = [];
 function buildBasicAuthHeader() {
   const credentials = `${OTEL_USERNAME}:${OTEL_PASSWORD}`;
   return `Basic ${btoa(credentials)}`;
@@ -11644,6 +11921,7 @@ function initializeOtel(version, resourceAttrs) {
     isInitialized$1 = true;
     logger.log(`[OTel] Initialized successfully - endpoint: ${OTEL_LOGS_ENDPOINT}, stream: ${OTEL_STREAM_NAME}`);
     flushEventQueue$1();
+    clockSync.onReady(() => flushPreCalibrationQueue());
     replayPersistedEvents().catch(() => {
     });
   } catch (error) {
@@ -11704,7 +11982,27 @@ function flushEventQueue$1() {
   eventQueue$1.length = 0;
 }
 function trackEventOtel(event, level = "info", contents = {}) {
-  const timestamp = Date.now();
+  if (shouldFilterHostname()) return;
+  if (!clockSync.isReady()) {
+    preCalibrationQueue.push({ event, level, contents, enqueueMono: performance.now() });
+    return;
+  }
+  emitOtelEvent(event, level, contents, performance.now());
+}
+function flushPreCalibrationQueue() {
+  if (preCalibrationQueue.length === 0) return;
+  const pending = preCalibrationQueue.splice(0, preCalibrationQueue.length);
+  for (const e2 of pending) {
+    emitOtelEvent(e2.event, e2.level, e2.contents, e2.enqueueMono);
+  }
+}
+function emitOtelEvent(event, level, contents, atMono) {
+  contents = resolveMarks(contents);
+  const timestamp = clockSync.localAt(atMono);
+  const serverTs = clockSync.serverAt(atMono);
+  if (serverTs !== null) {
+    contents = { ...contents, server_timestamp: serverTs };
+  }
   eventStore.add({ event, level, contents, timestamp }).then((id) => {
     const contentsWithIndex = { ...contents, _index: id };
     if (!loggerProvider) return;
@@ -11807,6 +12105,15 @@ function cleanupOtel() {
     loggerProvider = null;
   }
 }
+function timestampFields(enqueueMono) {
+  const local = enqueueMono === void 0 ? clockSync.localNow() : clockSync.localAt(enqueueMono);
+  const server = enqueueMono === void 0 ? clockSync.serverNow() : clockSync.serverAt(enqueueMono);
+  const fields = { timestamp: local };
+  if (server !== null) {
+    fields.server_timestamp = server;
+  }
+  return fields;
+}
 let sdkVersion = "1.0.0";
 let isInitialized = false;
 let commonRegion = "";
@@ -11817,14 +12124,6 @@ function isPostHogEnabled() {
 const SDK_POSTHOG_INSTANCE_NAME = "spatius-posthog";
 let sdkPosthogInstance = null;
 const eventQueue = [];
-const FILTERED_HOSTNAMES = ["localhost", "127.0.0.1", "0.0.0.0"];
-function shouldFilterHostname() {
-  if (typeof window === "undefined") {
-    return false;
-  }
-  const hostname = window.location.hostname;
-  return FILTERED_HOSTNAMES.includes(hostname);
-}
 function getCommonFields() {
   const logContext = idManager.getLogContext();
   return {
@@ -11885,6 +12184,7 @@ function initializePostHog(version, commonFields) {
         }
         posthogInstance.setPersonPropertiesForFlags(userProperties);
         flushEventQueue();
+        clockSync.onReady(() => flushEventQueue());
       }
     }, SDK_POSTHOG_INSTANCE_NAME);
   } catch (error) {
@@ -11948,20 +12248,20 @@ function updatePostHogPersonPropertiesForFlags() {
   instance.setPersonPropertiesForFlags(commonFields);
 }
 function flushEventQueue() {
-  if (!sdkPosthogInstance || eventQueue.length === 0) {
+  if (!sdkPosthogInstance || !clockSync.isReady() || eventQueue.length === 0) {
     return;
   }
   logger.log(`[PostHog] Flushing ${eventQueue.length} queued events`);
   setTimeout(() => {
-    for (const { event, level, contents } of eventQueue) {
+    for (const { event, level, contents, enqueueMono } of eventQueue) {
       try {
         const commonFields = getCommonFields();
         const properties = {
           ...commonFields,
           level,
           service_module: "sdk",
-          timestamp: Date.now(),
-          ...contents
+          ...timestampFields(enqueueMono),
+          ...resolveMarks(contents)
         };
         sdkPosthogInstance.capture(event, properties);
       } catch (error) {
@@ -11977,8 +12277,8 @@ function trackEvent(event, level = "info", contents = {}) {
     return;
   }
   const instance = getSdkPosthogInstance();
-  if (!instance) {
-    eventQueue.push({ event, level, contents });
+  if (!instance || !clockSync.isReady()) {
+    eventQueue.push({ event, level, contents, enqueueMono: performance.now() });
     return;
   }
   sdkPosthogInstance = instance;
@@ -11988,8 +12288,8 @@ function trackEvent(event, level = "info", contents = {}) {
       ...commonFields,
       level,
       service_module: "sdk",
-      timestamp: Date.now(),
-      ...contents
+      ...timestampFields(),
+      ...resolveMarks(contents)
     };
     sdkPosthogInstance.capture(event, properties);
   } catch (error) {
@@ -12021,28 +12321,39 @@ function cleanupPostHog() {
     sdkPosthogInstance = null;
   }
 }
-function logEvent(event, level = "info", contents = {}) {
+const TELEMETRY_LOG_METHOD = {
+  debug: "log",
+  info: "log",
+  warning: "warn",
+  error: "error"
+};
+function buildTelemetryContext(event, level, contents) {
   const sessionToken = idManager.getSessionToken() ?? "";
   const context2 = {
     session_token_suffix: sessionToken ? sessionToken.slice(-8) : "",
     ...contents
   };
-  const logLevels = {
-    debug: "log",
-    info: "log",
-    warning: "warn",
-    error: "error"
-  };
-  const logMethod = logLevels[level] ?? "log";
+  const logMethod = TELEMETRY_LOG_METHOD[level] ?? "log";
   const propsDescription = Object.entries(contents).map(([k2, v2]) => `${k2}=${v2}`).join(", ");
   logger[logMethod](`[Telemetry] ${event} [${propsDescription}]`);
-  trackEvent(event, level, context2);
+  return context2;
+}
+function emitToOtel(event, level, context2) {
   try {
     trackEventOtel(event, level, context2);
   } catch (error) {
     logger.warn("[OTel] Dual-send failed:", error instanceof Error ? error.message : String(error));
   }
 }
+function logEvent(event, level = "info", contents = {}) {
+  const context2 = buildTelemetryContext(event, level, contents);
+  trackEvent(event, level, context2);
+  emitToOtel(event, level, context2);
+}
+function logMetric(event, level = "info", contents = {}) {
+  const context2 = buildTelemetryContext(event, level, contents);
+  emitToOtel(event, level, context2);
+}
 const _LogSink = class _LogSink {
   constructor() {
     __publicField(this, "db", null);
@@ -12544,6 +12855,8 @@ const _AnimationPlayer = class _AnimationPlayer {
     __publicField(this, "_isPlaying", false);
     __publicField(this, "fps", APP_CONFIG.animation.fps);
     __publicField(this, "onEndedCallback");
+    // 音频缓冲卡顿回调（透传给 streamingPlayer；控制器注册，用于并入 playback_quality）
+    __publicField(this, "onAudioStallCallback");
     __publicField(this, "useStreaming", false);
   }
   /**
@@ -12627,7 +12940,7 @@ const _AnimationPlayer = class _AnimationPlayer {
     if (this.streamingPlayer) {
       return;
     }
-    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-DmOtqI_a.js");
+    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-2bLnaLam.js");
     const { AvatarSDK: AvatarSDK2 } = await Promise.resolve().then(() => AvatarSDK$1);
     const audioFormat = AvatarSDK2.getAudioFormat();
     this.streamingPlayer = new StreamingAudioPlayer({
@@ -12666,6 +12979,22 @@ const _AnimationPlayer = class _AnimationPlayer {
       this._isPlaying = false;
       (_a = this.onEndedCallback) == null ? void 0 : _a.call(this);
     });
+    this.streamingPlayer.onAudioStall((stalled) => {
+      var _a;
+      (_a = this.onAudioStallCallback) == null ? void 0 : _a.call(this, stalled);
+    });
+  }
+  /**
+   * 注册音频缓冲卡顿回调，透传给底层 streamingPlayer（若已就绪则立即接上）。
+   * @internal
+   */
+  onAudioStall(callback) {
+    var _a;
+    this.onAudioStallCallback = callback;
+    (_a = this.streamingPlayer) == null ? void 0 : _a.onAudioStall((stalled) => {
+      var _a2;
+      (_a2 = this.onAudioStallCallback) == null ? void 0 : _a2.call(this, stalled);
+    });
   }
   setupEventListeners() {
     if (!this.audio)
@@ -12885,6 +13214,38 @@ class AvatarViewRegistry {
   }
 }
 const avatarViewRegistry = new AvatarViewRegistry();
+const RESOLVE_TIMEOUT_MS = 5e3;
+async function resolveRegion(opts) {
+  var _a;
+  const { appId, sdkVersion: sdkVersion2, requestedRegion } = opts;
+  if (requestedRegion !== DEFAULT_REGION_REQUEST) {
+    return requestedRegion;
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), RESOLVE_TIMEOUT_MS);
+  try {
+    const res = await fetchBootstrap(
+      { appId, sdkVersion: sdkVersion2, region: "auto" },
+      controller.signal
+    );
+    const current = (_a = res.region) == null ? void 0 : _a.current;
+    if (typeof current === "string" && current.length > 0) {
+      logger.log(`[RegionResolver] auto → ${current}`);
+      return current;
+    }
+    throw new Error("bootstrap response missing region.current");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.warn(`[RegionResolver] auto resolve failed, falling back to ${DEFAULT_REGION}: ${message}`);
+    logEvent("region_resolve_failed", "error", {
+      fallback_region: DEFAULT_REGION,
+      reason: message
+    });
+    return DEFAULT_REGION;
+  } finally {
+    clearTimeout(timer);
+  }
+}
 class AvatarCoreMemoryManager {
   constructor(wasmModule) {
     __publicField(this, "module");
@@ -14322,17 +14683,23 @@ class AvatarSDK {
   }
   static async _initializeInternal(appId, configuration) {
     try {
-      logger.log(`[AvatarSDK] Initializing with appId: ${appId}, region: ${configuration.region || DEFAULT_REGION}`);
+      const requestedRegion = configuration.region || DEFAULT_REGION_REQUEST;
+      logger.log(`[AvatarSDK] Initializing with appId: ${appId}, region: ${requestedRegion}`);
       resetDeprecationWarnings();
-      this._configuration = configuration;
       setLogLevel(configuration.logLevel ?? LogLevel.off);
       idManager.setAppId(appId);
       logger.log(`[AvatarSDK] Client ID: ${idManager.getClientId()}`);
-      const region = configuration.region || DEFAULT_REGION;
       const dsm = configuration.drivingServiceMode || DrivingServiceMode.direct;
       const appIdValue = idManager.getAppId() || "";
+      const region = await resolveRegion({
+        appId: appIdValue,
+        sdkVersion: this._version,
+        requestedRegion
+      });
+      this._configuration = { ...configuration, region };
       initializePostHog(this._version, { region, dsm });
       initializeOtel(this._version, { region, dsm, appId: appIdValue });
+      clockSync.start({ appId: appIdValue, sdkVersion: this._version });
       await this.initializeWASMModule();
       await this.initializeTemplateResources();
       this._initializationState = "initialized";
@@ -14594,6 +14961,7 @@ class AvatarSDK {
       idManager.clear();
       cleanupPostHog();
       cleanupOtel();
+      clockSync.cleanup();
       logger.log("[AvatarSDK] Cleanup completed");
     } catch (error) {
       logger.error("Failed to cleanup AvatarSDK:", error instanceof Error ? error.message : String(error));
@@ -14712,7 +15080,7 @@ class AvatarSDK {
 __publicField(AvatarSDK, "_initializationState", "uninitialized");
 __publicField(AvatarSDK, "_initializingPromise", null);
 __publicField(AvatarSDK, "_configuration", null);
-__publicField(AvatarSDK, "_version", "1.3.0");
+__publicField(AvatarSDK, "_version", "1.3.1-beta.2");
 __publicField(AvatarSDK, "_avatarCore", null);
 __publicField(AvatarSDK, "_cachedDeviceScore", null);
 __publicField(AvatarSDK, "_rendererBackend", null);
@@ -15338,14 +15706,14 @@ class NetworkLayer {
     }
     const metrics = this.audioMetrics;
     if (!metrics.taps.has(0)) {
-      metrics.taps.set(0, Date.now());
+      metrics.taps.set(0, monoTimestamp());
     }
     metrics.accumulatedBytes += audioData.byteLength;
     const currentDuration = metrics.accumulatedBytes / this.getAudioBytesPerSecond();
     const maxTapKey = metrics.taps.size > 0 ? Math.max(...metrics.taps.keys()) : 0;
     let s2 = maxTapKey + 1;
     while (currentDuration >= s2) {
-      metrics.taps.set(s2, Date.now());
+      metrics.taps.set(s2, monoTimestamp());
       s2++;
     }
     if (audioData.byteLength === 0 && !isLast) {
@@ -15353,7 +15721,6 @@ class NetworkLayer {
     }
     if (this.isFallbackMode) {
       if (this.currentConversationId) {
-        logger.warn("[NetworkLayer] Fallback mode: skipping WebSocket send, triggering fallback");
         this.dataController.yieldKeyframes([], this.currentConversationId);
       }
       return;
@@ -15502,7 +15869,7 @@ class NetworkLayer {
       if (!this.dataController.getIsPlaying()) {
         this.dataController.startStreamingPlayback();
       }
-      this.audioMetrics.anims.set(this.audioMetrics.animGroupCount, Date.now());
+      this.audioMetrics.anims.set(this.audioMetrics.animGroupCount, monoTimestamp());
       this.audioMetrics.animGroupCount++;
     } else {
       logger.warn(`[NetworkLayer] Animation message has no animation data - conversationId: ${conversationId}`);
@@ -15581,26 +15948,24 @@ class NetworkLayer {
     this.audioMetrics = this.createAudioMetrics();
   }
   /**
-   * 上报 driving_service_latency 事件
-   * 整轮播放结束(进入 idle)时由 AvatarController 调用,覆盖自然结束与中途打断两条路径
+   * 取本轮端到端延迟打点（tap_N=第N秒音频送入时刻，anim_N=第N组动画到达时刻）。
+   * 整轮播放结束(进入 idle)时由 AvatarController 读取，并入 playback_quality 的
+   * latency 成员统一上报（不再单发 driving_service_latency）。
+   * 无打点数据（如未走 direct 驱动）时返回 null，playback_quality 不带 latency。
    * @internal
    */
-  reportDrivingServiceLatency() {
-    const conversationId = this.currentConversationId;
-    if (!conversationId) return;
+  getDrivingServiceLatency() {
+    if (!this.currentConversationId) return null;
     const metrics = this.audioMetrics;
-    if (metrics.taps.size === 0 || metrics.anims.size === 0) return;
-    const props = {
-      conversation_id: conversationId,
-      dsm: "direct"
-    };
+    if (metrics.taps.size === 0 || metrics.anims.size === 0) return null;
+    const props = {};
     for (const [n2, t2] of metrics.taps) {
       props[`tap_${n2}`] = t2;
     }
     for (const [n2, t2] of metrics.anims) {
       props[`anim_${n2}`] = t2;
     }
-    logEvent("driving_service_latency", "info", props);
+    return props;
   }
   /**
    * Start driving service heartbeat check (check connection status every 2 minutes)
@@ -15897,8 +16262,23 @@ class AvatarController {
     __publicField(this, "isFallbackMode", false);
     // 降级模式标志
     // ========== Frame Starvation Tracking ==========
+    // enterMono：进入卡顿那刻的单调读数（performance.now()），恢复时用来算 durationMs。
+    // durationMs：这次卡顿持续多久（ms），帧恢复时回填；卡到播放结束都没恢复则为 null。
+    // startTs：卡顿开始的时间线时刻（clockSync.timelineNow()，优先后台、退本地，与 tap/anim 同轴）。
+    // framesAtEnter / framesAtRecover：卡顿开始/恢复时本轮已收到的服务端动画帧数
+    // （差值 = 卡顿期间到帧量，区分"服务端没发"与"发了但不够消费"）。未恢复则 framesAtRecover=null。
     __publicField(this, "frameStarvationEvents", []);
     __publicField(this, "isFrameStarved", false);
+    // ========== Audio Buffer Stall Tracking ==========
+    // 音频缓冲卡顿（缓冲耗尽自动暂停、有数据自动恢复），与帧饥饿对称记录。字段同义。
+    __publicField(this, "audioStallEvents", []);
+    __publicField(this, "isAudioBufferStalled", false);
+    // 本轮播放的结束原因（供 playback_quality 上报）：completed=正常播完，interrupted=中途打断。
+    __publicField(this, "playbackEndReason", "completed");
+    // 本轮已接收的音频总字节数（两模式统一累计）。总时长 = /audioBytesPerSecond。每轮重置。
+    __publicField(this, "receivedAudioBytes", 0);
+    // 本轮已接收的服务端下发动画帧总数（不含本地起播过渡帧）。每轮重置。
+    __publicField(this, "receivedAnimationFrames", 0);
     /**
      * Whether this round's final animation batch (ServerResponseAnimation.end) has arrived.
      * Frame starvation is only possible BEFORE this — once all frames are in, any remaining
@@ -16079,42 +16459,101 @@ class AvatarController {
   /**
    * Notify conversation state change and handle telemetry
    * @internal
-   * @param isFallback - true when entering fallback mode (suppresses playback stats)
    */
-  notifyConversationState(avatarState, isFallback = false) {
-    var _a, _b;
+  notifyConversationState(avatarState) {
+    var _a;
     switch (avatarState) {
       case AvatarState.playing:
         this.frameRateMonitor.resetPlaybackStats();
-        this.shouldReportPlaybackStats = !isFallback;
+        this.shouldReportPlaybackStats = true;
         break;
       case AvatarState.paused:
         this.shouldReportPlaybackStats = false;
         break;
       case AvatarState.idle:
-        (_a = this.networkLayer) == null ? void 0 : _a.reportDrivingServiceLatency();
         if (this.shouldReportPlaybackStats) {
-          const stats = this.frameRateMonitor.getPlaybackStats();
-          const bypassSampling = typeof window !== "undefined" && new URLSearchParams(window.location.search).get("integration") === "1";
-          if (stats.durationMs >= 2e3 && stats.frameCount > 0 && (bypassSampling || Math.random() < 0.3)) {
-            const props = {
-              avg_fps: Number(stats.avgFps.toFixed(1)),
-              frame_count: stats.frameCount,
-              duration_ms: stats.durationMs,
-              jank_ratio: Number(stats.jankRatio.toFixed(2)),
-              fps_cv: Number(stats.fpsCv.toFixed(3)),
-              ...this._getDeviceScoreProps()
-            };
-            if (AvatarSDK.getRendererBackend()) {
-              props.renderer_backend = AvatarSDK.getRendererBackend();
-            }
-            logEvent("avatar_playback_fps", "info", props);
-          }
+          this.reportPlaybackQuality();
         }
         this.shouldReportPlaybackStats = false;
         break;
     }
-    (_b = this.onConversationState) == null ? void 0 : _b.call(this, this.mapToConversationState(avatarState));
+    (_a = this.onConversationState) == null ? void 0 : _a.call(this, this.mapToConversationState(avatarState));
+  }
+  /**
+   * 上报本轮播放质量（playback_quality）。每轮播放结束都发一次（不采样、不设时长门槛），
+   * 把帧率与卡顿两块合并为嵌套成员。end_reason 区分完整播完 / 中途打断。
+   * 有卡顿时用 warning，否则 info（保留卡顿的告警语义）。
+   * @internal
+   */
+  reportPlaybackQuality() {
+    var _a, _b;
+    const stats = this.frameRateMonitor.getPlaybackStats();
+    const settled = this.frameStarvationEvents.map((e2) => e2.durationMs).filter((d2) => d2 !== null);
+    const totalStallMs = settled.reduce((a2, b2) => a2 + b2, 0);
+    const stall = {
+      count: this.frameStarvationEvents.length,
+      max_ms: settled.length > 0 ? Math.max(...settled) : 0,
+      total_ms: totalStallMs,
+      // 卡顿率 = 卡顿总时长 / 已播放时长（fps.duration_ms；打断轮即播到打断那刻，
+      // 上限为音频时长）。播放时长为 0 时记 0。
+      ratio: stats.durationMs > 0 ? Number((totalStallMs / stats.durationMs).toFixed(4)) : 0,
+      req_end: this.frameStarvationEvents.some((e2) => e2.reqEnd),
+      // 每次卡顿明细：开始时间戳（timelineNow，与 tap/anim 同轴）/ 卡顿时的音频时刻 /
+      // 等了多久（null=卡到播放结束没恢复）/ 卡顿开始与恢复时已收到的动画帧数
+      // （frames_at_recover - frames_at_enter = 卡顿期间到帧量）。
+      events: this.frameStarvationEvents.map((e2) => ({
+        start_ts: Math.round(e2.startTs),
+        audio_time: Number(e2.audioTime.toFixed(3)),
+        duration_ms: e2.durationMs,
+        frames_at_enter: e2.framesAtEnter,
+        frames_at_recover: e2.framesAtRecover
+      }))
+    };
+    const audioSettled = this.audioStallEvents.map((e2) => e2.durationMs).filter((d2) => d2 !== null);
+    const audioStall = {
+      count: this.audioStallEvents.length,
+      max_ms: audioSettled.length > 0 ? Math.max(...audioSettled) : 0,
+      total_ms: audioSettled.reduce((a2, b2) => a2 + b2, 0),
+      events: this.audioStallEvents.map((e2) => ({
+        start_ts: Math.round(e2.startTs),
+        duration_ms: e2.durationMs,
+        frames_at_enter: e2.framesAtEnter,
+        frames_at_recover: e2.framesAtRecover
+      }))
+    };
+    const fps = {
+      avg_fps: Number(stats.avgFps.toFixed(1)),
+      frame_count: stats.frameCount,
+      duration_ms: stats.durationMs,
+      jank_ratio: Number(stats.jankRatio.toFixed(2)),
+      fps_cv: Number(stats.fpsCv.toFixed(3)),
+      ...this._getDeviceScoreProps()
+    };
+    if (AvatarSDK.getRendererBackend()) {
+      fps.renderer_backend = AvatarSDK.getRendererBackend();
+    }
+    const latency = ((_a = this.networkLayer) == null ? void 0 : _a.getDrivingServiceLatency()) ?? null;
+    logMetric("playback_quality", stall.count > 0 || audioStall.count > 0 ? "warning" : "info", {
+      avatar_id: this.avatar.id,
+      conversation_id: ((_b = this.networkLayer) == null ? void 0 : _b.getCurrentConversationId()) || void 0,
+      end_reason: this.playbackEndReason,
+      // 是否降级模式（audio-only 无动画帧）：为 true 时 fps/animation_frame_count 空是预期
+      is_fallback: this.isFallbackMode,
+      // 本轮接收情况：总音频时长(ms) / 是否收到最后音频(end=true) /
+      // 服务端下发总动画帧数(不含过渡帧) / 是否收到最后动画包(end=true)
+      audio_duration_ms: Math.round(this.receivedAudioBytes / this.audioBytesPerSecond * 1e3),
+      audio_ended: this.reqEnd,
+      animation_frame_count: this.receivedAnimationFrames,
+      animation_ended: this.animationEnded,
+      fps,
+      stall,
+      audio_stall: audioStall,
+      ...latency ? { latency } : {}
+    });
+    this.frameStarvationEvents = [];
+    this.isFrameStarved = false;
+    this.audioStallEvents = [];
+    this.isAudioBufferStalled = false;
   }
   /**
    * Get animation player instance
@@ -16234,6 +16673,7 @@ class AvatarController {
     if (this.reqEnd && this.isPlaying && networkConversationId) {
       this.interrupt();
     }
+    this.receivedAudioBytes += audioData.byteLength;
     this.addAudioChunkToBuffer(new Uint8Array(audioData), end);
     this.networkLayer.sendAudioData(audioData, end);
     if (end) {
@@ -16333,18 +16773,19 @@ class AvatarController {
     if (isLast) {
       this.reqEnd = true;
     }
+    this.receivedAudioBytes += data.length;
     if (this.playbackMode === DrivingServiceMode.backend) {
       const metrics = this.hostModeMetrics;
       if (metrics.startTimestamp === 0) {
-        metrics.startTimestamp = Date.now();
+        metrics.startTimestamp = clockSync.timelineNow();
       }
       metrics.accumulatedBytes += data.length;
       const currentDuration = metrics.accumulatedBytes / this.audioBytesPerSecond;
       if (currentDuration >= 1 && metrics.tap1Timestamp === 0) {
-        metrics.tap1Timestamp = Date.now();
+        metrics.tap1Timestamp = clockSync.timelineNow();
       }
       if (currentDuration >= 2 && metrics.tap2Timestamp === 0) {
-        metrics.tap2Timestamp = Date.now();
+        metrics.tap2Timestamp = clockSync.timelineNow();
       }
     }
     if (this.isPlaying && ((_b = this.animationPlayer) == null ? void 0 : _b.isStreamingReady())) {
@@ -16461,11 +16902,12 @@ class AvatarController {
       return;
     }
     const flameKeyframes = keyframes;
+    this.receivedAnimationFrames += flameKeyframes.length;
     if (this.currentKeyframes.length === 0) {
       this.currentKeyframes = flameKeyframes;
       if (this.playbackMode === DrivingServiceMode.backend && !this.hostModeMetrics.didRecvFirstFlame) {
         this.hostModeMetrics.didRecvFirstFlame = true;
-        this.hostModeMetrics.recvFirstFlameTimestamp = Date.now();
+        this.hostModeMetrics.recvFirstFlameTimestamp = clockSync.timelineNow();
       }
     } else {
       this.currentKeyframes.push(...flameKeyframes);
@@ -16601,6 +17043,8 @@ class AvatarController {
     this.lastSyncLogTime = 0;
     this.lastOutOfBoundsState = false;
     this.animationEnded = false;
+    this.receivedAudioBytes = 0;
+    this.receivedAnimationFrames = 0;
     if (this.isAudioStalledForStarvation) {
       this.isAudioStalledForStarvation = false;
       (_a = this.onPlaybackStall) == null ? void 0 : _a.call(this, false);
@@ -16793,6 +17237,9 @@ class AvatarController {
       await this.animationPlayer.prepareStreamingPlayer(() => {
         this.onPlaybackEnded();
       });
+      this.animationPlayer.onAudioStall((stalled) => {
+        this.trackAudioBufferStall(stalled);
+      });
       if (!this.isFallbackMode) {
         this.emit("startRendering");
       }
@@ -16810,7 +17257,7 @@ class AvatarController {
       this.pendingAudioChunks = [];
       this.isPlaying = true;
       this.currentState = AvatarState.playing;
-      this.notifyConversationState(AvatarState.playing, this.isFallbackMode);
+      this.notifyConversationState(AvatarState.playing);
       this.isStartingPlayback = false;
       logEvent("playback_started", "info", {
         avatar_id: this.avatar.id,
@@ -16953,13 +17400,28 @@ class AvatarController {
         const totalKeyframes = this.currentKeyframes.length + this.keyframesOffset;
         const frameDiff = frameIndex - totalKeyframes;
         if (!(this.reqEnd && frameDiff <= 1)) {
-          this.frameStarvationEvents.push({ audioTime, reqEnd: this.reqEnd });
+          this.frameStarvationEvents.push({
+            audioTime,
+            reqEnd: this.reqEnd,
+            enterMono: performance.now(),
+            durationMs: null,
+            startTs: clockSync.timelineNow(),
+            framesAtEnter: this.receivedAnimationFrames,
+            framesAtRecover: null
+          });
         }
       }
       if (!this.animationEnded) {
         this.pauseAudioForStarvation();
       }
     } else {
+      if (this.isFrameStarved) {
+        const last = this.frameStarvationEvents[this.frameStarvationEvents.length - 1];
+        if (last && last.durationMs === null) {
+          last.durationMs = Math.round(performance.now() - last.enterMono);
+          last.framesAtRecover = this.receivedAnimationFrames;
+        }
+      }
       this.isFrameStarved = false;
       if (isOutOfBounds !== this.lastOutOfBoundsState) {
         this.lastOutOfBoundsState = isOutOfBounds;
@@ -16967,6 +17429,33 @@ class AvatarController {
       this.resumeAudioFromStarvation();
     }
   }
+  /**
+   * 记录音频缓冲卡顿（缓冲耗尽自动暂停 / 有数据自动恢复），并入 playback_quality.audio_stall。
+   * 与 trackFrameStarvation 对称：进入 push 事件、恢复回填时长与动画帧数。
+   * @param stalled true=进入卡顿，false=恢复
+   * @internal
+   */
+  trackAudioBufferStall(stalled) {
+    if (stalled) {
+      if (this.isAudioBufferStalled) return;
+      this.isAudioBufferStalled = true;
+      this.audioStallEvents.push({
+        enterMono: performance.now(),
+        durationMs: null,
+        startTs: clockSync.timelineNow(),
+        framesAtEnter: this.receivedAnimationFrames,
+        framesAtRecover: null
+      });
+    } else {
+      if (!this.isAudioBufferStalled) return;
+      this.isAudioBufferStalled = false;
+      const last = this.audioStallEvents[this.audioStallEvents.length - 1];
+      if (last && last.durationMs === null) {
+        last.durationMs = Math.round(performance.now() - last.enterMono);
+        last.framesAtRecover = this.receivedAnimationFrames;
+      }
+    }
+  }
   /**
    * strictSync: pause audio on frame starvation, waiting for new frames.
    *
@@ -17042,7 +17531,6 @@ class AvatarController {
     if (this.isFallbackMode) {
       return;
     }
-    logger.warn("[AvatarController] Enabling fallback mode");
     this.isFallbackMode = true;
     this.resumeAudioFromStarvation();
     logEvent("fallback_mode_entered", "warning", {
@@ -17076,26 +17564,15 @@ class AvatarController {
    * @internal
    */
   onPlaybackEnded() {
-    var _a, _b;
-    if (this.frameStarvationEvents.length > 0) {
-      const hasReqEnd = this.frameStarvationEvents.some((e2) => e2.reqEnd);
-      logEvent("frame_starvation", "warning", {
-        avatar_id: this.avatar.id,
-        conversation_id: ((_a = this.networkLayer) == null ? void 0 : _a.getCurrentConversationId()) || void 0,
-        starvation_count: this.frameStarvationEvents.length,
-        starvation_times: this.frameStarvationEvents.map((e2) => Number(e2.audioTime.toFixed(3))),
-        ...hasReqEnd ? { req_end: true } : {}
-      });
-    }
-    this.frameStarvationEvents = [];
-    this.isFrameStarved = false;
+    var _a;
     logEvent("playback_ended", "info", {
       avatar_id: this.avatar.id,
-      conversation_id: this.currentConversationId || ((_b = this.networkLayer) == null ? void 0 : _b.getCurrentConversationId()) || void 0,
+      conversation_id: this.currentConversationId || ((_a = this.networkLayer) == null ? void 0 : _a.getCurrentConversationId()) || void 0,
       source: this.isFallbackMode ? "fallback" : "streaming"
     });
     this.isPlaying = false;
     this.currentState = AvatarState.idle;
+    this.playbackEndReason = "completed";
     this.notifyConversationState(AvatarState.idle);
     this.emit("stopRendering");
     this.emit("stopFallback");
@@ -17113,6 +17590,7 @@ class AvatarController {
     this.emit("stopRendering");
     this.isPlaying = false;
     this.currentState = AvatarState.idle;
+    this.playbackEndReason = "interrupted";
     this.notifyConversationState(AvatarState.idle);
   }
   /**
@@ -17490,7 +17968,7 @@ class AvatarDownloader {
     if (cached) {
       const duration = Date.now() - startTime;
       logger.log(`✅ Unified template loaded from cache (${(cached.byteLength / 1024 / 1024).toFixed(1)} MB)`);
-      logEvent("template_resources_load_measure", "info", {
+      logMetric("template_resources_load_measure", "info", {
         duration,
         file_count: 1,
         cache_hit: true,
@@ -17519,7 +17997,7 @@ class AvatarDownloader {
           logger.warn(`[loadUnifiedTemplate] Failed to cache:`, err);
         });
         const duration = Date.now() - startTime;
-        logEvent("template_resources_load_measure", "info", {
+        logMetric("template_resources_load_measure", "info", {
           duration,
           file_count: 1,
           cache_hit: false,
@@ -17672,7 +18150,7 @@ class AvatarDownloader {
     const totalSize = Object.values(characterData).reduce((sum, buffer) => {
       return sum + (buffer ? buffer.byteLength : 0);
     }, 0);
-    logEvent("download_avatar_assets_latency", "info", {
+    logMetric("download_avatar_assets_latency", "info", {
       resolution: "default",
       // 目前写死 default
       avatar_id: characterMeta.characterId ?? "unknown",
@@ -17866,7 +18344,7 @@ class AvatarDownloader {
         );
       }
       const duration = Date.now() - startTime;
-      logEvent("fetch_avatar_metadata_latency", "info", {
+      logMetric("fetch_avatar_metadata_latency", "info", {
         avatar_id: characterId,
         duration,
         trace_id: traceId
@@ -18108,7 +18586,7 @@ const _AvatarManager = class _AvatarManager {
     this.avatarCache.set(id, avatar);
     logger.log("[AvatarManager] Avatar loaded successfully");
     const totalDuration = Date.now() - startTime;
-    logEvent("fetch_avatar_latency", "info", {
+    logMetric("fetch_avatar_latency", "info", {
       resolution: "default",
       // 目前写死 default
       avatar_id: id,
@@ -20400,6 +20878,11 @@ class AvatarView {
    * @internal
    */
   createCanvas(container) {
+    if (container.querySelector("canvas")) {
+      logger.warn(
+        "[AvatarView] The container already contains a <canvas>. This usually means another AvatarView was created in the same container without disposing the previous one, which will render two avatars side by side. Call dispose() on the previous AvatarView before creating a new one, or use a separate container."
+      );
+    }
     const canvas = document.createElement("canvas");
     const containerWidth = container.offsetWidth || 800;
     const containerHeight = container.offsetHeight || 600;
@@ -21746,12 +22229,13 @@ export {
   AvatarView as g,
   RENDER_QUALITY_PARAMS as h,
   DEFAULT_REGION as i,
-  LoadProgress as j,
-  AnimationType as k,
+  DEFAULT_REGION_REQUEST as j,
+  LoadProgress as k,
   logger as l,
-  ConversationState as m,
-  AvatarState as n,
-  AvatarError as o,
-  ResourceType as p,
-  extractResourceUrls as q
+  AnimationType as m,
+  ConversationState as n,
+  AvatarState as o,
+  AvatarError as p,
+  ResourceType as q,
+  extractResourceUrls as r
 };

package/dist/index.js

@@ -1,24 +1,25 @@
-import { k, b, c, o, f, d, n, g, C, m, i, D, E, F, j, L, h, R, p, T, q } from "./index-BDFs1WRg.js";
+import { m, b, c, p, f, d, o, g, C, n, i, j, D, E, F, k, L, h, R, q, T, r } from "./index-CPolDcOo.js";
 export {
-  k as AnimationType,
+  m as AnimationType,
   b as Avatar,
   c as AvatarController,
-  o as AvatarError,
+  p as AvatarError,
   f as AvatarManager,
   d as AvatarSDK,
-  n as AvatarState,
+  o as AvatarState,
   g as AvatarView,
   C as ConnectionState,
-  m as ConversationState,
+  n as ConversationState,
   i as DEFAULT_REGION,
+  j as DEFAULT_REGION_REQUEST,
   D as DrivingServiceMode,
   E as ErrorCode,
   F as FrameStarvationMode,
-  j as LoadProgress,
+  k as LoadProgress,
   L as LogLevel,
   h as RENDER_QUALITY_PARAMS,
   R as RenderQuality,
-  p as ResourceType,
+  q as ResourceType,
   T as TransitionType,
-  q as extractResourceUrls
+  r as extractResourceUrls
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spatius/avatarkit",
   "type": "module",
-  "version": "1.3.0",
+  "version": "1.3.1-beta.2",
   "packageManager": "pnpm@10.18.2",
   "description": "AvatarKit SDK - Real-time Avatar Rendering SDK for Web",
   "author": "AvatarKit Team",
@@ -87,6 +87,7 @@
   "devDependencies": {
     "@types/node": "^20.11.30",
     "@webgpu/types": "^0.1.65",
+    "fflate": "0.8.3",
     "tsx": "^4.20.6",
     "typescript": "^5.0.0",
     "vite": "^5.0.0",