@spatius/avatarkit 1.3.7 → 1.3.9

package/dist/core/AvatarController.d.ts

@@ -69,6 +69,11 @@ export declare class AvatarController {
     private receivedAudioBytes;
     private receivedAnimationFrames;
     private playbackStartedAt;
+    /**
+     * 新一轮起播时 SDK 自己打断上一轮走的也是 interrupt()；那不是宿主的动作，不记
+     * lifecycle_api_called。内部调用经 interruptForNewRound() 置位后再进 interrupt()。
+     */
+    private suppressLifecycleEvent;
     private playbackEndedAt;
     /**
      * Whether this round's final animation batch (ServerResponseAnimation.end) has arrived.
@@ -82,10 +87,6 @@ export declare class AvatarController {
      * Orthogonal to user pause — user pause/resume does not change it; only frame arrival does.
      */
     private isAudioStalledForStarvation;
-    private playbackStuckCheckState;
-    private readonly MAX_AUDIO_TIME_ZERO_COUNT;
-    private readonly MAX_AUDIO_TIME_STUCK_COUNT;
-    private readonly AUDIO_TIME_STUCK_THRESHOLD;
     private latencyMarks;
     /**
      * W3C `traceparent` the driving service stamped on this round's animation
@@ -214,6 +215,14 @@ export declare class AvatarController {
      * Animation will continue from paused frame (because animation time base comes from audio, will auto-sync)
      */
     resume(): Promise<void>;
+    /**
+     * 宿主调了 close / interrupt（AvatarView.dispose 在 View 里记）。带调用栈：排查
+     * "数字人中途消失"时，这条日志直接指出是宿主哪段代码在断连后多久做了什么。
+     * 在播时记 warning，便于按级别筛出"播到一半被宿主打断"。
+     */
+    private logLifecycleCall;
+    /** SDK 内部起新一轮时打断上一轮：走 interrupt() 但不记宿主生命周期事件。 */
+    private interruptForNewRound;
     /**
      * Interrupt current playback
      */

package/dist/core/AvatarSDK.d.ts

@@ -48,6 +48,15 @@ export declare class AvatarSDK {
     /**
      * Cleanup resources
      */
+    private static onPageHide;
+    /**
+     * pagehide 时直发一条 `page_unload`：整页刷新 / 关闭是"数字人整个消失"的一种来源
+     * （宿主自己 reload 切 region 就是实例），服务端只能看到一个 1001，客户端此前什么都
+     * 不留。走 emitDirectLog（fetch keepalive）而不是 logEvent——后者先写 IndexedDB 再等
+     * 批处理，页面卸载时发不出去。
+     */
+    private static installPageHideProbe;
+    private static removePageHideProbe;
     static cleanup(): void;
     /**
      * Device performance score (CPU + GPU).
@@ -64,8 +73,9 @@ export declare class AvatarSDK {
     /**
      * 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.
+     * Returns false when neither WebGL2 nor WebGPU can be created — that is deterministic
+     * and the benchmark is skipped. Otherwise runs the benchmark and returns true; the
+     * score thresholds are not yet enforced and will be calibrated from production data.
      */
     static isDeviceSupported(): Promise<boolean>;
-    private static _getGPURenderer;
 }

package/dist/core/AvatarView.d.ts

@@ -13,6 +13,10 @@ export declare class AvatarView {
     private resizeObserver;
     private onWindowResize;
     private onVisibilityChange;
+    private canvasSeenConnected;
+    private canvasDetachedReported;
+    private containerSeenSized;
+    private containerHiddenReported;
     private frameCount;
     private lastFpsUpdate;
     private currentFPS;
@@ -52,6 +56,44 @@ export declare class AvatarView {
         width: number;
         height: number;
     };
+    /**
+     * Set once the first-frame callback has fired; the render loop samples the
+     * canvas on the first frame after this deadline and then clears it.
+     *
+     * The check exists because "the render loop is running" does not mean anything
+     * reached the screen. Failures along the render path mostly log and return, so
+     * a user seeing nothing produces no signal at all. This asks the only question
+     * that matters at the end: did this layer draw anything?
+     *
+     * Sampling has to happen inside the loop, right after renderFrame() — the
+     * context runs with preserveDrawingBuffer:false, so the buffer is only valid
+     * there. Reading from a timer would find it already cleared and report every
+     * healthy session as blank.
+     */
+    private _blankCheckDueAt;
+    private _blankCheckDone;
+    /** How long after the first frame to sample. Long enough for the pipeline to settle. */
+    private static readonly BLANK_CHECK_DELAY_MS;
+    /**
+     * Sample size. The browser scales the full canvas into this, so it covers the
+     * whole frame rather than a crop — the avatar is found wherever it sits. Kept
+     * tiny because the question is only "any opaque pixel at all"; reading the
+     * full canvas would copy megabytes for a yes/no answer.
+     */
+    private static readonly BLANK_CHECK_WIDTH;
+    private static readonly BLANK_CHECK_HEIGHT;
+    private scheduleBlankCanvasCheck;
+    /**
+     * Called from the render loop immediately after renderFrame(), while the
+     * drawing buffer is still valid.
+     */
+    private runBlankCanvasCheckIfDue;
+    /**
+     * Count pixels that are not fully transparent. Null when the sample could not
+     * be taken at all, which is not the same as a blank frame and must not be
+     * reported as one.
+     */
+    private countOpaquePixels;
     private _exportBitmapResolve;
     /**
      * Exports the current rendering as a Blob (PNG).
@@ -62,8 +104,12 @@ export declare class AvatarView {
      * to work correctly with WebGL preserveDrawingBuffer:false.
      */
     exportBitmap(): Promise<Blob | null>;
-    /** @deprecated Use startRenderLoop() */
-    private startIdleAnimationLoop;
+    /**
+     * 当前初始化走到哪一步。供构造函数里的最终 catch 上报 `render_init_failed.stage`：
+     * 各步骤抛的错误类型五花八门（Error / AvatarError / WASM 抛的字符串），只靠
+     * message 没法聚合，stage 才是能按环节切分的低基数字段。
+     */
+    private _initStage;
     /**
      * Render a specific idle frame by index for benchmark capture.
      * Bypasses animation loop and _renderingEnabled check.
@@ -80,11 +126,17 @@ export declare class AvatarView {
      */
     dispose(): void;
     /**
-     * 获取相机配置
+     * 获取相机配置。
+     *
+     * @deprecated 1.3.9 起弃用，下个版本移除。相机由角色自身的设置决定，渲染基线也按它校准；
+     * 宿主侧改 fov / 位置会让画面偏离基线。没有替代接口——请删除宿主侧的相机覆盖逻辑。
+     * SDK 自己的评测链路（web-iframe）仍可调用。
      */
     getCameraConfig(): CameraConfig | null;
     /**
-     * 更新相机配置
+     * 更新相机配置。
+     *
+     * @deprecated 1.3.9 起弃用，下个版本移除，理由见 {@link getCameraConfig}。
      */
     updateCameraConfig(cameraConfig: CameraConfig): void;
     /**
@@ -96,30 +148,6 @@ export declare class AvatarView {
      * @param data - Raw protobuf bytes (a single Message containing ServerResponseAnimation)
      */
     renderFromProtobuf(data: ArrayBuffer | Uint8Array): Promise<void>;
-    /**
-     * Play a transition from idle to the target frame in the protobuf data,
-     * then resolve when the transition is complete.
-     *
-     * The transition frames are generated and played internally at 25fps.
-     * The caller should wait for the returned Promise before pushing streaming frames.
-     *
-     * @param data - Raw protobuf bytes containing the target frame
-     * @param frameCount - Number of transition frames to generate
-     * @returns Promise that resolves when the transition playback finishes
-     */
-    playTransitionFromProtobuf(data: ArrayBuffer | Uint8Array, frameCount: number): Promise<void>;
-    /**
-     * Play a transition from current animation back to idle,
-     * then start the idle animation loop.
-     *
-     * Generates reverse transition frames from idle→lastFrame, reverses them,
-     * plays at 25fps, then starts idle.
-     *
-     * @param data - Raw protobuf bytes containing the last animation frame
-     * @param frameCount - Number of transition frames to generate
-     * @returns Promise that resolves when idle animation starts
-     */
-    playTransitionToIdleFromProtobuf(data: ArrayBuffer | Uint8Array, frameCount: number): Promise<void>;
     /**
      * Start idle animation (stop pure rendering mode, resume idle loop).
      */
@@ -151,10 +179,19 @@ export declare class AvatarView {
         useLinear?: boolean;
     }): Promise<unknown[]>;
     /**
-     * Cancel any in-progress frame sequence playback.
-     * Called by renderFromProtobuf when streaming frames arrive during transition.
+     * canvas 是否还挂在 DOM 上。宿主卸载父组件而没调 dispose() 时，canvas 会跟着容器
+     * 一起被移除，SDK 却还在跑：没有任何现有埋点会响。渲染循环每 tick 查一次
+     * `isConnected`（不触发 layout），脱离时记一条 error，重新挂回记一条 info。
+     * 只在 canvas 曾经在 DOM 里之后才判，避免离屏构造的误报。
+     */
+    private probeCanvasAttachment;
+    /**
+     * 容器被缩成 0×0（display:none 或父级折叠）时 ResizeObserver 会回调一次 0 尺寸。
+     * 画面还在 DOM 里但用户看不见，与 detach 是不同的消失方式，分开记。
+     * 只在容器曾有过非零尺寸之后才判。
      */
-    cancelFrameSequence(): void;
+    private probeContainerVisibility;
+    private syncCanvasSize;
     /** 计算 canvas backing-store 像素尺寸. 默认 css × dpr;
      *  AvatarSDK.setRenderResolutionCap 启用且高度超过阈值时,
      *  按比例缩到阈值, css 尺寸不变 (浏览器自动拉伸). */

package/dist/core/avatarViewRegistry.d.ts

@@ -3,6 +3,8 @@ declare class AvatarViewRegistry {
     private entries;
     register(view: AvatarView): void;
     unregister(view: AvatarView): void;
+    /** 遍历仍存活的 view（顺手清掉已被 GC 的弱引用）。 */
+    forEachLive(fn: (view: AvatarView) => void): void;
     applyResolutionCapToAll(): void;
 }
 export declare const avatarViewRegistry: AvatarViewRegistry;