@spatialwalk/avatarkit 1.0.0-beta.4 → 1.0.0-beta.41

package/dist/index.d.ts

@@ -1,12 +1,7 @@
-/**
- * SPAvatar SDK - 统一公开接口
- */
-export { APP_CONFIG } from './config/app-config';
 export { Avatar } from './core/Avatar';
 export { AvatarController } from './core/AvatarController';
-export { AvatarKit } from './core/AvatarKit';
+export { AvatarSDK } from './core/AvatarSDK';
 export { AvatarManager } from './core/AvatarManager';
 export { AvatarView } from './core/AvatarView';
 export * from './types';
 export type { CharacterInfo, FlameInfo } from './wasm/avatarCoreAdapter';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,20 +1,19 @@
-import { A as s, b as o, c as e, a as t, d as n, h as A, g as v, f as l, C as c, E as g, L as i, R as M, S as P, i as d, j as u, k as C } from "./index-BDxVrKwm.js";
+import { b, c, f, d, j, g, C, i, D, E, k, h, L, R, S, m } from "./index-CRKYjlwp.js";
 export {
-  s as APP_CONFIG,
-  o as Avatar,
-  e as AvatarController,
-  t as AvatarKit,
-  n as AvatarManager,
-  A as AvatarPlaybackMode,
-  v as AvatarState,
-  l as AvatarView,
-  c as ConnectionState,
-  g as Environment,
-  i as LoadProgress,
-  M as ResourceType,
-  P as SPAvatarError,
-  d as extractResourceUrls,
-  u as hasMonologue,
-  C as hasMonologueFromModelInfo
+  b as Avatar,
+  c as AvatarController,
+  f as AvatarManager,
+  d as AvatarSDK,
+  j as AvatarState,
+  g as AvatarView,
+  C as ConnectionState,
+  i as ConversationState,
+  D as DrivingServiceMode,
+  E as Environment,
+  k as ErrorCode,
+  h as LoadProgress,
+  L as LogLevel,
+  R as ResourceType,
+  S as SPAvatarError,
+  m as extractResourceUrls
 };
-//# sourceMappingURL=index.js.map

package/dist/renderer/RenderSystem.d.ts

@@ -1,79 +1 @@
-import { CameraConfig } from '../types';
-import { RenderBackend } from './renderer';
-export interface RenderSystemOptions {
-    canvas: HTMLCanvasElement;
-    preferBackend?: RenderBackend;
-    backgroundColor?: [number, number, number, number];
-    camera?: CameraConfig;
-}
-export declare class RenderSystem {
-    private renderer;
-    private backend;
-    private canvas;
-    private options;
-    private camera;
-    private viewMatrix;
-    private projectionMatrix;
-    private originalPackedData;
-    renderTime: number;
-    sortTime: number;
-    constructor(options: RenderSystemOptions);
-    /**
-     * 初始化渲染系统
-     */
-    initialize(): Promise<void>;
-    /**
-     * 加载已打包的 Splat 数据（零拷贝，GPU 格式）
-     * 直接接收 WASM 的 packed 数据
-     *
-     * @param packedData Float32Array [pos3, color4, cov6] x N 个点
-     */
-    loadSplatsFromPackedData(packedData: Float32Array): void;
-    /**
-     * 渲染一帧
-     */
-    renderFrame(): void;
-    /**
-     * 更新相机参数
-     */
-    updateCamera(params: Partial<CameraConfig>): void;
-    /**
-     * 处理窗口大小变化
-     */
-    handleResize(): void;
-    /**
-     * 获取当前使用的后端
-     */
-    getBackend(): RenderBackend | null;
-    /**
-     * 清理资源
-     */
-    dispose(): void;
-    /**
-     * 检查 WebGPU 支持
-     */
-    private checkWebGPUSupport;
-    /**
-     * 更新相机长宽比
-     */
-    private updateCameraAspect;
-    /**
-     * 更新相机矩阵
-     */
-    private updateCameraMatrices;
-    /**
-     * 获取相机前向向量
-     */
-    private getCameraForward;
-    /**
-     * 更新透视投影矩阵（复用缓冲区）
-     */
-    private updatePerspectiveMatrix;
-    /**
-     * 更新视图矩阵（直接更新预分配的缓冲区，避免每帧分配）
-     * 等价于：inverse(translation) * inverse(rotation) = T^(-1) * R^(-1)
-     * 其中 T 是平移矩阵，R 是旋转矩阵
-     */
-    private updateViewMatrix;
-}
-//# sourceMappingURL=RenderSystem.d.ts.map
+export {};

