@spatialwalk/avatarkit 1.0.0-beta.68 → 1.0.0-beta.69

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+/**
+ *AvatarKit SDK - 统一公开接口
+ */
 export { Avatar } from './core/Avatar';
 export { AvatarController } from './core/AvatarController';
 export { AvatarSDK } from './core/AvatarSDK';

package/dist/index.js

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

package/dist/renderer/RenderSystem.d.ts

@@ -1 +1,9 @@
+/**
+ * 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 +1,12 @@
+/**
+ * 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[][];

package/dist/renderer/sortSplats.d.ts

@@ -1 +1,11 @@
+/**
+ * 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;

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

@@ -1 +1,13 @@
+/**
+ * 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;

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

@@ -24,20 +24,73 @@ export declare class WebGLRenderer implements I3DGSRenderer {
     private blitVAO;
     constructor(canvas: HTMLCanvasElement, backgroundColor?: [number, number, number, number], alpha?: boolean);
     private alpha;
+    /**
+     * 初始化 WebGL 渲染器
+     */
     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], 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;
 }

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

@@ -26,16 +26,54 @@ export declare class WebGPURenderer implements I3DGSRenderer {
     private blitQuadBuffer;
     private blitSampler;
     constructor(canvas: HTMLCanvasElement, backgroundColor?: [number, number, number, number], alpha?: boolean);
+    /**
+     * 初始化 WebGPU 渲染器
+     */
     initialize(): Promise<void>;
+    /**
+     * 创建 Uniform Buffer
+     */
     private createUniformBuffer;
+    /**
+     * 创建四边形顶点缓冲区（实例化渲染用）
+     */
     private createQuadVertexBuffer;
+    /**
+     * 创建 Render Pipeline
+     */
     private createRenderPipeline;
+    /**
+     * 创建 Blit Pipeline（用于绘制 render texture 到屏幕）
+     */
     private createBlitPipeline;
+    /**
+     * 创建 render texture 和 depth texture
+     */
     private createRenderTexture;
+    /**
+     * 从已打包数据加载
+     * 🚀 间接索引渲染：packedData 是原始数据，sortOrder 是排序索引
+     * 🚀 完全消除 CPU 重排序开销
+     */
     loadSplatsFromPackedData(packedData: Float32Array, pointCount: number, sortOrder?: Uint32Array): 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;
 }

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

@@ -1,3 +1,7 @@
+/**
+ * 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;

package/dist/types/character.d.ts

@@ -1,6 +1,8 @@
 import { CharacterAsset } from '../generated/driveningress/v2/driveningress';
 import { CameraSettings, CharacterSettings } from './character-settings';
-
+/**
+ * 角色元数据
+ */
 export type CharacterMeta = CharacterAsset & {
     characterSettings?: CharacterSettings;
 };
