@spatialwalk/avatarkit 1.0.0-beta.10 → 1.0.0-beta.101

package/dist/index.d.ts

@@ -1,11 +1,9 @@
 /**
- * SPAvatar SDK - 统一公开接口
+ * AvatarKit SDK - Unified Public API
  */
 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,19 +1,19 @@
-import { b as o, c as s, a as e, d as t, h as n, g as v, f as A, C as l, E as c, L as g, R as i, S as M, i as d, j as u, k as S } from "./index-bQnEVIkT.js";
+import { b, c, m, f, d, j, g, C, i, D, E, k, h, L, R, n } from "./index-C0A1HA8M.js";
 export {
-  o as Avatar,
-  s as AvatarController,
-  e as AvatarKit,
-  t as AvatarManager,
-  n as AvatarPlaybackMode,
-  v as AvatarState,
-  A as AvatarView,
-  l as ConnectionState,
-  c as Environment,
-  g as LoadProgress,
-  i as ResourceType,
-  M as SPAvatarError,
-  d as extractResourceUrls,
-  u as hasMonologue,
-  S 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

@@ -16,8 +16,14 @@ export interface CameraSettings {
     translationY: number;
     translationZ: number;
 }
+export interface TransformSettings {
+    x: number;
+    y: number;
+    scale: number;
+}
 export interface CharacterSettings {
     eyelid: EyelidSettings;
+    eyefocus?: EyelidSettings;
     camera: CameraSettings;
+    transform?: TransformSettings;
 }
-//# 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,61 @@ 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",
+    /** Session Token invalid (WebSocket close code 4010) */
+    sessionTokenInvalid = "sessionTokenInvalid",
+    /** Session Token expired (WebSocket close code 4010) */
+    sessionTokenExpired = "sessionTokenExpired",
+    /** Insufficient balance (WebSocket close code 4001) */
+    insufficientBalance = "insufficientBalance",
+    /** Concurrent connection limit exceeded (WebSocket close code 4003) */
+    concurrentLimitExceeded = "concurrentLimitExceeded",
+    /** AvatarID not recognized */
+    avatarIDUnrecognized = "avatarIDUnrecognized",
+    /** Failed to fetch avatar metadata */
+    failedToFetchAvatarMetadata = "failedToFetchAvatarMetadata",
+    /** Failed to download avatar assets */
+    failedToDownloadAvatarAssets = "failedToDownloadAvatarAssets",
+    /** WebSocket connection error (handshake failure, network error) */
+    websocketError = "websocketError",
+    /** WebSocket connection closed abnormally (close code 1006) */
+    websocketClosedAbnormally = "websocketClosedAbnormally",
+    /** WebSocket closed with unexpected close code */
+    websocketClosedUnexpected = "websocketClosedUnexpected",
+    /** Session timeout (WebSocket close code 4002) */
+    sessionTimeout = "sessionTimeout",
+    /** Connection already in progress */
+    connectionInProgress = "connectionInProgress",
+    /** Network layer not available (SDK mode required) */
+    networkLayerNotAvailable = "networkLayerNotAvailable",
+    /** Failed to start playback */
+    playbackStartFailed = "playbackStartFailed",
+    /** Playback initialization failed */
+    playbackInitFailed = "playbackInitFailed",
+    /** Audio-only playback initialization failed */
+    audioOnlyInitFailed = "audioOnlyInitFailed",
+    /** No audio data to play */
+    noAudio = "noAudio",
+    /** Audio context not initialized */
+    audioContextNotInitialized = "audioContextNotInitialized",
+    /** Animation player not initialized */
+    animationPlayerNotInitialized = "animationPlayerNotInitialized",
+    /** Server-side error */
+    serverError = "serverError"
+}
+export declare class AvatarError extends Error {
+    code: ErrorCode;
+    constructor(message: string, code: ErrorCode);
 }
 export interface CameraConfig {
     position: [number, number, number];
@@ -58,29 +119,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