package/dist/renderer/covariance.d.ts

@@ -1,13 +1 @@
-/**
- * 3D 协方差矩阵计算工具
- * 用于从缩放和旋转参数计算 Gaussian Splat 的协方差矩阵
- */
-/**
- * 计算 3D 协方差矩阵
- *
- * @param scale - 缩放向量 [sx, sy, sz]
- * @param rotation - 四元数旋转 [qx, qy, qz, qw]
- * @returns 3x3 协方差矩阵
- */
 export declare function computeCovariance3D(scale: number[], rotation: number[]): number[][];
-//# sourceMappingURL=covariance.d.ts.map

package/dist/renderer/renderer.d.ts

@@ -1,8 +1,12 @@
+export interface Transform {
+    x: number;
+    y: number;
+    scale: number;
+}
 export interface I3DGSRenderer {
     initialize: () => Promise<void>;
     loadSplatsFromPackedData: (packedData: Float32Array, pointCount: number, sortOrder?: Uint32Array) => void;
-    render: (viewMatrix: Float32Array, projectionMatrix: Float32Array, screenSize: [number, number]) => void;
+    render: (viewMatrix: Float32Array, projectionMatrix: Float32Array, screenSize: [number, number], transform?: Transform) => void;
     dispose: () => void;
 }
 export type RenderBackend = 'webgl' | 'webgpu';
-//# sourceMappingURL=renderer.d.ts.map

package/dist/renderer/sortSplats.d.ts

@@ -1,12 +1 @@
-/**
- * Splat 深度排序（Radix Sort 优化版）
- * 使用 11-bit 两轮基数排序，O(n) 时间复杂度
- */
-/**
- * 对 splats 进行深度排序（Radix Sort）
- * @param packedData Packed 格式数据 [pos3, color4, cov6] x N
- * @param cameraPosition 相机位置
- * @param cameraForward 相机前向向量
- */
 export declare function sortSplats(packedData: Float32Array, cameraPosition: [number, number, number], cameraForward: [number, number, number]): Uint32Array;
-//# sourceMappingURL=sortSplats.d.ts.map

package/dist/renderer/webgl/reorderData.d.ts

@@ -1,14 +1 @@
-/**
- * Packed Data 工具函数
- *
- * Packed 格式：[pos3, color4, cov6] x N 个点
- * 每个点 13 个 float，共 52 bytes
- */
-/**
- * 重新排序 packed 数据（复用缓冲区）
- * @param packedData 原始数据 [pos3, color4, cov6] x N
- * @param sortOrder 排序索引数组
- * @returns 重排序后的数据（复用的缓冲区引用）
- */
 export declare function reorderPackedData(packedData: Float32Array, sortOrder: Uint32Array): Float32Array;
-//# sourceMappingURL=reorderData.d.ts.map

package/dist/renderer/webgl/webglRenderer.d.ts

