@spatialwalk/avatarkit 1.0.0-beta.7 → 1.0.0-beta.70

package/dist/index.d.ts

@@ -1,12 +1,10 @@
 /**
- * SPAvatar SDK - 统一公开接口
+ * AvatarKit SDK - Unified Public API
  */
-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-CpSvWi6A.js";
+import { b, c, m, f, d, j, g, C, i, D, E, k, h, L, R, n } from "./index-CvW_c7G-.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,
+  m as AvatarError,
+  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,
+  n as extractResourceUrls
 };
-//# sourceMappingURL=index.js.map

package/dist/renderer/RenderSystem.d.ts

@@ -1,79 +1,9 @@
-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
+/**
+ * Render System - Unified WebGL/WebGPU rendering management
+ *
+ * Responsibilities:
+ * 1. Automatically select rendering backend (WebGPU preferred, fallback to WebGL)
+ * 2. Camera management
+ * 3. Matrix calculations
+ */
+export {};

package/dist/renderer/covariance.d.ts

@@ -1,13 +1,5 @@
 /**
- * 3D 协方差矩阵计算工具
- * 用于从缩放和旋转参数计算 Gaussian Splat 的协方差矩阵
+ * 3D Covariance Matrix Calculation Utility
+ * Used to calculate Gaussian Splat covariance matrix from scale and rotation parameters
  */
-/**
- * 计算 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
+export {};

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,5 @@
 /**
- * Splat 深度排序（Radix Sort 优化版）
- * 使用 11-bit 两轮基数排序，O(n) 时间复杂度
+ * Splat depth sorting (Radix Sort optimized version)
+ * Uses 11-bit radix sort, O(n) time complexity
  */
-/**
- * 对 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
+export {};

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

@@ -1,14 +1,7 @@
 /**
- * Packed Data 工具函数
+ * Packed Data utility functions
  *
- * Packed 格式：[pos3, color4, cov6] x N 个点
- * 每个点 13 个 float，共 52 bytes
+ * Packed format: [pos3, color4, cov6] x N points
+ * Each point has 13 floats, 52 bytes total
  */
-/**
- * 重新排序 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
+export {};

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,7 +12,18 @@ export declare class WebGLRenderer implements I3DGSRenderer {
     private splatCount;
     private isInitialized;
     private splatBufferSize;
-    constructor(canvas: HTMLCanvasElement, backgroundColor?: [number, number, number, number]);
+    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;
     /**
      * 初始化 WebGL 渲染器
      */
@@ -53,14 +64,33 @@ export declare class WebGLRenderer implements I3DGSRenderer {
     /**
      * 渲染一帧
      */
-    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;
+    /**
+     * 渲染 3DGS 场景（公共方法，用于直接渲染和渲染到 framebuffer）
+     */
+    private render3DGS;
+    /**
+     * 创建 framebuffer 和 render texture
+     */
+    private createFramebuffer;
+    /**
+     * 创建 blit shader（用于绘制 render texture 到屏幕）
+     */
+    private createBlitShader;
+    /**
+     * 将 render texture 绘制到屏幕（应用 transform）
+     */
+    private blitToScreen;
     /**
      * 清理资源
      */
     dispose(): void;
 }
-//# sourceMappingURL=webglRenderer.d.ts.map

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

@@ -1,21 +1,31 @@
-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]);
+    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);
     /**
      * 初始化 WebGPU 渲染器
      */
@@ -32,6 +42,14 @@ export declare class WebGPURenderer implements I3DGSRenderer {
      * 创建 Render Pipeline
      */
     private createRenderPipeline;
+    /**
+     * 创建 Blit Pipeline（用于绘制 render texture 到屏幕）
+     */
+    private createBlitPipeline;
+    /**
+     * 创建 render texture 和 depth texture
+     */
+    private createRenderTexture;
     /**
      * 从已打包数据加载
      * 🚀 间接索引渲染：packedData 是原始数据，sortOrder 是排序索引
@@ -41,14 +59,21 @@ export declare class WebGPURenderer implements I3DGSRenderer {
     /**
      * 渲染一帧
      */
-    render(viewMatrix: Float32Array, projectionMatrix: Float32Array, screenSize: [number, number]): void;
+    render(viewMatrix: Float32Array, projectionMatrix: Float32Array, screenSize: [number, number], transform?: Transform): void;
+    /**
+     * 将 render texture 绘制到屏幕（应用 transform）
+     */
+    private blitToScreen;
     /**
      * 更新 Uniform Buffer
      */
     private updateUniforms;
+    /**
+     * 更新背景颜色
+     */
+    updateBackgroundColor(backgroundColor: [number, number, number, number]): void;
     /**
      * 清理资源
      */
     dispose(): void;
 }
