@spatialwalk/avatarkit 1.0.0-beta.9 → 1.0.0-beta.91

package/dist/index.d.ts

@@ -1,12 +1,9 @@
 /**
- * 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-8jCKHF1q.js";
+import { b, c, m, f, d, j, g, C, i, D, E, k, h, L, R, n } from "./index-BYr_FIpm.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/next.d.ts

@@ -0,0 +1,2 @@
+export declare function withAvatarkit(nextConfig?: any): any;
+export default withAvatarkit;

package/dist/performance/FrameRateMonitor.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Per-frame render timing — Web platform.
+ * Aligned with Android FrameRenderInfo / iOS FrameRenderInfo.
+ */
+export interface FrameRenderInfo {
+    /** Frame start timestamp (performance.now ms). */
+    startTimeMs: number;
+    /** Frame end timestamp (performance.now ms). */
+    endTimeMs: number;
+    /** Sort stage time (ms). */
+    sortTimeMs: number;
+    /** GPU render time (ms). */
+    renderTimeMs: number;
+    /** Reorder time (ms, WebGL path only; 0 for WebGPU). */
+    reorderTimeMs: number;
+    /** CPU render-submit time (ms, loadSplats + render call). */
+    renderSubmitTimeMs: number;
+    /** Production frame serial (incremented on actual render). */
+    frameSerial: number;
+    /** Presentation frame serial (incremented on display submit). */
+    presentFrameSerial: number;
+    /** Idle time: gap between previous frame end and this frame start (ms). */
+    idleTimeMs: number;
+}
+/**
+ * Frame rate monitoring info — unified public API across platforms.
+ * Contains pre-computed high-level performance metrics.
+ */
+export interface FrameRateInfo {
+    /** Production FPS (actual frames rendered per second). */
+    fps: number;
+    /** Presentation FPS (display refresh rate including reused frames). */
+    presentationFps: number;
+    /** 95th percentile frame interval (ms). */
+    frameIntervalP95Ms: number;
+    /** 99th percentile frame interval (ms). */
+    frameIntervalP99Ms: number;
+    /** Percentage of frames with interval > 50ms (jank ratio). */
+    jankRatioPercent: number;
+    /** Average total frame time (ms). */
+    averageFrameTimeMs: number;
+    /** Estimated CPU busy ratio (%). Browser approximation based on frame active time vs interval. */
+    cpuUsagePercent: number;
+    /** Per-frame details within the sliding window (aligned with Android/iOS). */
+    frames: FrameRenderInfo[];
+}
+export interface PlaybackStats {
+    avgFps: number;
+    frameCount: number;
+    durationMs: number;
+    /** Percentage of frame intervals > 50ms */
+    jankRatio: number;
+    /** Coefficient of variation of frame intervals (stddev / mean) */
+    fpsCv: number;
+}
+/**
+ * Frame rate monitor with 2-second sliding window.
+ * Aligned with Android/iOS FrameRateMonitor.
+ *
+ * @example
+ * ```ts
+ * controller.frameRateMonitorEnabled = true
+ * controller.onFrameRateInfo = (info) => {
+ *   console.log('FPS:', info.fps, 'Jank:', info.jankRatioPercent)
+ * }
+ * ```
+ */
+export declare class FrameRateMonitor {
+    enabled: boolean;
+    onFrameRateInfo: ((info: FrameRateInfo) => void) | null;
+    private lwFrameCount;
+    private lwStartTimeMs;
+    private lwLastEndTimeMs;
+    private lwJankCount;
+    private lwSumInterval;
+    private lwSumIntervalSq;
+    /** Reset the lightweight counter. Call at playback start. */
+    resetPlaybackStats(): void;
+    /** Get lightweight playback stats. Call at playback end. */
+    getPlaybackStats(): PlaybackStats;
+    private frames;
+    private computeFrameRateInfo;
+    private percentileInterval;
+    private jankRatio;
+}

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,45 @@
-import { CharacterAsset } from '../generated/driveningress/v2/driveningress';
 import { CameraSettings, CharacterSettings } from './character-settings';