@@ -1,4 +1,4 @@
-import { I3DGSRenderer } from '../renderer';
+import { I3DGSRenderer, Transform } from '../renderer';
 export declare class WebGLRenderer implements I3DGSRenderer {
     private canvas;
     private backgroundColor;
@@ -12,55 +12,32 @@ export declare class WebGLRenderer implements I3DGSRenderer {
     private splatCount;
     private isInitialized;
     private splatBufferSize;
-    constructor(canvas: HTMLCanvasElement, backgroundColor?: [number, number, number, number]);
-    /**
-     * 初始化 WebGL 渲染器
-     */
+    private framebuffer;
+    private renderTexture;
+    private depthBuffer;
+    private framebufferWidth;
+    private framebufferHeight;
+    private blitShaderProgram;
+    private blitUniformLocations;
+    private blitAttributeLocations;
+    private blitQuadBuffer;
+    private blitVAO;
+    constructor(canvas: HTMLCanvasElement, backgroundColor?: [number, number, number, number], alpha?: boolean);
+    private alpha;
     initialize(): Promise<void>;
-    /**
-     * 设置着色器位置
-     */
     private setupShaderLocations;
-    /**
-     * 设置 WebGL 渲染状态
-     */
     private setupWebGLState;
-    /**
-     * 创建渲染缓冲区
-     */
     private createBuffers;
-    /**
-     * 创建四边形顶点缓冲区（实例化渲染用）
-     */
     private createQuadVertexBuffer;
-    /**
-     * 从已打包数据加载（零拷贝，GPU 优化路径）
-     * 🚀 性能优化版本：直接使用 WASM 输出的 packed 数据
-     * 🚀 Buffer 复用：避免每帧重新分配，使用 bufferSubData 更新
-     * @param packedData Float32Array [pos3, color4, cov6] x N 个点
-     * @param pointCount 点数
-     * @param _sortOrder WebGL 忽略此参数（已在 RenderSystem 中重排序）
-     */
     loadSplatsFromPackedData(packedData: Float32Array, pointCount: number, _sortOrder?: Uint32Array): void;
-    /**
-     * 上传数据到 GPU
-     */
     private uploadToGPU;
-    /**
-     * 设置实例化渲染顶点属性
-     */
     private setupVertexAttributes;
-    /**
-     * 渲染一帧
-     */
-    render(viewMatrix: Float32Array, projectionMatrix: Float32Array, screenSize: [number, number]): void;
-    /**
-     * 创建着色器程序
-     */
+    render(viewMatrix: Float32Array, projectionMatrix: Float32Array, screenSize: [number, number], transform?: Transform): void;
     private createShaderProgram;
-    /**
-     * 清理资源
-     */
+    updateBackgroundColor(backgroundColor: [number, number, number, number]): void;
+    private render3DGS;
+    private createFramebuffer;
+    private createBlitShader;
+    private blitToScreen;
     dispose(): void;
 }
-//# sourceMappingURL=webglRenderer.d.ts.map

package/dist/renderer/webgpu/webgpuRenderer.d.ts

@@ -1,54 +1,41 @@
-import { I3DGSRenderer } from '../renderer';
+import { I3DGSRenderer, Transform } from '../renderer';
 export declare class WebGPURenderer implements I3DGSRenderer {
     private canvas;
     private backgroundColor;
     private device;
     private context;
     private renderPipeline;
+    private renderTexturePipeline;
     private quadVertexBuffer;
     private uniformBuffer;
     private uniformBindGroup;
     private sortIndexBuffer;
     private splatDataBuffer;
     private storageBindGroup;
-    private lastSortOrder;
     private bindGroupNeedsUpdate;
     private splatCount;
     private presentationFormat;
-    constructor(canvas: HTMLCanvasElement, backgroundColor?: [number, number, number, number]);
-    /**
-     * 初始化 WebGPU 渲染器
-     */
+    private alpha;
+    private renderTexture;
+    private renderTextureView;
+    private depthTexture;
+    private framebufferWidth;
+    private framebufferHeight;
+    private blitPipeline;
+    private blitUniformBuffer;
+    private blitQuadBuffer;
+    private blitSampler;
+    constructor(canvas: HTMLCanvasElement, backgroundColor?: [number, number, number, number], alpha?: boolean);
     initialize(): Promise<void>;
-    /**
-     * 创建 Uniform Buffer
-     */
     private createUniformBuffer;
-    /**
-     * 创建四边形顶点缓冲区（实例化渲染用）
-     */
     private createQuadVertexBuffer;
-    /**
-     * 创建 Render Pipeline
-     */
     private createRenderPipeline;
-    /**
-     * 从已打包数据加载
-     * 🚀 间接索引渲染：packedData 是原始数据，sortOrder 是排序索引
-     * 🚀 完全消除 CPU 重排序开销
-     */
+    private createBlitPipeline;
+    private createRenderTexture;
     loadSplatsFromPackedData(packedData: Float32Array, pointCount: number, sortOrder?: Uint32Array): void;
-    /**
-     * 渲染一帧
-     */
-    render(viewMatrix: Float32Array, projectionMatrix: Float32Array, screenSize: [number, number]): void;
-    /**
-     * 更新 Uniform Buffer
-     */
+    render(viewMatrix: Float32Array, projectionMatrix: Float32Array, screenSize: [number, number], transform?: Transform): void;
+    private blitToScreen;
     private updateUniforms;
-    /**
-     * 清理资源
-     */
+    updateBackgroundColor(backgroundColor: [number, number, number, number]): void;
     dispose(): void;
 }
-//# sourceMappingURL=webgpuRenderer.d.ts.map

package/dist/types/character-settings.d.ts

@@ -1,7 +1,3 @@
-/**
- * Character settings type definitions for character templates
- * Backend guarantees the schema although it is weakly typed in proto.
- */
 export interface EyelidSettings {
     auto_eyelid_adjustment: boolean;
     enabled: boolean;
@@ -20,4 +16,3 @@ export interface CharacterSettings {
     eyelid: EyelidSettings;
     camera: CameraSettings;
 }
-//# sourceMappingURL=character-settings.d.ts.map

package/dist/types/character.d.ts

@@ -1,8 +1,6 @@
 import { CharacterAsset } from '../generated/driveningress/v2/driveningress';
 import { CameraSettings, CharacterSettings } from './character-settings';
-/**
- * 角色元数据
- */
+
 export type CharacterMeta = CharacterAsset & {
     characterSettings?: CharacterSettings;
 };
@@ -12,28 +10,12 @@ export type PreloadResources<T> = {
 export type PreloadCameraSettings = PreloadResources<{
     camera: CameraSettings;
 }>;
-/**
- * 资源类型枚举
- */
+
 export declare enum ResourceType {
     CAMERA = "camera",
     ANIMATION_IDLE = "frameIdle",
-    ANIMATION_MONO = "frameMono",
-    AUDIO_MONO = "audioMono",
     MODEL_SHAPE = "shape",
     MODEL_GS = "gsStandard"
 }
-/**
- * 提取所有资源 URL
- */
+
 export declare function extractResourceUrls(meta: CharacterMeta): Record<ResourceType, string | null>;
-/**
- * 检查角色是否有完整的独白资源
- */
-export declare function hasMonologue(meta: CharacterMeta): boolean;
-/**
- * 从 RealtimeCharacter 的 modelInfo JSON 中解析是否有独白
- * modelInfo 是一个 JSON 字符串，包含角色的模型信息
- */
-export declare function hasMonologueFromModelInfo(modelInfo: string): boolean;
-//# sourceMappingURL=character.d.ts.map

package/dist/types/index.d.ts

@@ -1,19 +1,39 @@
-/**
- * 统一公开类型 & 接口
- */
 export declare enum Environment {
     cn = "cn",
-    us = "us",
-    test = "test"
+    intl = "intl"
+}
+export declare enum DrivingServiceMode {
+
+    sdk = "sdk",
+
+    host = "host"
+}
+export declare enum LogLevel {
+
+    off = "off",
+
+    error = "error",
+
+    warning = "warning",
+
+    all = "all"
+}
+export interface AudioFormat {
+    readonly channelCount: 1;
+    readonly sampleRate: number;
 }
 export interface Configuration {
     readonly environment: Environment;
+    readonly drivingServiceMode?: DrivingServiceMode;
+    readonly logLevel?: LogLevel;
+    readonly audioFormat?: AudioFormat;
+    readonly characterApiBaseUrl?: string;
 }
 export interface SdkConfigResponse {
     endpoints: {
         cn?: string;
+        intl?: string;
         us?: string;
-        test?: string;
     };
 }
 export declare enum LoadProgress {
@@ -32,14 +52,31 @@ export declare enum ConnectionState {
     connected = "connected",
     failed = "failed"
 }
-export declare enum AvatarState {
-    idle = "idle",// 空闲状态，呈现呼吸态
-    active = "active",// 活跃中，等待可播放内容
-    playing = "playing"
+export declare enum ConversationState {
+
+    idle = "idle",
+
+    playing = "playing",
+
+    pausing = "pausing"
+}
+export declare enum ErrorCode {
+
+    appIDUnrecognized = "appIDUnrecognized",
+
+    avatarIDUnrecognized = "avatarIDUnrecognized",
+
+    sessionTokenInvalid = "sessionTokenInvalid",
+
+    sessionTokenExpired = "sessionTokenExpired",
+
+    failedToFetchAvatarMetadata = "failedToFetchAvatarMetadata",
+
+    failedToDownloadAvatarAssets = "failedToDownloadAvatarAssets"
 }
 export declare class SPAvatarError extends Error {
-    code?: string | undefined;
-    constructor(message: string, code?: string | undefined);
+    code?: (string | ErrorCode) | undefined;
+    constructor(message: string, code?: (string | ErrorCode) | undefined);
 }
 export interface FlatSplatData {
     positions: Float32Array;
@@ -58,29 +95,28 @@ export interface CameraConfig {
     up?: [number, number, number];
     aspect?: number;
 }
-export interface RenderPerformanceStats {
-    renderTime: number;
-    sortTime: number;
-    backend: 'webgpu' | 'webgl' | null;
-    pointCount?: number;
-}
-/**
- * 播放模式
- */
-export declare enum AvatarPlaybackMode {
-    /** 网络模式：通过 WebSocket 发送音频，接收动画数据 */
-    network = "network",
-    /** 外部数据模式：外部提供音频和动画数据, SDK 负责同步播放 */
-    external = "external"
-}
-/**
- * AvatarView 配置选项
- */
-export interface AvatarViewOptions {
-    /** 播放模式 */
-    playbackMode?: AvatarPlaybackMode;
-    /** Canvas 容器 */
-    container?: HTMLElement;
+
+export interface PostProcessingConfig {
+    rotation?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    neckPose?: {
+        x?: number;
+        y?: number;
+        z?: number;
+        weightX?: number;
+        weightY?: number;
+        weightZ?: number;
+    };
+    jawPose?: {
+        x?: number;
+        y?: number;
+        z?: number;
+        weight?: number;
+    };
+    eyeBlink?: number;
+    expressionWeight?: number;
 }
 export * from './character';
-//# sourceMappingURL=index.d.ts.map

package/dist/utils/animation-interpolation.d.ts

@@ -1,17 +1,7 @@
 import { Flame } from '../generated/driveningress/v1/driveningress';
-/**
- * Linear interpolation with cosine easing (ease-in-ease-out)
- * 0.5 - cos(progress * π) * 0.5
- */
+
 export declare function linearLerp(from: Flame, to: Flame, progress: number): Flame;
-/**
- * Generate transition keyframes between two Flame states
- * @param durationMs Transition duration (e.g. 400ms)
- * @param fps Frames per second (default 25)
- */
+
 export declare function generateTransitionFrames(from: Flame, to: Flame, durationMs: number, fps?: number): Flame[];
-/**
- * Create a neutral Flame
- */
+
 export declare function createNeutralFlame(): Flame;
-//# sourceMappingURL=animation-interpolation.d.ts.map

package/dist/utils/client-id.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/conversationId.d.ts

@@ -0,0 +1 @@
+export declare function generateConversationId(): string;

package/dist/utils/error-utils.d.ts

@@ -1,27 +1,3 @@
-/**
- * Error Utility Functions
- * Provides consistent error handling and formatting across the application
- */
-/**
- * Convert unknown error to a readable error message string
- *
- * @param err - Unknown error object (could be Error, string, object, etc.)
- * @returns Formatted error message string
- *
- * @example
- * try {
- *   riskyOperation()
- * } catch (err) {
- *   const message = errorToMessage(err)
- *   logger.error('Operation failed:', message)
- * }
- */
 export declare function errorToMessage(err: unknown): string;
-/**
- * Convert unknown error to a detailed error message with stack trace (for logging)
- *
- * @param err - Unknown error object
- * @returns Detailed error message with stack if available
- */
+
 export declare function errorToDetailedMessage(err: unknown): string;
-//# sourceMappingURL=error-utils.d.ts.map

package/dist/utils/heartbeat-manager.d.ts

@@ -0,0 +1,18 @@
+import { Environment } from '../types';
+declare class HeartbeatManager {
+    private heartbeatTimer;
+    private visibilityChangeHandler;
+    private isInitialized;
+    private currentEnvironment;
+    private currentAppId;
+    private failureCount;
+    start(environment: Environment): void;
+    stop(): void;
+    private startHeartbeatTimer;
+    private stopHeartbeatTimer;
+    private reportHeartbeat;
+    private setupVisibilityListener;
+    private removeVisibilityListener;
+}
+export declare const heartbeatManager: HeartbeatManager;
+export {};

package/dist/utils/id-manager.d.ts

@@ -0,0 +1,38 @@
+export interface SdkIds {
+    clientId: string;
+    userId: string | null;
+    appId: string | null;
+    sessionToken: string | null;
+    connectionId: string | null;
+    conversationId: string | null;
+}
+declare class IdManager {
+    private ids;
+    constructor();
+    getClientId(): string;
+    setUserId(userId: string | null): void;
+    getUserId(): string | null;
+    setAppId(appId: string | null): void;
+    getAppId(): string | null;
+    setSessionToken(token: string | null): void;
+    getSessionToken(): string | null;
+    generateConnectionId(): string;
+    setConnectionId(connectionId: string | null): void;
+    getConnectionId(): string | null;
+    clearConnectionId(): void;
+    generateNewConversationId(): string;
+    getConversationId(): string | null;
+    setConversationId(conversationId: string | null): void;
+    clearConversationId(): void;
+    getAllIds(): Readonly<SdkIds>;
+    getLogContext(): {
+        client_id: string;
+        user_id: string;
+        app_id: string;
+        connection_id?: string;
+        conversation_id?: string;
+    };
+    clear(): void;
+}
+export declare const idManager: IdManager;
+export {};