-//# sourceMappingURL=webgpuRenderer.d.ts.map

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

@@ -18,6 +18,6 @@ export interface CameraSettings {
 }
 export interface CharacterSettings {
     eyelid: EyelidSettings;
+    eyefocus?: EyelidSettings;
     camera: CameraSettings;
 }
-//# sourceMappingURL=character-settings.d.ts.map

package/dist/types/character.d.ts

@@ -1,7 +1,7 @@
 import { CharacterAsset } from '../generated/driveningress/v2/driveningress';
 import { CameraSettings, CharacterSettings } from './character-settings';
 /**
- * 角色元数据
+ * Character metadata
  */
 export type CharacterMeta = CharacterAsset & {
     characterSettings?: CharacterSettings;
@@ -13,27 +13,15 @@ export type PreloadCameraSettings = PreloadResources<{
     camera: CameraSettings;
 }>;
 /**
- * 资源类型枚举
+ * Resource type enumeration
  */
 export declare enum ResourceType {
     CAMERA = "camera",
     ANIMATION_IDLE = "frameIdle",
-    ANIMATION_MONO = "frameMono",
-    AUDIO_MONO = "audioMono",
     MODEL_SHAPE = "shape",
     MODEL_GS = "gsStandard"
 }
 /**
- * 提取所有资源 URL
+ * Extract all resource URLs
  */
 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,20 +1,42 @@
 /**
- * 统一公开类型 & 接口
+ * Unified public types & interfaces
  */
 export declare enum Environment {
     cn = "cn",
-    us = "us",
-    test = "test"
+    intl = "intl"
+}
+export declare enum DrivingServiceMode {
+    /** Driven by SDK directly */
+    sdk = "sdk",
+    /** Driven by host application */
+    host = "host"
+}
+export declare enum LogLevel {
+    /** Disable all logs */
+    off = "off",
+    /** Error logs only */
+    error = "error",
+    /** Warning and error logs */
+    warning = "warning",
+    /** All logs (info, warning, error), default value */
+    all = "all"
+}
+export interface AudioFormat {
+    /** Channel count, fixed to 1 (mono) */
+    readonly channelCount: 1;
+    /** Sample rate, supported: 8000, 16000, 22050, 24000, 32000, 44100, 48000, default: 16000 */
+    readonly sampleRate: number;
 }
 export interface Configuration {
     readonly environment: Environment;
-}
-export interface SdkConfigResponse {
-    endpoints: {
-        cn?: string;
-        us?: string;
-        test?: string;
-    };
+    /** Driving service mode, default is sdk */
+    readonly drivingServiceMode?: DrivingServiceMode;
+    /** Log level, default is off */
+    readonly logLevel?: LogLevel;
+    /** Audio format configuration, default is { channelCount: 1, sampleRate: 16000 } */
+    readonly audioFormat?: AudioFormat;
+    /** Custom character data API base URL (optional, if provided will be used preferentially, otherwise use environment-configured sdkApiBaseUrl) */
+    readonly characterApiBaseUrl?: string;
 }
 export declare enum LoadProgress {
     downloading = "downloading",
@@ -32,22 +54,31 @@ export declare enum ConnectionState {
     connected = "connected",
     failed = "failed"
 }
-export declare enum AvatarState {
-    idle = "idle",// 空闲状态，呈现呼吸态
-    active = "active",// 活跃中，等待可播放内容
-    playing = "playing"
+export declare enum ConversationState {
+    /** Idle state (breathing animation) */
+    idle = "idle",
+    /** Playing state */
+    playing = "playing",
+    /** Pausing state */
+    pausing = "pausing"
 }
-export declare class SPAvatarError extends Error {
-    code?: string | undefined;
-    constructor(message: string, code?: string | undefined);
+export declare enum ErrorCode {
+    /** AppID not recognized (reserved, future appID validation logic) */
+    appIDUnrecognized = "appIDUnrecognized",
+    /** AvatarID not recognized */
+    avatarIDUnrecognized = "avatarIDUnrecognized",
+    /** Session Token invalid */
+    sessionTokenInvalid = "sessionTokenInvalid",
+    /** Session Token expired */
+    sessionTokenExpired = "sessionTokenExpired",
+    /** Failed to fetch avatar metadata */
+    failedToFetchAvatarMetadata = "failedToFetchAvatarMetadata",
+    /** Failed to download avatar assets */
+    failedToDownloadAvatarAssets = "failedToDownloadAvatarAssets"
 }
-export interface FlatSplatData {
-    positions: Float32Array;
-    scales: Float32Array;
-    rotations: Float32Array;
-    colors: Float32Array;
-    opacities: Float32Array;
-    pointCount: number;
+export declare class AvatarError extends Error {
+    code?: (string | ErrorCode) | undefined;
+    constructor(message: string, code?: (string | ErrorCode) | undefined);
 }
 export interface CameraConfig {
     position: [number, number, number];
@@ -58,29 +89,78 @@ export interface CameraConfig {
     up?: [number, number, number];
     aspect?: number;
 }
-export interface RenderPerformanceStats {
-    renderTime: number;
-    sortTime: number;
-    backend: 'webgpu' | 'webgl' | null;
-    pointCount?: number;
-}
 /**
- * 播放模式
+ * Animation keyframe data
+ * Used to represent avatar pose and expression parameters
  */
-export declare enum AvatarPlaybackMode {
-    /** 网络模式：通过 WebSocket 发送音频，接收动画数据 */
-    network = "network",
-    /** 外部数据模式：外部提供音频和动画数据, SDK 负责同步播放 */
-    external = "external"
+export interface KeyframeData {
+    /** Translation [x, y, z] */
+    translation: number[];
+    /** Rotation [x, y, z] (Euler angles, in radians) */
+    rotation: number[];
+    /** Neck pose [x, y, z] (in radians) */
+    neckPose: number[];
+    /** Jaw pose [x, y, z] (in radians) */
+    jawPose: number[];
+    /** Eye pose [x, y, z, x, y, z] (3 parameters for each eye) */
+    eyePose: number[];
+    /** Eyelid [x, y] */
+    eyeLid: number[];
+    /** Expression parameters array */
+    expression: number[];
 }
 /**
- * AvatarView 配置选项
+ * Post-processing parameter configuration
+ * Used to overlay in real-time on animation parameters returned by the server
  */
-export interface AvatarViewOptions {
-    /** 播放模式 */
-    playbackMode?: AvatarPlaybackMode;
-    /** Canvas 容器 */
-    container?: HTMLElement;
+export interface PostProcessingConfig {
+    /** Rotation (Euler angles, in radians) */
+    rotation?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    /** Translation (position offset) */
+    translation?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    /** Neck pose offset (in radians) */
+    neckPose?: {
+        x?: number;
+        y?: number;
+        z?: number;
+        weightX?: number;
+        weightY?: number;
+        weightZ?: number;
+    };
+    /** Jaw pose offset (in radians) */
+    jawPose?: {
+        x?: number;
+        y?: number;
+        z?: number;
+        weight?: number;
+    };
+    /** Eye pose offset (in radians) */
+    eyePose?: {
+        x?: number;
+        y?: number;
+        z?: number;
+        weightX?: number;
+        weightY?: number;
+        weightZ?: number;
+    };
+    /** Eye blink value (-1.0 to 1.0, larger value means more closed) */
+    eyeBlink?: number;
+    /** Expression weight (0.0-2.0, 0=no expression, 1=normal, >1=enhanced) */
+    expressionWeight?: number;
+    /** Eye tracking complete configuration (real-time control of eye_focus, must provide complete configuration) */
+    eyefocus?: {
+        enabled: boolean;
+        auto_eyelid_adjustment?: boolean;
+        eyelid_threshold?: number;
+        targets?: number[];
+    };
 }
 export * from './character';
-//# sourceMappingURL=index.d.ts.map

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

@@ -1,17 +1,6 @@
-import { Flame } from '../generated/driveningress/v1/driveningress';
 /**
- * Linear interpolation with cosine easing (ease-in-ease-out)
- * 0.5 - cos(progress * π) * 0.5
+ * Animation Interpolation Utilities (SDK)
+ * Layered interpolation with different timing for each facial component
+ * Aligned with app implementation and iOS behavior
  */
-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
+export {};

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

@@ -0,0 +1,6 @@
+/**
+ * Client ID management utility
+ * Used to generate and persist unique device identifier
+ * @internal
+ */
+export {};

package/dist/utils/conversationId.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Conversation ID generation utility
+ *
+ * Unified format: timestamp (UTC time, second-level, format: YYYYMMDDHHmmss) + underscore + 12-digit NanoID
+ * Example: 20251027143034_aB3dEf9hIjKl
+ *
+ * Time part uses UTC time for easier cross-platform log troubleshooting with unified timezone conversion
+ * @internal
+ */
+export {};

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

@@ -24,4 +24,3 @@ export declare function errorToMessage(err: unknown): string;
  * @returns Detailed error message with stack if available
  */
 export declare function errorToDetailedMessage(err: unknown): string;
-//# sourceMappingURL=error-utils.d.ts.map