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

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

@@ -0,0 +1,34 @@
+/**
+ * ID Manager
+ * Unified management of all types of IDs in SDK
+ * @internal
+ */
+/**
+ * ID type definitions
+ */
+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;
+    getConnectionId(): string | null;
+    clearConnectionId(): void;
+    getConversationId(): string | null;
+    setConversationId(conversationId: string | null): void;
+    clearConversationId(): void;
+}
+export declare const idManager: IdManager;
+export {};

package/dist/utils/logger.d.ts

@@ -1,12 +1,4 @@
-/**
- * Logger Utility
- * Environment-aware logger wrapper
- * - Logs normally in test/dev environment
- * - In production: silently logs to console
- * - Errors and warnings are always reported to CLS (when enabled)
- *
- * Usage: Replace `console.log()` with `logger.log()`
- */
+import { LogLevel as GuiiaiLogLevel } from '@guiiai/logg';
 export declare const logger: import('@guiiai/logg').Logg;
 export declare const loggerWithUnknown: {
     error: (message: string, error?: unknown) => void;
@@ -14,7 +6,7 @@ export declare const loggerWithUnknown: {
     useGlobalConfig: () => import('@guiiai/logg').Logg;
     child: (fields?: Record<string, any>) => import('@guiiai/logg').Logg;
     withContext: (context: string) => import('@guiiai/logg').Logg;
-    withLogLevel: (logLevel: import('@guiiai/logg').LogLevel) => import('@guiiai/logg').Logg;
+    withLogLevel: (logLevel: GuiiaiLogLevel) => import('@guiiai/logg').Logg;
     withLogLevelString: (logLevelString: import('@guiiai/logg').LogLevelString) => import('@guiiai/logg').Logg;
     withFormat: (format: import('@guiiai/logg').Format) => import('@guiiai/logg').Logg;
     withFields: (fields: Record<string, any>) => import('@guiiai/logg').Logg;
@@ -32,4 +24,3 @@ export declare const loggerWithUnknown: {
     withTimeFormatter: (fn: (inputDate: Date) => string) => import('@guiiai/logg').Logg;
     withErrorProcessor: (fn: (err: Error | unknown) => Error | unknown) => import('@guiiai/logg').Logg;
 };
-//# sourceMappingURL=logger.d.ts.map

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

@@ -0,0 +1,8 @@
+/**
+ * PostHog Telemetry Tool (Browser Version)
+ *
+ * Unified PostHog telemetry reporting, supports custom reporting
+ * Uses PostHog JS SDK for event tracking, suitable for browser environments
+ * @internal
+ */
+export {};

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

@@ -0,0 +1,17 @@
+/**
+ * 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;
+    private static readonly TEMPLATE_VERSION_STORAGE_KEY;
+    private static readonly CHARACTER_CACHE_PREFIX;
+    private static readonly CHARACTER_CACHE_SUFFIX;
+    private static readonly MAX_CHARACTER_CACHE_ENTRIES;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Usage tracking utility
+ * Used to determine first use, daily active status, etc.
+ * @internal
+ */
+export {};

package/dist/vanilla/vite.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/vite.d.ts

@@ -0,0 +1,19 @@
+import { Plugin } from 'vite';
+/**
+ * Vite plugin for @spatialwalk/avatarkit
+ * Automatically handles WASM file configuration for development and production builds
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'vite'
+ * import { avatarkitVitePlugin } from '@spatialwalk/avatarkit/vite'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     avatarkitVitePlugin()
+ *   ]
+ * })
+ * ```
+ */
+export declare function avatarkitVitePlugin(): Plugin;
+export default avatarkitVitePlugin;

package/dist/wasm/avatarCoreAdapter.d.ts

@@ -1,4 +1,10 @@
-import { AvatarCoreMemoryManager } from './avatarCoreMemory';
+/**
+ * Avatar Core WASM Adapter
+ *
+ * Completely replaces FlameComplete3DGSManager, provides full functionality of avatar_core_wasm
+ * Includes advanced features such as teeth subdivision, eye tracking, etc.
+ * @internal
+ */
 export interface WasmModuleConfig {
     baseUrl?: string;
     [key: string]: unknown;
@@ -13,13 +19,6 @@ export interface AvatarCoreOptions {
     wasmConfig?: WasmModuleConfig;
     wasmPath?: string;
 }
-interface PerformanceMetrics {
-    initTime: number;
-    loadTime: number;
-    computeFrames: number;
-    totalComputeTime: number;
-    averageComputeTime: number;
-}
 export interface FlameInfo {
     vertexCount: number;
     faceCount: number;
@@ -46,6 +45,8 @@ export declare class AvatarCoreAdapter {
     private wasmModule;
     private memoryManager;
     private coreHandle;
+    private characterHandles;
+    private animationHandles;
     private characterHandle;
     private animationHandle;
     private totalFrames;
@@ -58,131 +59,19 @@ export declare class AvatarCoreAdapter {
     private flameInfo?;
     private characterInfo?;
     constructor(options?: AvatarCoreOptions);
-    /**
-     * 加载 WASM 模块并设置 API
-     * 每次都创建全新的 WASM 实例，确保 C++ 内存是干净的
-     *
-     * 注意：这里使用动态 import() 导入 WASM 模块。
-     * Vite 在构建时会自动为 WASM 文件和 JS glue 代码添加 hash（如 avatar_core_wasm-CxWuw7eS.wasm），
-     * 确保浏览器缓存与版本一致，不会有缓存问题。
-     *
-     * Hash 的作用机制：
-     * - WASM 文件内容变化 → hash 自动变化 → URL 变化 → 浏览器拉取新版本
-     * - WASM 文件内容不变 → hash 保持不变 → URL 不变 → 浏览器使用缓存
-     * - Emscripten 生成的 JS 内部会使用 hard-coded 的 hash 路径加载 .wasm 文件
-     */
-    loadWASMModule(): Promise<void>;
-    /**
-     * 验证 WASM 模块功能
-     */
-    private validateWASMModule;
-    /**
-     * 初始化内存视图
-     */
-    private initializeMemoryViews;
-    /**
-     * 设置 C API 函数包装
-     */
-    private setupCAPIFunctions;
-    /**
-     * 读取当前动画帧的 FlameParams（用于过渡或调试）
-     */
-    getCurrentFrameParams(frameIndex?: number): Promise<FlameParams>;
-    /**
-     * 初始化 Avatar Core 核心
-     */
-    private initializeAvatarCore;
-    /**
-     * 加载模板资源（从预加载的 ArrayBuffers）
-     */
-    loadTemplateResourcesFromBuffers(templateResources: Record<string, ArrayBuffer>): Promise<boolean>;
-    /**
-     * 加载角色数据（从预加载的 ArrayBuffers）
-     */
-    loadCharacterFromBuffers(shapeBuffer: ArrayBuffer, pointCloudBuffer: ArrayBuffer): Promise<boolean>;
     private loadAnimationFromData;
     /**
      * Load animation from ArrayBuffer (for CDN-based dynamic loading)
+     * @param animData Animation data buffer
+     * @param characterId Optional character ID for multi-character support
+     * @returns Animation handle
      */
-    loadAnimationFromBuffer(animData: ArrayBuffer): Promise<number>;
+    loadAnimationFromBuffer(animData: ArrayBuffer, characterId?: string): Promise<number>;
     switchAnimationFile(animationFile: string): Promise<number>;
     /**
-     * 获取动画总帧数
-     */
-    getAnimationTotalFrames(): Promise<number>;
-    /**
-     * 从动画中获取指定帧的参数
-     */
-    getAnimationFrameParams(frameIndex?: number): Promise<number>;
-    /**
-     * 设置眼部追踪配置（对齐 app 实现）
-     */
-    setEyeTrackingConfig(config: {
-        enabled: boolean;
-        auto_eyelid_adjustment?: boolean;
-        eyelid_threshold?: number;
-    }): Promise<boolean>;
-    /**
-     * 设置眼部追踪目标（高级功能）
-     */
-    setGazeTarget(x: number, y: number, z: number): Promise<boolean>;
-    /**
-     * 重置眼部追踪
-     */
-    resetEyeTracking(): Promise<boolean>;
-    /**
-     * 查询 FLAME 模型信息
-     */
-    private queryFlameInfo;
-    /**
-     * 查询角色信息
-     */
-    private queryCharacterInfo;
-    /**
-     * 检查错误码并抛出异常
-     */
-    private checkError;
-    /**
-     * 更新进度回调
-     */
-    private updateProgress;
-    /**
-     * 获取性能指标
-     */
-    getPerformanceMetrics(): PerformanceMetrics & {
-        memoryStats?: ReturnType<AvatarCoreMemoryManager['getMemoryStats']>;
-        flameInfo?: FlameInfo;
-        characterInfo?: CharacterInfo;
-        version?: string;
-    };
-    /**
-     * 释放当前角色和动画资源（但保留 core）
+     * Release current character (legacy method, kept for backward compatibility)
+     * @deprecated Use removeCharacter() instead for multi-character support
      */
     releaseCurrentCharacter(): void;
-    /**
-     * 释放所有资源（包括 core）
-     */
-    release(): void;
-    /**
-     * 兼容性接口：提供与 FlameComplete3DGSManager 相同的接口
-     */
-    loadFlameModel(_modelData: any): Promise<boolean>;
     load3DGSData(_original3DGSPoints: any, _binding: any, _flameFaces: any): Promise<boolean>;
-    /**
-     * 计算帧并返回 GPU 友好的 flat 格式（零拷贝，协方差预计算）
-     * 🚀 性能优化版本：
-     * - C++ 预计算协方差矩阵
-     * - 零拷贝直接访问 WASM 内存http://localhost:3000/us/
-     * - 直接输出 GPU 格式 [pos3, color4, cov6]
-     */
-    computeCompleteFrameFlat(params?: {
-        frameIndex?: number;
-    }): Promise<Float32Array | null>;
-    /**
-     * 计算帧并返回 GPU 友好的 flat 格式（从 FLAME 参数）
-     * 🔑 用于 Realtime: 接受自定义 FLAME 参数并计算 Splat
-     */
-    computeFrameFlatFromParams(flameParams: FlameParams): Promise<Float32Array | null>;
 }
-export {};
-//# sourceMappingURL=avatarCoreAdapter.d.ts.map

package/dist/wasm/avatarCoreMemory.d.ts

@@ -58,7 +58,11 @@ export declare class AvatarCoreMemoryManager {
     /**
      * 创建 AvatarCharacterData 结构体 - 新版 Emscripten 方式
      */
-    createCharacterData(shapeBuffer: ArrayBuffer, plyBuffer: ArrayBuffer): number;
+    createCharacterData(shapeBuffer: ArrayBuffer, plyBuffer: ArrayBuffer, characterId?: string): {
+        dataPtr: number;
+        shapePtr: number;
+        plyPtr: number;
+    };
     /**
      * 读取 AvatarFlameParams 结构体数据
      * Used to extract current animation frame parameters from WASM memory
@@ -138,4 +142,3 @@ export declare class AvatarCoreMemoryManager {
     };
 }
 export {};
-//# sourceMappingURL=avatarCoreMemory.d.ts.map

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@spatialwalk/avatarkit",
   "type": "module",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.71",
   "packageManager": "pnpm@10.18.2",
-  "description": "SPAvatar SDK - 3D Gaussian Splatting Avatar Rendering SDK",
-  "author": "SPAvatar Team",
+  "description": "AvatarKit SDK - 3D Gaussian Splatting Avatar Rendering SDK",
+  "author": "AvatarKit Team",
   "license": "MIT",
   "keywords": [
     "avatar",
@@ -19,6 +19,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./vite": {
+      "types": "./vite.d.ts",
+      "import": "./vite.js"
+    },
     "./*": {
       "types": "./dist/*.d.ts",
       "import": "./dist/*.js"
@@ -30,28 +34,35 @@
   "files": [
     "README.md",
     "CHANGELOG.md",
-    "dist"
+    "dist",
+    "vite.js",
+    "vite.d.ts"
   ],
   "scripts": {
-    "build": "SDK_BUILD=true vite build --mode library",
+    "build": "SDK_BUILD=true vite build --mode library && npm run build:vite-plugin",
+    "build:vite-plugin": "tsc vite.ts --outDir . --module esnext --target es2020 --moduleResolution bundler --esModuleInterop --skipLibCheck --declaration --declarationMap",
     "dev": "vite build --mode library --watch",
     "clean": "rm -rf dist",
     "typecheck": "tsc --noEmit",
     "test": "cd tests && pnpm test",
     "test:watch": "cd tests && pnpm run test:watch",
-    "test:e2e": "cd tests && pnpm run test:e2e"
+    "test:e2e": "cd tests && pnpm run test:e2e",
+    "test:perf": "cd tests && pnpm run test:perf"
   },
   "peerDependencies": {
-    "@webgpu/types": "*"
+    "@webgpu/types": "*",
+    "vite": "^5.0.0"
   },
   "dependencies": {
     "@bufbuild/protobuf": "^2.10.0",
     "@guiiai/logg": "^1.2.4",
-    "nanoid": "^5.1.6"
+    "nanoid": "^5.1.6",
+    "posthog-js": "^1.310.1"
   },
   "devDependencies": {
     "@types/node": "^20.11.30",
     "@webgpu/types": "^0.1.65",
+    "tsx": "^4.20.6",
     "typescript": "^5.0.0",
     "vite": "^5.0.0",
     "vite-plugin-dts": "^4.5.4"

package/vite.d.ts

@@ -0,0 +1,20 @@
+import type { Plugin } from 'vite';
+/**
+ * Vite plugin for @spatialwalk/avatarkit
+ * Automatically handles WASM file configuration for development and production builds
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'vite'
+ * import { avatarkitVitePlugin } from '@spatialwalk/avatarkit/vite'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     avatarkitVitePlugin()
+ *   ]
+ * })
+ * ```
+ */
+export declare function avatarkitVitePlugin(): Plugin;
+export default avatarkitVitePlugin;
+//# sourceMappingURL=vite.d.ts.map

package/vite.js

@@ -0,0 +1,126 @@
+import { copyFileSync, existsSync, writeFileSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Vite plugin for @spatialwalk/avatarkit
+ * Automatically handles WASM file configuration for development and production builds
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'vite'
+ * import { avatarkitVitePlugin } from '@spatialwalk/avatarkit/vite'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     avatarkitVitePlugin()
+ *   ]
+ * })
+ * ```
+ */
+export function avatarkitVitePlugin() {
+    let rootDir;
+    return {
+        name: 'avatarkit-wasm',
+        // 保存项目根目录
+        configResolved(config) {
+            rootDir = config.root;
+        },
+        // 开发服务器 MIME 类型配置
+        configureServer(server) {
+            server.middlewares.use((req, res, next) => {
+                if (req.url?.endsWith('.wasm')) {
+                    res.setHeader('Content-Type', 'application/wasm');
+                }
+                next();
+            });
+        },
+        // 构建时自动复制 WASM 文件和生成 headers
+        closeBundle() {
+            if (!rootDir)
+                return;
+            const wasmSourceDir = join(rootDir, 'node_modules/@spatialwalk/avatarkit/dist');
+            // 先查找并读取 JS glue 文件，提取它引用的 WASM 文件名
+            let wasmFileName = null;
+            if (existsSync(wasmSourceDir)) {
+                const files = readdirSync(wasmSourceDir);
+                const wasmJsFile = files.find((f) => f.startsWith('avatar_core_wasm') && f.endsWith('.js'));
+                if (wasmJsFile) {
+                    const wasmJsSource = join(wasmSourceDir, wasmJsFile);
+                    try {
+                        const jsContent = readFileSync(wasmJsSource, 'utf-8');
+                        // 从 JS 文件中提取 WASM 文件名
+                        // 匹配 avatar_core_wasm-{hash}.wasm 或 avatar_core_wasm.wasm
+                        // 使用更精确的正则，匹配带引号或不带引号的情况
+                        const wasmMatch = jsContent.match(/["'`]?avatar_core_wasm[-\w]*\.wasm["'`]?/g);
+                        if (wasmMatch && wasmMatch.length > 0) {
+                            // 取第一个匹配，去掉引号
+                            wasmFileName = wasmMatch[0].replace(/["'`]/g, '');
+                        }
+                    }
+                    catch (error) {
+                        console.warn('⚠️ [avatarkit] Could not read JS glue file:', error);
+                    }
+                }
+            }
+            // 如果从 JS 文件中找到了 WASM 文件名，使用它；否则回退到默认名称
+            const targetWasmName = wasmFileName || 'avatar_core_wasm.wasm';
+            const wasmSource = join(wasmSourceDir, targetWasmName);
+            const wasmDest = join(rootDir, `dist/assets/${targetWasmName}`);
+            const wasmJsDest = join(rootDir, 'dist/assets/avatar_core_wasm.js');
+            const headersDest = join(rootDir, 'dist/_headers');
+            // 复制 WASM 文件
+            if (existsSync(wasmSource)) {
+                copyFileSync(wasmSource, wasmDest);
+                console.log(`✅ [avatarkit] Copied WASM file to dist/assets/${targetWasmName}`);
+            }
+            else {
+                console.warn(`⚠️ [avatarkit] WASM file not found: ${wasmSource}`);
+                if (wasmFileName) {
+                    console.warn(`   Expected file: ${targetWasmName} (extracted from JS glue file)`);
+                }
+            }
+            // 复制 WASM JS glue 文件
+            if (existsSync(wasmSourceDir)) {
+                const files = readdirSync(wasmSourceDir);
+                const wasmJsFile = files.find((f) => f.startsWith('avatar_core_wasm') && f.endsWith('.js'));
+                if (wasmJsFile) {
+                    const wasmJsSource = join(wasmSourceDir, wasmJsFile);
+                    copyFileSync(wasmJsSource, wasmJsDest);
+                    console.log(`✅ [avatarkit] Copied WASM JS file to dist/assets/avatar_core_wasm.js (from ${wasmJsFile})`);
+                }
+                else {
+                    console.log('ℹ️ [avatarkit] WASM JS file not found (may be handled by Vite):', wasmSourceDir);
+                }
+            }
+            // 生成 _headers 文件（用于 Cloudflare Pages 等平台）
+            const headersContent = '/*.wasm\n  Content-Type: application/wasm\n';
+            writeFileSync(headersDest, headersContent);
+            console.log('✅ [avatarkit] Created _headers file for Cloudflare Pages');
+        },
+        // 自动配置 Vite 选项
+        config() {
+            return {
+                optimizeDeps: {
+                    exclude: ['@spatialwalk/avatarkit']
+                },
+                assetsInclude: ['**/*.wasm'],
+                build: {
+                    assetsInlineLimit: 0, // 确保 WASM 文件不被内联
+                    rollupOptions: {
+                        output: {
+                            assetFileNames: (assetInfo) => {
+                                // WASM 文件使用固定名称
+                                if (assetInfo.name?.endsWith('.wasm')) {
+                                    return 'assets/[name][extname]';
+                                }
+                                // 其他资源使用 hash
+                                return 'assets/[name]-[hash][extname]';
+                            }
+                        }
+                    }
+                }
+            };
+        }
+    };
+}
+// 默认导出
+export default avatarkitVitePlugin;