@aether-stack-dev/client-sdk 1.2.4 → 1.2.5

package/README.md

@@ -137,6 +137,78 @@ The hook returns:
 
 Pass `autoConnect: true` in options to connect automatically on mount.
 
+The hook also accepts a `character` config for custom avatars (see below).
+
+## Custom Characters
+
+AStack supports custom VRM characters. Any VRM model with ARKit blendshapes will animate with the server's Audio2Face output.
+
+### VRMAvatar Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `blendshapes` | `number[]` | **required** | 52 ARKit blendshape values |
+| `modelUrl` | `string` | `'/models/avatar.vrm'` | URL of the VRM model |
+| `blendshapeMap` | `Record<string, string>` | — | Custom blendshape name mapping (ARKit → model) |
+| `onModelLoad` | `(report: ModelCompatibilityReport) => void` | — | Callback with compatibility report after load |
+| `maxModelSize` | `number` | `31457280` (30MB) | Max model file size in bytes (0 to disable) |
+| `width` | `number` | `400` | Canvas width |
+| `height` | `number` | `400` | Canvas height |
+| `backgroundColor` | `number` | `0x1a1a2e` | Background color |
+
+### Custom Model URL
+
+```typescript
+<VRMAvatar blendshapes={blendshapes} modelUrl="https://cdn.example.com/my-character.vrm" />
+```
+
+### Blendshape Mapping
+
+For models with non-standard blendshape names, provide a mapping from ARKit names to your model's names:
+
+```typescript
+import { VROID_BLENDSHAPE_MAP } from '@aether-stack-dev/client-sdk';
+
+// Use the built-in VRoid Studio preset
+<VRMAvatar blendshapes={blendshapes} blendshapeMap={VROID_BLENDSHAPE_MAP} />
+
+// Or provide a custom mapping
+<VRMAvatar blendshapes={blendshapes} blendshapeMap={{ jawOpen: 'mouth_open', eyeBlinkLeft: 'blink_L' }} />
+```
+
+### Compatibility Report
+
+```typescript
+<VRMAvatar
+  blendshapes={blendshapes}
+  modelUrl="/custom.vrm"
+  onModelLoad={(report) => {
+    console.log(`${report.supported}/52 blendshapes supported`);
+    console.log('Missing:', report.missing);
+    console.log('Warnings:', report.warnings);
+    console.log('Stats:', report.modelStats);
+  }}
+/>
+```
+
+### Hook Character Config
+
+```typescript
+const { blendshapes, characterConfig } = useAStackCSR({
+  workerUrl, sessionToken,
+  character: {
+    modelUrl: 'https://cdn.example.com/my-character.vrm',
+    blendshapeMap: VROID_BLENDSHAPE_MAP,
+    onModelLoad: (report) => console.log(report),
+  },
+});
+
+// Spread characterConfig directly on VRMAvatar
+<VRMAvatar blendshapes={blendshapes} {...characterConfig} />
+```
+
+See the [full character documentation](https://astack.dev/docs/characters) for VRM requirements, ecosystem links, and integration guides.
+
 ## License
 
 MIT

package/dist/avatar/VRMAvatar.d.ts

@@ -1,9 +1,22 @@
+export interface ModelCompatibilityReport {
+    supported: number;
+    missing: string[];
+    warnings: string[];
+    modelStats: {
+        vertexCount: number;
+        textureCount: number;
+        morphTargetCount: number;
+    };
+}
 export interface VRMAvatarProps {
     blendshapes: number[];
     width?: number;
     height?: number;
     modelUrl?: string;
     backgroundColor?: number;
+    blendshapeMap?: Record<string, string>;
+    onModelLoad?: (report: ModelCompatibilityReport) => void;
+    maxModelSize?: number;
 }
-export declare function VRMAvatar({ blendshapes, width, height, modelUrl, backgroundColor }: VRMAvatarProps): import("react/jsx-runtime").JSX.Element;
+export declare function VRMAvatar({ blendshapes, width, height, modelUrl, backgroundColor, blendshapeMap, onModelLoad, maxModelSize, }: VRMAvatarProps): import("react/jsx-runtime").JSX.Element;
 export default VRMAvatar;

package/dist/avatar/constants.d.ts

@@ -1,3 +1,6 @@
 export declare const ARKIT_BLENDSHAPES: readonly ["jawOpen", "jawForward", "jawLeft", "jawRight", "mouthClose", "mouthFunnel", "mouthPucker", "mouthLeft", "mouthRight", "mouthSmileLeft", "mouthSmileRight", "mouthFrownLeft", "mouthFrownRight", "mouthDimpleLeft", "mouthDimpleRight", "mouthStretchLeft", "mouthStretchRight", "mouthRollLower", "mouthRollUpper", "mouthShrugLower", "mouthShrugUpper", "mouthPressLeft", "mouthPressRight", "mouthLowerDownLeft", "mouthLowerDownRight", "mouthUpperUpLeft", "mouthUpperUpRight", "tongueOut", "cheekPuff", "cheekSquintLeft", "cheekSquintRight", "noseSneerLeft", "noseSneerRight", "eyeBlinkLeft", "eyeBlinkRight", "eyeLookDownLeft", "eyeLookDownRight", "eyeLookInLeft", "eyeLookInRight", "eyeLookOutLeft", "eyeLookOutRight", "eyeLookUpLeft", "eyeLookUpRight", "eyeSquintLeft", "eyeSquintRight", "eyeWideLeft", "eyeWideRight", "browDownLeft", "browDownRight", "browInnerUp", "browOuterUpLeft", "browOuterUpRight"];
 export type ARKitBlendshapeName = typeof ARKIT_BLENDSHAPES[number];
 export declare const BLENDSHAPE_COUNT = 52;
+export declare const CRITICAL_BLENDSHAPES: ARKitBlendshapeName[];
+export declare const DEFAULT_BLENDSHAPE_MAP: Record<string, string>;
+export declare const VROID_BLENDSHAPE_MAP: Record<string, string>;

package/dist/avatar/index.d.ts

@@ -1,4 +1,4 @@
 export { VRMAvatar } from './VRMAvatar';
-export type { VRMAvatarProps } from './VRMAvatar';
-export { ARKIT_BLENDSHAPES, BLENDSHAPE_COUNT } from './constants';
+export type { VRMAvatarProps, ModelCompatibilityReport } from './VRMAvatar';
+export { ARKIT_BLENDSHAPES, BLENDSHAPE_COUNT, CRITICAL_BLENDSHAPES, DEFAULT_BLENDSHAPE_MAP, VROID_BLENDSHAPE_MAP, } from './constants';
 export type { ARKitBlendshapeName } from './constants';

package/dist/index.esm.js

@@ -18,6 +18,9 @@ const ARKIT_BLENDSHAPES = [
     'browDownLeft', 'browDownRight', 'browInnerUp', 'browOuterUpLeft', 'browOuterUpRight'
 ];
 const BLENDSHAPE_COUNT = 52;
+const DEFAULT_BLENDSHAPE_MAP = Object.fromEntries(ARKIT_BLENDSHAPES.map(name => [name, name]));
+({
+    ...DEFAULT_BLENDSHAPE_MAP});
 
 const IDX_JAW_OPEN = ARKIT_BLENDSHAPES.indexOf('jawOpen');
 const IDX_MOUTH_FUNNEL = ARKIT_BLENDSHAPES.indexOf('mouthFunnel');

package/dist/index.js

@@ -22,6 +22,9 @@ const ARKIT_BLENDSHAPES = [
     'browDownLeft', 'browDownRight', 'browInnerUp', 'browOuterUpLeft', 'browOuterUpRight'
 ];
 const BLENDSHAPE_COUNT = 52;
+const DEFAULT_BLENDSHAPE_MAP = Object.fromEntries(ARKIT_BLENDSHAPES.map(name => [name, name]));
+({
+    ...DEFAULT_BLENDSHAPE_MAP});
 
 const IDX_JAW_OPEN = ARKIT_BLENDSHAPES.indexOf('jawOpen');
 const IDX_MOUTH_FUNNEL = ARKIT_BLENDSHAPES.indexOf('mouthFunnel');

package/dist/react/index.d.ts

@@ -1,4 +1,4 @@
 export { useAStackCSR } from './useAStackCSR';
-export type { UseAStackCSROptions, UseAStackCSRReturn } from './useAStackCSR';
+export type { UseAStackCSROptions, UseAStackCSRReturn, CharacterConfig } from './useAStackCSR';
 export { VRMAvatar } from '../avatar/VRMAvatar';
-export type { VRMAvatarProps } from '../avatar/VRMAvatar';
+export type { VRMAvatarProps, ModelCompatibilityReport } from '../avatar/VRMAvatar';

package/dist/react/useAStackCSR.d.ts

@@ -1,6 +1,14 @@
 import { AStackCSRClient, AStackCSRConfig, CallStatus } from '../AStackCSRClient';
+import type { ModelCompatibilityReport } from '../avatar/VRMAvatar';
+export interface CharacterConfig {
+    modelUrl?: string;
+    blendshapeMap?: Record<string, string>;
+    onModelLoad?: (report: ModelCompatibilityReport) => void;
+    maxModelSize?: number;
+}
 export interface UseAStackCSROptions extends AStackCSRConfig {
     autoConnect?: boolean;
+    character?: CharacterConfig;
 }
 export interface UseAStackCSRReturn {
     client: AStackCSRClient | null;
@@ -10,6 +18,7 @@ export interface UseAStackCSRReturn {
     transcript: string;
     response: string;
     error: Error | null;
+    characterConfig: CharacterConfig;
     connect: () => Promise<void>;
     disconnect: () => void;
     startCall: () => Promise<void>;

package/dist/react.esm.js

@@ -1,5 +1,5 @@
 'use client';
-import { useState, useRef, useEffect, useCallback } from 'react';
+import { useState, useRef, useEffect, useCallback, useMemo } from 'react';
 import { EventEmitter } from 'eventemitter3';
 import { jsxs, jsx } from 'react/jsx-runtime';
 import * as THREE from 'three';
@@ -24,6 +24,12 @@ const ARKIT_BLENDSHAPES = [
     'browDownLeft', 'browDownRight', 'browInnerUp', 'browOuterUpLeft', 'browOuterUpRight'
 ];
 const BLENDSHAPE_COUNT = 52;
+const CRITICAL_BLENDSHAPES = [
+    'jawOpen', 'eyeBlinkLeft', 'eyeBlinkRight',
+];
+const DEFAULT_BLENDSHAPE_MAP = Object.fromEntries(ARKIT_BLENDSHAPES.map(name => [name, name]));
+({
+    ...DEFAULT_BLENDSHAPE_MAP});
 
 const IDX_JAW_OPEN = ARKIT_BLENDSHAPES.indexOf('jawOpen');
 const IDX_MOUTH_FUNNEL = ARKIT_BLENDSHAPES.indexOf('mouthFunnel');
@@ -768,6 +774,12 @@ function useAStackCSR(options) {
             clientRef.current.sendText(message);
         }
     }, []);
+    const characterConfig = useMemo(() => ({
+        ...(options.character?.modelUrl && { modelUrl: options.character.modelUrl }),
+        ...(options.character?.blendshapeMap && { blendshapeMap: options.character.blendshapeMap }),
+        ...(options.character?.onModelLoad && { onModelLoad: options.character.onModelLoad }),
+        ...(options.character?.maxModelSize !== undefined && { maxModelSize: options.character.maxModelSize }),
+    }), [options.character?.modelUrl, options.character?.blendshapeMap, options.character?.onModelLoad, options.character?.maxModelSize]);
     return {
         client: clientRef.current,
         isConnected,
@@ -776,6 +788,7 @@ function useAStackCSR(options) {
         transcript,
         response,
         error,
+        characterConfig,
         connect,
         disconnect,
         startCall,
@@ -784,7 +797,67 @@ function useAStackCSR(options) {
     };
 }
 
-function VRMAvatar({ blendshapes, width = 400, height = 400, modelUrl = '/models/avatar.vrm', backgroundColor = 0x1a1a2e }) {
+const DEFAULT_MAX_MODEL_SIZE = 30 * 1024 * 1024; // 30MB
+const HIGH_VERTEX_THRESHOLD = 100000;
+function buildCompatibilityReport(vrm) {
+    const foundNames = new Set();
+    let vertexCount = 0;
+    let textureCount = 0;
+    let morphTargetCount = 0;
+    vrm.scene.traverse((obj) => {
+        if (obj.isMesh) {
+            const mesh = obj;
+            const geo = mesh.geometry;
+            if (geo)
+                vertexCount += geo.attributes.position?.count || 0;
+            const material = mesh.material;
+            const materials = Array.isArray(material) ? material : [material];
+            for (const mat of materials) {
+                if (mat && 'map' in mat && mat.map)
+                    textureCount++;
+            }
+            const morphDict = mesh.morphTargetDictionary;
+            if (morphDict) {
+                morphTargetCount += Object.keys(morphDict).length;
+                for (const name of Object.keys(morphDict)) {
+                    foundNames.add(name);
+                    foundNames.add(name.toLowerCase());
+                }
+            }
+        }
+    });
+    if (vrm.expressionManager) {
+        for (const exp of vrm.expressionManager.expressions) {
+            foundNames.add(exp.expressionName);
+        }
+    }
+    const supported = [];
+    const missing = [];
+    for (const name of ARKIT_BLENDSHAPES) {
+        if (foundNames.has(name) || foundNames.has(name.toLowerCase())) {
+            supported.push(name);
+        }
+        else {
+            missing.push(name);
+        }
+    }
+    const warnings = [];
+    for (const name of CRITICAL_BLENDSHAPES) {
+        if (missing.includes(name)) {
+            warnings.push(`Missing critical blendshape: ${name}`);
+        }
+    }
+    if (vertexCount > HIGH_VERTEX_THRESHOLD) {
+        warnings.push(`High vertex count (${vertexCount.toLocaleString()}) may impact performance`);
+    }
+    return {
+        supported: supported.length,
+        missing,
+        warnings,
+        modelStats: { vertexCount, textureCount, morphTargetCount },
+    };
+}
+function VRMAvatar({ blendshapes, width = 400, height = 400, modelUrl = '/models/avatar.vrm', backgroundColor = 0x1a1a2e, blendshapeMap, onModelLoad, maxModelSize = DEFAULT_MAX_MODEL_SIZE, }) {
     const containerRef = useRef(null);
     const rendererRef = useRef(null);
     const sceneRef = useRef(null);
@@ -831,7 +904,8 @@ function VRMAvatar({ blendshapes, width = 400, height = 400, modelUrl = '/models
                 const morphInfluences = mesh.morphTargetInfluences;
                 if (morphDict && morphInfluences) {
                     ARKIT_BLENDSHAPES.forEach((name, i) => {
-                        const idx = morphDict[name] ?? morphDict[name.toLowerCase()];
+                        const mapped = blendshapeMap?.[name] ?? name;
+                        const idx = morphDict[mapped] ?? morphDict[mapped.toLowerCase()];
                         if (idx !== undefined) {
                             morphInfluences[idx] = shapes[i] || 0;
                         }
@@ -839,7 +913,7 @@ function VRMAvatar({ blendshapes, width = 400, height = 400, modelUrl = '/models
                 }
             }
         });
-    }, []);
+    }, [blendshapeMap]);
     useEffect(() => {
         const container = containerRef.current;
         if (!container)
@@ -877,18 +951,53 @@ function VRMAvatar({ blendshapes, width = 400, height = 400, modelUrl = '/models
         const backLight = new THREE.DirectionalLight(0x4a9eff, 0.3);
         backLight.position.set(-1, 1, -1);
         scene.add(backLight);
+        let cancelled = false;
+        // Size guard: fire HEAD check in parallel — if model is too large, cancel before render
+        if (maxModelSize > 0) {
+            fetch(modelUrl, { method: 'HEAD' }).then(res => {
+                if (cancelled)
+                    return;
+                const contentLength = res.headers.get('content-length');
+                if (contentLength && parseInt(contentLength, 10) > maxModelSize) {
+                    cancelled = true;
+                    const sizeMB = (parseInt(contentLength, 10) / 1024 / 1024).toFixed(1);
+                    const limitMB = (maxModelSize / 1024 / 1024).toFixed(0);
+                    const errMsg = `Model too large (${sizeMB}MB, limit ${limitMB}MB)`;
+                    setError(errMsg);
+                    setLoading(false);
+                    onModelLoad?.({
+                        supported: 0, missing: [...ARKIT_BLENDSHAPES], warnings: [errMsg],
+                        modelStats: { vertexCount: 0, textureCount: 0, morphTargetCount: 0 },
+                    });
+                }
+            }).catch(() => { });
+        }
         const loader = new GLTFLoader();
         loader.register((parser) => new VRMLoaderPlugin(parser));
         loader.load(modelUrl, (gltf) => {
+            if (cancelled)
+                return;
             const vrm = gltf.userData.vrm;
             if (vrm) {
                 scene.add(vrm.scene);
                 vrmRef.current = vrm;
                 setLoading(false);
+                const report = buildCompatibilityReport(vrm);
+                if (report.warnings.length > 0) {
+                    console.warn('[VRM] Compatibility warnings:', report.warnings);
+                }
+                onModelLoad?.(report);
             }
         }, () => { }, (err) => {
-            console.error('[VRM] Error loading model:', err);
-            setError('Failed to load VRM model');
+            if (cancelled)
+                return;
+            const message = err instanceof Error ? err.message : String(err);
+            const detail = message.includes('404') ? `Model not found: ${modelUrl}`
+                : message.includes('NetworkError') || message.includes('Failed to fetch')
+                    ? `Network error loading model: ${modelUrl}`
+                    : `Failed to load VRM model: ${message}`;
+            console.error('[VRM] Error loading model:', detail);
+            setError(detail);
             setLoading(false);
         });
         const clock = new THREE.Clock();
@@ -949,13 +1058,14 @@ function VRMAvatar({ blendshapes, width = 400, height = 400, modelUrl = '/models
         };
         animate();
         return () => {
+            cancelled = true;
             cancelAnimationFrame(animationFrameRef.current);
             renderer.dispose();
             if (container && renderer.domElement) {
                 container.removeChild(renderer.domElement);
             }
         };
-    }, [width, height, modelUrl, backgroundColor]);
+    }, [width, height, modelUrl, backgroundColor, maxModelSize, onModelLoad]);
     useEffect(() => {
         if (vrmRef.current && blendshapes.length > 0) {
             applyBlendshapes(vrmRef.current, blendshapes);

package/dist/react.js

@@ -45,6 +45,12 @@ const ARKIT_BLENDSHAPES = [
     'browDownLeft', 'browDownRight', 'browInnerUp', 'browOuterUpLeft', 'browOuterUpRight'
 ];
 const BLENDSHAPE_COUNT = 52;
+const CRITICAL_BLENDSHAPES = [
+    'jawOpen', 'eyeBlinkLeft', 'eyeBlinkRight',
+];
+const DEFAULT_BLENDSHAPE_MAP = Object.fromEntries(ARKIT_BLENDSHAPES.map(name => [name, name]));
+({
+    ...DEFAULT_BLENDSHAPE_MAP});
 
 const IDX_JAW_OPEN = ARKIT_BLENDSHAPES.indexOf('jawOpen');
 const IDX_MOUTH_FUNNEL = ARKIT_BLENDSHAPES.indexOf('mouthFunnel');
@@ -789,6 +795,12 @@ function useAStackCSR(options) {
             clientRef.current.sendText(message);
         }
     }, []);
+    const characterConfig = react.useMemo(() => ({
+        ...(options.character?.modelUrl && { modelUrl: options.character.modelUrl }),
+        ...(options.character?.blendshapeMap && { blendshapeMap: options.character.blendshapeMap }),
+        ...(options.character?.onModelLoad && { onModelLoad: options.character.onModelLoad }),
+        ...(options.character?.maxModelSize !== undefined && { maxModelSize: options.character.maxModelSize }),
+    }), [options.character?.modelUrl, options.character?.blendshapeMap, options.character?.onModelLoad, options.character?.maxModelSize]);
     return {
         client: clientRef.current,
         isConnected,
@@ -797,6 +809,7 @@ function useAStackCSR(options) {
         transcript,
         response,
         error,
+        characterConfig,
         connect,
         disconnect,
         startCall,
@@ -805,7 +818,67 @@ function useAStackCSR(options) {
     };
 }
 
-function VRMAvatar({ blendshapes, width = 400, height = 400, modelUrl = '/models/avatar.vrm', backgroundColor = 0x1a1a2e }) {
+const DEFAULT_MAX_MODEL_SIZE = 30 * 1024 * 1024; // 30MB
+const HIGH_VERTEX_THRESHOLD = 100000;
+function buildCompatibilityReport(vrm) {
+    const foundNames = new Set();
+    let vertexCount = 0;
+    let textureCount = 0;
+    let morphTargetCount = 0;
+    vrm.scene.traverse((obj) => {
+        if (obj.isMesh) {
+            const mesh = obj;
+            const geo = mesh.geometry;
+            if (geo)
+                vertexCount += geo.attributes.position?.count || 0;
+            const material = mesh.material;
+            const materials = Array.isArray(material) ? material : [material];
+            for (const mat of materials) {
+                if (mat && 'map' in mat && mat.map)
+                    textureCount++;
+            }
+            const morphDict = mesh.morphTargetDictionary;
+            if (morphDict) {
+                morphTargetCount += Object.keys(morphDict).length;
+                for (const name of Object.keys(morphDict)) {
+                    foundNames.add(name);
+                    foundNames.add(name.toLowerCase());
+                }
+            }
+        }
+    });
+    if (vrm.expressionManager) {
+        for (const exp of vrm.expressionManager.expressions) {
+            foundNames.add(exp.expressionName);
+        }
+    }
+    const supported = [];
+    const missing = [];
+    for (const name of ARKIT_BLENDSHAPES) {
+        if (foundNames.has(name) || foundNames.has(name.toLowerCase())) {
+            supported.push(name);
+        }
+        else {
+            missing.push(name);
+        }
+    }
+    const warnings = [];
+    for (const name of CRITICAL_BLENDSHAPES) {
+        if (missing.includes(name)) {
+            warnings.push(`Missing critical blendshape: ${name}`);
+        }
+    }
+    if (vertexCount > HIGH_VERTEX_THRESHOLD) {
+        warnings.push(`High vertex count (${vertexCount.toLocaleString()}) may impact performance`);
+    }
+    return {
+        supported: supported.length,
+        missing,
+        warnings,
+        modelStats: { vertexCount, textureCount, morphTargetCount },
+    };
+}
+function VRMAvatar({ blendshapes, width = 400, height = 400, modelUrl = '/models/avatar.vrm', backgroundColor = 0x1a1a2e, blendshapeMap, onModelLoad, maxModelSize = DEFAULT_MAX_MODEL_SIZE, }) {
     const containerRef = react.useRef(null);
     const rendererRef = react.useRef(null);
     const sceneRef = react.useRef(null);
@@ -852,7 +925,8 @@ function VRMAvatar({ blendshapes, width = 400, height = 400, modelUrl = '/models
                 const morphInfluences = mesh.morphTargetInfluences;
                 if (morphDict && morphInfluences) {
                     ARKIT_BLENDSHAPES.forEach((name, i) => {
-                        const idx = morphDict[name] ?? morphDict[name.toLowerCase()];
+                        const mapped = blendshapeMap?.[name] ?? name;
+                        const idx = morphDict[mapped] ?? morphDict[mapped.toLowerCase()];
                         if (idx !== undefined) {
                             morphInfluences[idx] = shapes[i] || 0;
                         }
@@ -860,7 +934,7 @@ function VRMAvatar({ blendshapes, width = 400, height = 400, modelUrl = '/models
                 }
             }
         });
-    }, []);
+    }, [blendshapeMap]);
     react.useEffect(() => {
         const container = containerRef.current;
         if (!container)
@@ -898,18 +972,53 @@ function VRMAvatar({ blendshapes, width = 400, height = 400, modelUrl = '/models
         const backLight = new THREE__namespace.DirectionalLight(0x4a9eff, 0.3);
         backLight.position.set(-1, 1, -1);
         scene.add(backLight);
+        let cancelled = false;
+        // Size guard: fire HEAD check in parallel — if model is too large, cancel before render
+        if (maxModelSize > 0) {
+            fetch(modelUrl, { method: 'HEAD' }).then(res => {
+                if (cancelled)
+                    return;
+                const contentLength = res.headers.get('content-length');
+                if (contentLength && parseInt(contentLength, 10) > maxModelSize) {
+                    cancelled = true;
+                    const sizeMB = (parseInt(contentLength, 10) / 1024 / 1024).toFixed(1);
+                    const limitMB = (maxModelSize / 1024 / 1024).toFixed(0);
+                    const errMsg = `Model too large (${sizeMB}MB, limit ${limitMB}MB)`;
+                    setError(errMsg);
+                    setLoading(false);
+                    onModelLoad?.({
+                        supported: 0, missing: [...ARKIT_BLENDSHAPES], warnings: [errMsg],
+                        modelStats: { vertexCount: 0, textureCount: 0, morphTargetCount: 0 },
+                    });
+                }
+            }).catch(() => { });
+        }
         const loader = new GLTFLoader_js.GLTFLoader();
         loader.register((parser) => new threeVrm.VRMLoaderPlugin(parser));
         loader.load(modelUrl, (gltf) => {
+            if (cancelled)
+                return;
             const vrm = gltf.userData.vrm;
             if (vrm) {
                 scene.add(vrm.scene);
                 vrmRef.current = vrm;
                 setLoading(false);
+                const report = buildCompatibilityReport(vrm);
+                if (report.warnings.length > 0) {
+                    console.warn('[VRM] Compatibility warnings:', report.warnings);
+                }
+                onModelLoad?.(report);
             }
         }, () => { }, (err) => {
-            console.error('[VRM] Error loading model:', err);
-            setError('Failed to load VRM model');
+            if (cancelled)
+                return;
+            const message = err instanceof Error ? err.message : String(err);
+            const detail = message.includes('404') ? `Model not found: ${modelUrl}`
+                : message.includes('NetworkError') || message.includes('Failed to fetch')
+                    ? `Network error loading model: ${modelUrl}`
+                    : `Failed to load VRM model: ${message}`;
+            console.error('[VRM] Error loading model:', detail);
+            setError(detail);
             setLoading(false);
         });
         const clock = new THREE__namespace.Clock();
@@ -970,13 +1079,14 @@ function VRMAvatar({ blendshapes, width = 400, height = 400, modelUrl = '/models
         };
         animate();
         return () => {
+            cancelled = true;
             cancelAnimationFrame(animationFrameRef.current);
             renderer.dispose();
             if (container && renderer.domElement) {
                 container.removeChild(renderer.domElement);
             }
         };
-    }, [width, height, modelUrl, backgroundColor]);
+    }, [width, height, modelUrl, backgroundColor, maxModelSize, onModelLoad]);
     react.useEffect(() => {
         if (vrmRef.current && blendshapes.length > 0) {
             applyBlendshapes(vrmRef.current, blendshapes);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aether-stack-dev/client-sdk",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "type": "module",
   "description": "JavaScript/TypeScript SDK for AStack video-to-video AI conversations",
   "main": "dist/index.js",