@@ -10,12 +12,16 @@ export type PreloadResources<T> = {
 export type PreloadCameraSettings = PreloadResources<{
     camera: CameraSettings;
 }>;
-
+/**
+ * 资源类型枚举
+ */
 export declare enum ResourceType {
     CAMERA = "camera",
     ANIMATION_IDLE = "frameIdle",
     MODEL_SHAPE = "shape",
     MODEL_GS = "gsStandard"
 }
-
+/**
+ * 提取所有资源 URL
+ */
 export declare function extractResourceUrls(meta: CharacterMeta): Record<ResourceType, string | null>;

package/dist/types/index.d.ts

@@ -1,41 +1,43 @@
+/**
+ * Unified public types & interfaces
+ */
 export declare enum Environment {
     cn = "cn",
     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;
+    /** 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 interface SdkConfigResponse {
-    endpoints: {
-        cn?: string;
-        intl?: string;
-        us?: string;
-    };
-}
 export declare enum LoadProgress {
     downloading = "downloading",
     completed = "completed",
@@ -53,25 +55,25 @@ export declare enum ConnectionState {
     failed = "failed"
 }
 export declare enum ConversationState {
-
+    /** Idle state (breathing animation) */
     idle = "idle",
-
+    /** Playing state */
     playing = "playing",
-
+    /** Pausing state */
     pausing = "pausing"
 }
 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 declare class AvatarError extends Error {
@@ -95,18 +97,44 @@ export interface CameraConfig {
     up?: [number, number, number];
     aspect?: number;
 }
-
+/**
+ * Animation keyframe data
+ * Used to represent avatar pose and expression parameters
+ */
+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[];
+}
+/**
+ * Post-processing parameter configuration
+ * Used to overlay in real-time on animation parameters returned by the server
+ */
 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;
@@ -115,12 +143,14 @@ export interface PostProcessingConfig {
         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;
@@ -129,8 +159,11 @@ export interface PostProcessingConfig {
         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;

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

@@ -1,11 +1,36 @@
 import { Flame } from '../generated/driveningress/v1/driveningress';
-
+/**
+ * 线性插值（旧实现）
+ * @param from 起始 Flame
+ * @param to 目标 Flame
+ * @param progress 进度 (0-1)
+ */
 export declare function linearLerp(from: Flame, to: Flame, progress: number): Flame;
-
+/**
+ * 使用线性插值生成过渡帧（旧实现，保留用于兼容）
+ * @param from 起始 Flame
+ * @param to 目标 Flame
+ * @param durationMs 总过渡时长 (e.g. 400ms)
+ * @param fps Frames per second (default 25)
+ */
 export declare function generateTransitionFramesLinear(from: Flame, to: Flame, durationMs: number, fps?: number): Flame[];
-
+/**
+ * Bezier 曲线插值（使用不同部位的不同曲线和时间缩放）
+ * @param from 起始 Flame
+ * @param to 目标 Flame
+ * @param progress 全局进度 (0-1)
+ */
 export declare function bezierLerp(from: Flame, to: Flame, progress: number): Flame;
-
+/**
+ * Generate transition keyframes between two Flame states with layered timing
+ * Different facial components transition at different speeds and timings
+ * @param from 起始 Flame
+ * @param to 目标 Flame
+ * @param durationMs 总过渡时长 (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;

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

@@ -1 +1,6 @@
+/**
+ * Client ID 管理工具
+ * 用于生成和持久化用户设备唯一标识
+ * @internal
+ */
 export {};

package/dist/utils/conversationId.d.ts

@@ -1 +1,19 @@
+/**
+ * Conversation ID 生成工具
+ *
+ * 统一格式：时间戳（UTC时间，秒级，格式：YYYYMMDDHHmmss）+ 下划线 + 12位 NanoID
+ * 示例：20251027143034_aB3dEf9hIjKl
+ *
+ * 时间部分使用 UTC 时间，便于跨端日志排查时统一转换时区检索
+ */
+/**
+ * 生成统一的会话 ID
+ *
+ * 格式：时间戳（UTC时间，秒级，格式：YYYYMMDDHHmmss）+ 下划线 + 12位 NanoID
+ * 时间部分使用 UTC 时间，便于跨端日志排查时统一转换时区检索
+ *
+ * @returns 格式为 YYYYMMDDHHmmss_nanoid 的会话 ID
+ * @example
+ * generateConversationId() // "20251027143034_aB3dEf9hIjKl"
+ */
 export declare function generateConversationId(): string;

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

@@ -1,3 +1,26 @@
+/**
+ * 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;

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

@@ -1,3 +1,11 @@
+/**
+ * ID 管理器
+ * 统一管理 SDK 中所有类型的 ID
+ * @internal
+ */
+/**
+ * ID 类型定义
+ */
 export interface SdkIds {
     clientId: string;
     userId: string | null;
@@ -16,15 +24,30 @@ declare class IdManager {
     getAppId(): string | null;
     setSessionToken(token: string | null): void;
     getSessionToken(): string | null;
+    /**
+     * 生成新的 connectionId（用于 WebSocket 连接）
+     */
     generateConnectionId(): string;
+    /**
+     * 设置 connectionId（用于从服务器接收到的 connectionId）
+     */
     setConnectionId(connectionId: string | null): void;
     getConnectionId(): string | null;
     clearConnectionId(): void;
+    /**
+     * 生成新的 conversationId（用于每次对话）
+     */
     generateNewConversationId(): string;
     getConversationId(): string | null;
     setConversationId(conversationId: string | null): void;
     clearConversationId(): void;
+    /**
+     * 获取所有 ID（用于日志上报）
+     */
     getAllIds(): Readonly<SdkIds>;
+    /**
+     * 获取公共日志参数（包含所有必要的 ID）
+     */
     getLogContext(): {
         client_id: string;
         user_id: string;
@@ -32,6 +55,9 @@ declare class IdManager {
         connection_id?: string;
         conversation_id?: string;
     };
+    /**
+     * 清理所有 ID（用于测试或重置）
+     */
     clear(): void;
 }
 export declare const idManager: IdManager;

package/dist/utils/logger.d.ts

@@ -1,7 +1,10 @@
 import { LogLevel as GuiiaiLogLevel } from '@guiiai/logg';
 import { LogLevel } from '../types';
 export declare const logger: import('@guiiai/logg').Logg;
-
+/**
+ * 设置 SDK 日志等级
+ * @param level SDK 的 LogLevel 枚举值
+ */
 export declare function setLogLevel(level: LogLevel): void;
 export declare const loggerWithUnknown: {
     error: (message: string, error?: unknown) => void;

package/dist/utils/posthog-tracker.d.ts

@@ -1,11 +1,33 @@
 import { Environment } from '../types';
-
+/**
+ * 初始化 PostHog（需要传入环境信息和 SDK 版本）
+ */
 export declare function initializePostHog(environment: Environment, version: string): void;
-
+/**
+ * 上报事件到 PostHog
+ * @param event 事件名称
+ * @param level 日志级别
+ * @param contents 事件内容
+ */
 export declare function trackEvent(event: string, level?: 'debug' | 'info' | 'warning' | 'error', contents?: Record<string, unknown>): void;
-
+/**
+ * 使用 sendBeacon 同步发送关键事件（用于页面关闭时）
+ * PostHog 本身支持在页面关闭时自动发送，但我们可以手动触发
+ * @param event 事件名称
+ * @param level 日志级别
+ * @param contents 事件内容
+ * @returns 是否发送成功
+ */
 export declare function sendEventViaBeacon(event: string, level?: 'debug' | 'info' | 'warning' | 'error', contents?: Record<string, unknown>): boolean;
-
+/**
+ * 清理 PostHog（刷新剩余事件）
+ */
 export declare function cleanupPostHog(): void;
-
+/**
+ * 统一的 Telemetry 日志接口
+ * 用于 SDK 内部上报日志到 PostHog
+ * @param event 事件名称
+ * @param level 日志级别
+ * @param contents 日志内容
+ */
 export declare function logEvent(event: string, level?: 'debug' | 'info' | 'warning' | 'error', contents?: Record<string, unknown>): void;

package/dist/utils/pwa-cache-manager.d.ts

@@ -1,3 +1,12 @@
+/**
+ * PWA Cache Manager
+ * Manages Service Worker Cache for character resources and template resources
+ * @internal
+ */
+/**
+ * PWA Cache Manager
+ * Manages character resources cache (per character) and template resources cache (versioned)
+ */
 export declare class PwaCacheManager {
     private static readonly TEMPLATE_RESOURCE_VERSION;
     private static readonly TEMPLATE_CACHE_NAME;
@@ -5,12 +14,39 @@ export declare class PwaCacheManager {
     private static readonly CHARACTER_CACHE_PREFIX;
     private static readonly CHARACTER_CACHE_SUFFIX;
     private static readonly MAX_CHARACTER_CACHE_ENTRIES;
+    /**
+     * 检查是否支持 Cache API
+     */
     static isSupported(): boolean;
+    /**
+     * 获取角色缓存名称
+     */
     private static getCharacterCacheName;
+    /**
+     * 从角色缓存获取资源
+     */
     static getCharacterResource(characterId: string, url: string): Promise<ArrayBuffer | null>;
+    /**
+     * 将角色资源写入缓存
+     */
     static putCharacterResource(characterId: string, url: string, data: ArrayBuffer): Promise<void>;
+    /**
+     * 从模板缓存获取资源
+     */
     static getTemplateResource(url: string): Promise<ArrayBuffer | null>;
+    /**
+     * 将模板资源写入缓存
+     * 模板资源不设置数量限制，永久保留直到版本更新
+     */
     static putTemplateResource(url: string, data: ArrayBuffer): Promise<void>;
+    /**
+     * 清理角色缓存
+     */
     static clearCharacterCache(characterId: string): Promise<void>;
+    /**
+     * 检查模板缓存版本，如果版本变化则清理
+     * 使用独立的模板资源版本号（不依赖 SDK 版本），这样不同 SDK 版本可以共享相同模板资源的缓存
+     * @returns true 如果版本变化并清理了缓存，false 否则
+     */
     static checkTemplateCacheVersion(): Promise<boolean>;
 }

package/dist/utils/usage-tracker.d.ts

@@ -1,5 +1,20 @@
+/**
+ * 使用情况追踪工具
+ * 用于判断首次使用、每日活跃等状态
+ * @internal
+ */
+/**
+ * 检查是否为首次使用
+ * @returns true 如果是首次使用，false 如果不是
+ */
 export declare function isFirstUse(): boolean;
-
+/**
+ * 检查今天是否已经活跃过
+ * @returns true 如果今天首次活跃，false 如果今天已经活跃过
+ */
 export declare function isDailyActive(): boolean;
-
+/**
+ * 获取最后活跃日期
+ * @returns 最后活跃日期（YYYY-MM-DD），如果不存在则返回 null
+ */
 export declare function getLastActiveDate(): string | null;