+export interface Resource {
+    type: string;
+    local: string;
+    remote: string;
+}
+export interface ResourceHolder {
+    resource?: Resource;
+    /** Compressed model resource (~30% of original size, with minor quality degradation). */
+    xrResource?: Resource;
+}
+export interface Models {
+    shape?: ResourceHolder;
+    gsStandard?: ResourceHolder;
+    gsHigh?: ResourceHolder;
+    gsUltra?: ResourceHolder;
+}
+export interface Animations {
+    frameIdle?: ResourceHolder;
+    frameMono?: ResourceHolder;
+    audioMono?: ResourceHolder;
+}
+export interface CustomAnimation {
+    key: string;
+    pbUrl: string;
+    wavUrl: string;
+    remark: string;
+}
+export interface CharacterAsset {
+    characterId: string;
+    version: string;
+    camera?: ResourceHolder;
+    models?: Models;
+    animations?: Animations;
+    background?: ResourceHolder;
+    characterSettings?: {
+        [key: string]: any;
+    };
+    customAnimations: CustomAnimation[];
+}
 /**
- * 角色元数据
+ * Character metadata
  */
 export type CharacterMeta = CharacterAsset & {
     characterSettings?: CharacterSettings;
@@ -13,27 +51,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 class SPAvatarError extends Error {
-    code?: string | undefined;
-    constructor(message: string, code?: string | undefined);
-}
-export interface FlatSplatData {
-    positions: Float32Array;
-    scales: Float32Array;
-    rotations: Float32Array;
-    colors: Float32Array;
-    opacities: Float32Array;
-    pointCount: number;
+export declare enum ConversationState {
+    /** Idle state (breathing animation) */
+    idle = "idle",
+    /** Playing state */
+    playing = "playing",
+    /** Paused state */
+    paused = "paused"
+}
+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 {
+    code?: (string | ErrorCode) | undefined;
+    constructor(message: string, code?: (string | ErrorCode) | undefined);
 }
 export interface CameraConfig {
     position: [number, number, number];
@@ -58,29 +89,88 @@ 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 interface FlameInfo {
+    vertexCount: number;
+    faceCount: number;
+    jointCount: number;
+}
+export interface CharacterInfo {
+    pointCount: number;
+    hasAnimation: boolean;
 }
 export * from './character';
-//# sourceMappingURL=index.d.ts.map
+export type { FrameRateInfo, FrameRenderInfo } from '../performance/FrameRateMonitor';

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/next.d.ts

@@ -0,0 +1,3 @@
+export declare function withAvatarkit(nextConfig?: any): any;
+export default withAvatarkit;
+//# sourceMappingURL=next.d.ts.map

package/next.js

@@ -0,0 +1,187 @@
+/**
+ * Next.js plugin for @spatialwalk/avatarkit
+ * Handles WASM file configuration for both webpack and Turbopack (Next.js 15+/16+)
+ *
+ * Usage:
+ *   import { withAvatarkit } from '@spatialwalk/avatarkit/next'
+ *   export default withAvatarkit({ ...your next config... })
+ */
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { writeFileSync, readFileSync, readdirSync, mkdirSync, copyFileSync, existsSync, } from 'fs';
+// ── Locate SDK directory ──────────────────────────────────────────────
+// Walk up from this file (inside the SDK package) to find the package root.
+// This is reliable regardless of process.cwd(), monorepos, or hoisted deps.
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Since this file IS inside the SDK package (at package root), __dirname is the SDK dir.
+const sdkDir = __dirname;
+const sdkDistDir = join(sdkDir, 'dist');
+// ── Embedded webpack loader ───────────────────────────────────────────
+// Fixes Emscripten's scriptDirectory: bundlers replace import.meta.url with
+// a build-time path that browsers can't use to locate WASM files.
+// This loader replaces it with the correct public path.
+function createLoaderCode(wasmPublicPath) {
+    return `module.exports = function(source) {
+  // Strategy 1: Replace assignment only (simpler, more robust)
+  var pattern1 = /scriptDirectory\\s*=\\s*new\\s+URL\\(\\s*"\\."\\s*,\\s*_scriptName\\s*\\)\\.href\\s*;/;
+  var result = source.replace(pattern1, 'scriptDirectory = "${wasmPublicPath}";');
+  if (result !== source) return result;
+
+  // Strategy 2: Full try/catch block (handles different catch syntax)
+  var pattern2 = /try\\s*\\{\\s*scriptDirectory\\s*=\\s*new\\s+URL\\(\\s*"\\."\\s*,\\s*_scriptName\\s*\\)\\.href\\s*;?\\s*\\}\\s*catch\\s*(\\([^)]*\\))?\\s*\\{\\s*\\}/;
+  result = source.replace(pattern2, 'scriptDirectory = "${wasmPublicPath}";');
+  if (result !== source) return result;
+
+  console.warn('[avatarkit] WARNING: scriptDirectory pattern not matched in', this.resourcePath);
+  return source;
+}
+`;
+}
+function ensureLoader(wasmPublicPath) {
+    const cacheDir = join(sdkDir, '.cache');
+    const loaderPath = join(cacheDir, 'wasm-script-dir-loader.cjs');
+    mkdirSync(cacheDir, { recursive: true });
+    writeFileSync(loaderPath, createLoaderCode(wasmPublicPath));
+    return loaderPath;
+}
+// ── Copy WASM files to public directory ───────────────────────────────
+// Works for both webpack and Turbopack: public/ files are served by Next.js
+function copyWasmToPublic(projectDir) {
+    const publicWasmDir = join(projectDir, 'public', '_avatarkit');
+    mkdirSync(publicWasmDir, { recursive: true });
+    try {
+        const files = readdirSync(sdkDistDir);
+        for (const file of files) {
+            if (file.startsWith('avatar_core_wasm') && file.endsWith('.wasm')) {
+                const src = join(sdkDistDir, file);
+                const dest = join(publicWasmDir, file);
+                copyFileSync(src, dest);
+            }
+        }
+    }
+    catch (err) {
+        console.warn('[avatarkit] Failed to copy WASM files:', err.message);
+        console.warn('[avatarkit] SDK dist dir:', sdkDistDir);
+    }
+}
+// ── Webpack plugin: copy WASM to build output ─────────────────────────
+// Emits WASM files into .next/static/chunks/ during webpack compilation.
+// This is needed in addition to public/ for standalone Docker deployments
+// where .next/static/ is copied but public/ may not be.
+class CopyWasmPlugin {
+    apply(compiler) {
+        compiler.hooks.thisCompilation.tap('AvatarkitCopyWasm', (compilation) => {
+            compilation.hooks.processAssets.tap({
+                name: 'AvatarkitCopyWasm',
+                stage: compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_ADDITIONAL,
+            }, () => {
+                try {
+                    const files = readdirSync(sdkDistDir);
+                    for (const file of files) {
+                        if (file.startsWith('avatar_core_wasm') && file.endsWith('.wasm')) {
+                            const content = readFileSync(join(sdkDistDir, file));
+                            compilation.emitAsset(`static/chunks/${file}`, new compiler.webpack.sources.RawSource(content));
+                        }
+                    }
+                }
+                catch (err) {
+                    console.warn('[avatarkit] CopyWasmPlugin error:', err.message);
+                }
+            });
+        });
+    }
+}
+// ── Detect project root from next.config location ─────────────────────
+// next.config.mjs is always at the project root. Since this module is imported
+// from next.config.mjs, we find the project root by walking up from import.meta.url
+// of the calling module. However, we can't access the caller's import.meta.url,
+// so we search for the nearest next.config.* file from the SDK location upwards.
+function findProjectRoot() {
+    let dir = process.cwd(); // fallback, but also check for next.config
+    const configNames = [
+        'next.config.mjs',
+        'next.config.js',
+        'next.config.ts',
+        'next.config.cjs',
+    ];
+    // Verify cwd has a next.config file
+    for (const name of configNames) {
+        if (existsSync(join(dir, name))) {
+            return dir;
+        }
+    }
+    // Fallback: search from SDK location upward
+    let searchDir = sdkDir;
+    while (searchDir !== dirname(searchDir)) {
+        for (const name of configNames) {
+            if (existsSync(join(searchDir, name))) {
+                return searchDir;
+            }
+        }
+        searchDir = dirname(searchDir);
+    }
+    return process.cwd();
+}
+// ── Main plugin ───────────────────────────────────────────────────────
+export function withAvatarkit(nextConfig = {}) {
+    const basePath = nextConfig.basePath || '';
+    const wasmPublicPath = `${basePath}/_avatarkit/`;
+    const loaderPath = ensureLoader(wasmPublicPath);
+    const projectRoot = findProjectRoot();
+    // Copy WASM files to public/_avatarkit/ (works for both webpack & Turbopack)
+    copyWasmToPublic(projectRoot);
+    return {
+        ...nextConfig,
+        // ── Turbopack configuration (Next.js 15+/16+) ──
+        turbopack: {
+            ...nextConfig.turbopack,
+            rules: {
+                ...nextConfig.turbopack?.rules,
+                '**/avatar_core_wasm*.js': {
+                    loaders: [loaderPath],
+                    as: '*.js',
+                },
+            },
+        },
+        // ── Webpack configuration ──
+        webpack: (config, context) => {
+            // 1. Fix: Next.js sets module.generator.asset.filename which breaks asset/inline
+            if (config.module.generator?.asset?.filename) {
+                const filename = config.module.generator.asset.filename;
+                delete config.module.generator.asset.filename;
+                config.module.generator['asset/resource'] = {
+                    ...config.module.generator['asset/resource'],
+                    filename,
+                };
+            }
+            // 2. Fix: Emscripten scriptDirectory derived from import.meta.url
+            config.module.rules.push({
+                test: /avatar_core_wasm.*\.js$/,
+                enforce: 'pre',
+                use: [{ loader: loaderPath }],
+            });
+            // 3. Copy WASM files to static/chunks/ (client build only, for standalone)
+            if (!context.isServer) {
+                config.plugins.push(new CopyWasmPlugin());
+            }
+            // Chain with user's webpack config
+            if (typeof nextConfig.webpack === 'function') {
+                return nextConfig.webpack(config, context);
+            }
+            return config;
+        },
+        // ── Headers: ensure WASM content-type ──
+        async headers() {
+            const userHeaders = typeof nextConfig.headers === 'function' ? await nextConfig.headers() : [];
+            return [
+                ...userHeaders,
+                {
+                    source: '/_avatarkit/:path*.wasm',
+                    headers: [{ key: 'Content-Type', value: 'application/wasm' }],
+                },
+            ];
+        },
+    };
+}
+export default withAvatarkit;