@spatius/avatarkit 1.3.1-beta.2 → 1.3.1-beta.4

package/dist/assets/AvatarDownloader-C-CiIH1p.js

@@ -0,0 +1,753 @@
+import { _ as recordHttpClientDuration, c as logEvent, dt as isDebugMode, l as logMetric, mt as AvatarError, pt as generateTraceId, t as logger, vt as ErrorCode } from "./logger-B-X9jUON.js";
+import { t as AvatarSDK } from "./AvatarSDK-RVj90oMR.js";
+//#region config/app-config.ts
+const GLOBAL_FLAME_CDN_BASE = "https://cdn.spatialwalk.cloud/public";
+const CN_FLAME_CDN_BASE = "https://cdn.spatialwalk.top/public";
+function getFlameCdnBase(region) {
+	return region.startsWith("cn-") ? CN_FLAME_CDN_BASE : GLOBAL_FLAME_CDN_BASE;
+}
+const APP_CONFIG = {
+	testEnv: false,
+	get debug() {
+		return isDebugMode();
+	},
+	rendering: { 
+	/**
+	* Sort mode
+	* - 'balance': Performance first, sort first frame then reuse (default)
+	* - 'quality': Quality first, re-sort every frame
+	*/
+sortMode: "balance" },
+	camera: {
+		position: [
+			-.02,
+			-.013,
+			1.5
+		],
+		target: [
+			0,
+			0,
+			0
+		],
+		fov: 22,
+		near: .01,
+		far: 100
+	},
+	animation: { fps: 25 },
+	audio: { sampleRate: 16e3 },
+	avatar: {
+		baseAssetsPath: "",
+		wasmPath: "./wasm/avatar_core_wasm.js"
+	},
+	flame: {
+		cdnBase: GLOBAL_FLAME_CDN_BASE,
+		unifiedModelPath: "unified_model_body.pb.gz"
+	},
+	wasm: {
+		logLevel: "basic",
+		enableValidation: false,
+		enablePerformanceMetrics: true
+	}
+};
+//#endregion
+//#region utils/error-utils.ts
+/**
+* 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)
+* }
+*/
+function errorToMessage(err) {
+	if (err instanceof Error) return err.message;
+	if (typeof err === "string") return err;
+	if (typeof err === "object" && err !== null) {
+		if ("message" in err && typeof err.message === "string") return err.message;
+		try {
+			return JSON.stringify(err);
+		} catch {
+			return String(err);
+		}
+	}
+	return String(err);
+}
+//#endregion
+//#region utils/pwa-cache-manager.ts
+/**
+* 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)
+*/
+var PwaCacheManager = class PwaCacheManager {
+	static TEMPLATE_RESOURCE_VERSION = "1.0.0";
+	static TEMPLATE_CACHE_NAME = `spatius-sdk-template-cache-${PwaCacheManager.TEMPLATE_RESOURCE_VERSION}`;
+	static TEMPLATE_VERSION_STORAGE_KEY = "spatius-sdk-template-cache-version";
+	static CHARACTER_CACHE_PREFIX = "spatius-sdk-character-";
+	static CHARACTER_CACHE_SUFFIX = "-cache";
+	static MAX_CHARACTER_CACHE_ENTRIES = 1e3;
+	/**
+	* Check if Cache API is supported
+	* @internal
+	*/
+	static isSupported() {
+		return typeof caches !== "undefined";
+	}
+	/**
+	* Get character cache name
+	* @internal
+	*/
+	static getCharacterCacheName(characterId) {
+		return `${PwaCacheManager.CHARACTER_CACHE_PREFIX}${characterId}${PwaCacheManager.CHARACTER_CACHE_SUFFIX}`;
+	}
+	/**
+	* Get character resource from cache
+	* @internal
+	*/
+	static async getCharacterResource(characterId, url) {
+		if (!PwaCacheManager.isSupported()) return null;
+		try {
+			const cacheName = PwaCacheManager.getCharacterCacheName(characterId);
+			const response = await (await caches.open(cacheName)).match(url);
+			if (response) {
+				const arrayBuffer = await response.arrayBuffer();
+				logger.log(`[PwaCacheManager] Character resource cache hit: ${url}`);
+				return arrayBuffer;
+			}
+			return null;
+		} catch (error) {
+			logger.warn(`[PwaCacheManager] Failed to get character resource from cache:`, error);
+			return null;
+		}
+	}
+	/**
+	* Put character resource into cache
+	* @internal
+	*/
+	static async putCharacterResource(characterId, url, data) {
+		if (!PwaCacheManager.isSupported()) return;
+		try {
+			const cacheName = PwaCacheManager.getCharacterCacheName(characterId);
+			const cache = await caches.open(cacheName);
+			const keys = await cache.keys();
+			if (keys.length >= PwaCacheManager.MAX_CHARACTER_CACHE_ENTRIES) {
+				const oldestKey = keys[0];
+				await cache.delete(oldestKey);
+				logger.log(`[PwaCacheManager] Character cache full, deleted oldest entry: ${oldestKey.url}`);
+			}
+			await cache.put(url, new Response(data));
+			logger.log(`[PwaCacheManager] Character resource cached: ${url}`);
+		} catch (error) {
+			logger.warn(`[PwaCacheManager] Failed to put character resource to cache:`, error);
+		}
+	}
+	/**
+	* Get template resource from cache
+	* @internal
+	*/
+	static async getTemplateResource(url) {
+		if (!PwaCacheManager.isSupported()) return null;
+		try {
+			const response = await (await caches.open(PwaCacheManager.TEMPLATE_CACHE_NAME)).match(url);
+			if (response) {
+				const arrayBuffer = await response.arrayBuffer();
+				logger.log(`[PwaCacheManager] Template resource cache hit: ${url}`);
+				return arrayBuffer;
+			}
+			return null;
+		} catch (error) {
+			logger.warn(`[PwaCacheManager] Failed to get template resource from cache:`, error);
+			return null;
+		}
+	}
+	/**
+	* Put template resource into cache
+	* Template resources have no quantity limit, permanently retained until version update
+	* @internal
+	*/
+	static async putTemplateResource(url, data) {
+		if (!PwaCacheManager.isSupported()) return;
+		try {
+			await (await caches.open(PwaCacheManager.TEMPLATE_CACHE_NAME)).put(url, new Response(data));
+			logger.log(`[PwaCacheManager] Template resource cached: ${url}`);
+		} catch (error) {
+			logger.warn(`[PwaCacheManager] Failed to put template resource to cache:`, error);
+		}
+	}
+	/**
+	* Clear character cache
+	* @internal
+	*/
+	static async clearCharacterCache(characterId) {
+		if (!PwaCacheManager.isSupported()) return;
+		try {
+			const cacheName = PwaCacheManager.getCharacterCacheName(characterId);
+			await caches.delete(cacheName);
+			logger.log(`[PwaCacheManager] Character cache cleared: ${characterId}`);
+		} catch (error) {
+			logger.warn(`[PwaCacheManager] Failed to clear character cache:`, error);
+		}
+	}
+	/**
+	* Check template cache version, clear cache if version changed
+	* Uses independent template resource version (not dependent on SDK version), allowing different SDK versions to share the same template resource cache
+	* @returns true if version changed and cache was cleared, false otherwise
+	* @internal
+	*/
+	static async checkTemplateCacheVersion() {
+		if (!PwaCacheManager.isSupported()) return false;
+		try {
+			const currentTemplateVersion = PwaCacheManager.TEMPLATE_RESOURCE_VERSION;
+			const storedVersion = localStorage.getItem(PwaCacheManager.TEMPLATE_VERSION_STORAGE_KEY);
+			if (storedVersion !== currentTemplateVersion) {
+				if (storedVersion) {
+					const oldCacheName = `spatius-sdk-template-cache-${storedVersion}`;
+					await caches.delete(oldCacheName).catch(() => {});
+				}
+				localStorage.setItem(PwaCacheManager.TEMPLATE_VERSION_STORAGE_KEY, currentTemplateVersion);
+				logger.log(`[PwaCacheManager] Template cache version changed: ${storedVersion} -> ${currentTemplateVersion}, old cache cleared`);
+				return true;
+			}
+			return false;
+		} catch (error) {
+			logger.warn(`[PwaCacheManager] Failed to check template cache version:`, error);
+			return false;
+		}
+	}
+};
+//#endregion
+//#region core/AvatarDownloader.ts
+/**
+* Get cache information for a resource
+* Detects browser cache, CDN cache, and PWA (Service Worker) cache
+*/
+function getCacheInfo(url, response) {
+	const resourceTiming = performance.getEntriesByName(url, "resource")[0];
+	const transferSize = resourceTiming?.transferSize ?? 0;
+	const deliveryType = resourceTiming?.deliveryType;
+	const hasServiceWorker = typeof navigator !== "undefined" && navigator.serviceWorker?.controller !== null;
+	const isPwaCache = transferSize === 0 && hasServiceWorker && (deliveryType === "cache" || deliveryType === "serviceworker") && resourceTiming?.duration !== void 0 && resourceTiming.duration > 0;
+	const isBrowserCache = transferSize === 0 && !isPwaCache && (!hasServiceWorker || deliveryType === "cache") && resourceTiming?.duration !== void 0 && resourceTiming.duration > 0;
+	const cfCacheStatus = response.headers.get("cf-cache-status");
+	const xCache = response.headers.get("x-cache");
+	const xSwiftCacheTime = response.headers.get("x-swift-cache-time");
+	const cdnCacheStatus = cfCacheStatus || xCache || xSwiftCacheTime;
+	let isCdnCache = false;
+	if (cdnCacheStatus) {
+		const statusLower = cdnCacheStatus.toLowerCase();
+		if (statusLower === "hit" || statusLower === "hits" || statusLower.includes("hit")) {
+			if (!statusLower.includes("miss") && !statusLower.includes("dynamic") && !statusLower.includes("bypass")) isCdnCache = true;
+		}
+	}
+	let cacheHit = false;
+	let cacheType = "none";
+	if (isPwaCache) {
+		cacheHit = true;
+		cacheType = "pwa";
+	} else if (isBrowserCache) {
+		cacheHit = true;
+		cacheType = "browser";
+	} else if (isCdnCache) {
+		cacheHit = true;
+		cacheType = "cdn";
+	}
+	return {
+		cacheHit,
+		cacheType,
+		transferSize,
+		cdnCacheStatus: cdnCacheStatus || void 0
+	};
+}
+/**
+* Simple download helper with CORS proxy support for development
+* Static resources don't need appId and token headers
+* 
+* Features:
+* - Supports AbortSignal for cancellation
+* - Automatic retry (default 3 times, no delay)
+* - PWA cache integration
+* 
+* @param url 资源 URL
+* @param options 下载选项
+* @returns ArrayBuffer and cache information
+*/
+async function downloadResource(url, options) {
+	const { signal, characterId, resourceType, maxRetries = 3 } = options || {};
+	if (signal?.aborted) throw new Error("Download cancelled");
+	try {
+		let cached = null;
+		let pwaCacheSubtype = void 0;
+		if (characterId) {
+			cached = await PwaCacheManager.getCharacterResource(characterId, url);
+			if (cached) pwaCacheSubtype = "character";
+		} else if (resourceType === "template") {
+			cached = await PwaCacheManager.getTemplateResource(url);
+			if (cached) pwaCacheSubtype = "template";
+		}
+		if (cached) {
+			const response = new Response(cached);
+			await new Promise((resolve) => setTimeout(resolve, 0));
+			const cacheInfo = getCacheInfo(url, response);
+			cacheInfo.cacheHit = true;
+			cacheInfo.cacheType = "pwa";
+			cacheInfo.pwaCacheSubtype = pwaCacheSubtype;
+			return {
+				data: cached,
+				cacheInfo
+			};
+		}
+		let lastError = null;
+		for (let attempt = 1; attempt <= maxRetries; attempt++) {
+			if (signal?.aborted) throw new Error("Download cancelled");
+			try {
+				const response = await fetch(url, { signal });
+				if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText}`);
+				const arrayBuffer = await response.arrayBuffer();
+				const contentLength = response.headers.get("content-length");
+				if (contentLength) {
+					const expectedSize = parseInt(contentLength, 10);
+					if (!isNaN(expectedSize) && arrayBuffer.byteLength < expectedSize) throw new Error(`Download incomplete: received ${arrayBuffer.byteLength} bytes, expected ${expectedSize} bytes`);
+				}
+				if (characterId) PwaCacheManager.putCharacterResource(characterId, url, arrayBuffer).catch((err) => {
+					logger.warn(`[downloadResource] Failed to cache character resource:`, err);
+				});
+				else if (resourceType === "template") PwaCacheManager.putTemplateResource(url, arrayBuffer).catch((err) => {
+					logger.warn(`[downloadResource] Failed to cache template resource:`, err);
+				});
+				await new Promise((resolve) => setTimeout(resolve, 0));
+				return {
+					data: arrayBuffer,
+					cacheInfo: getCacheInfo(url, response)
+				};
+			} catch (err) {
+				if (err instanceof Error && (err.name === "AbortError" || err.message === "Download cancelled")) throw err;
+				lastError = err instanceof Error ? err : new Error(String(err));
+				if (attempt < maxRetries) logger.warn(`[downloadResource] Attempt ${attempt}/${maxRetries} failed for ${url}, retrying immediately...`);
+			}
+		}
+		throw lastError || /* @__PURE__ */ new Error(`Failed to download ${url} after ${maxRetries} attempts`);
+	} catch (err) {
+		if (err instanceof Error && (err.name === "AbortError" || err.message === "Download cancelled")) throw err;
+		const msg = errorToMessage(err);
+		throw new Error(`[downloadResource] ${url} → ${msg}`);
+	}
+}
+var AvatarDownloader = class {
+	baseAssetsPath;
+	constructor(baseAssetsPath = "/") {
+		this.baseAssetsPath = baseAssetsPath;
+	}
+	/**
+	* Load unified template model (single gzip-compressed file)
+	* Includes PWA cache, retry, integrity check, and telemetry
+	* @internal
+	*/
+	async loadUnifiedTemplate() {
+		await PwaCacheManager.checkTemplateCacheVersion();
+		const startTime = Date.now();
+		const cdnBase = getFlameCdnBase(AvatarSDK.configuration?.region || "us-west");
+		const { unifiedModelPath } = APP_CONFIG.flame;
+		const url = `${cdnBase}/${unifiedModelPath}`;
+		logger.log(`📥 Loading unified template from: ${url}`);
+		const cached = await PwaCacheManager.getTemplateResource(url);
+		if (cached) {
+			const duration = Date.now() - startTime;
+			logger.log(`✅ Unified template loaded from cache (${(cached.byteLength / 1024 / 1024).toFixed(1)} MB)`);
+			logMetric("template_resources_load_measure", duration, {
+				file_count: 1,
+				cache_hit: true,
+				cache_type: "pwa"
+			});
+			return { unifiedModel: cached };
+		}
+		const maxRetries = 3;
+		let lastError = null;
+		for (let attempt = 1; attempt <= maxRetries; attempt++) try {
+			const response = await fetch(url);
+			if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText}`);
+			let buffer;
+			if (APP_CONFIG.flame.unifiedModelPath.endsWith(".gz")) {
+				const decompressedStream = response.body.pipeThrough(new DecompressionStream("gzip"));
+				buffer = await new Response(decompressedStream).arrayBuffer();
+			} else buffer = await response.arrayBuffer();
+			logger.log(`✅ Unified template loaded (${(buffer.byteLength / 1024 / 1024).toFixed(1)} MB)`);
+			PwaCacheManager.putTemplateResource(url, buffer).catch((err) => {
+				logger.warn(`[loadUnifiedTemplate] Failed to cache:`, err);
+			});
+			logMetric("template_resources_load_measure", Date.now() - startTime, {
+				file_count: 1,
+				cache_hit: false,
+				cache_type: "none"
+			});
+			return { unifiedModel: buffer };
+		} catch (err) {
+			lastError = err instanceof Error ? err : new Error(String(err));
+			if (attempt < maxRetries) logger.warn(`[loadUnifiedTemplate] Attempt ${attempt}/${maxRetries} failed, retrying...`);
+		}
+		throw lastError || /* @__PURE__ */ new Error(`Failed to download unified template after ${maxRetries} attempts`);
+	}
+	/**
+	* Load camera settings from CharacterMeta (optional)
+	* @internal
+	*/
+	async loadCameraSettings(characterMeta, options) {
+		const { signal } = options || {};
+		const cameraUrl = characterMeta.camera?.resource?.remote;
+		if (!cameraUrl) {
+			logger.log("ℹ️ No camera resource URL provided");
+			return;
+		}
+		if (signal?.aborted) throw new Error("Load cancelled");
+		try {
+			logger.log(`📥 Loading camera info from: ${cameraUrl}`);
+			const { data: arrayBuffer } = await downloadResource(cameraUrl, {
+				signal,
+				characterId: characterMeta.characterId ?? void 0,
+				resourceType: "character"
+			});
+			const text = new TextDecoder().decode(arrayBuffer);
+			const cameraSettings = JSON.parse(text);
+			logger.log("✅ Camera info loaded:", cameraSettings);
+			return cameraSettings;
+		} catch (error) {
+			logger.warn("⚠️ Failed to load camera info, using default:", error);
+			return;
+		}
+	}
+	/**
+	* Load character data from CharacterMeta (iOS compatible)
+	* @internal
+	*/
+	async loadCharacterData(characterMeta, options) {
+		const { progressCallback = null, signal, useCompressedModel = false } = options || {};
+		if (signal?.aborted) throw new Error("Download cancelled");
+		const totalStartTime = Date.now();
+		const shapeUrl = characterMeta.models?.shape?.resource?.remote;
+		const pointCloudUrl = useCompressedModel ? characterMeta.models?.gsStandard?.xrResource?.remote ?? characterMeta.models?.gsStandard?.resource?.remote : characterMeta.models?.gsStandard?.resource?.remote;
+		const idleAnimationUrl = characterMeta.animations?.frameIdle?.resource?.remote;
+		const monoAnimationUrl = characterMeta.animations?.frameMono?.resource?.remote;
+		if (!shapeUrl || !pointCloudUrl) throw new Error("Missing required resources: shape or gsStandard (point cloud)");
+		const filesToLoad = [{
+			key: "shape",
+			url: shapeUrl,
+			filename: "shape.pb"
+		}, {
+			key: "pointCloud",
+			url: pointCloudUrl,
+			filename: "point_cloud.ply"
+		}];
+		if (idleAnimationUrl) filesToLoad.push({
+			key: "idleAnimation",
+			url: idleAnimationUrl,
+			filename: "idle.pb",
+			optional: true
+		});
+		if (monoAnimationUrl) filesToLoad.push({
+			key: "monoAnimation",
+			url: monoAnimationUrl,
+			filename: "mono.pb",
+			optional: true
+		});
+		let loadedFiles = 0;
+		const totalFiles = filesToLoad.length;
+		const updateProgress = (filename, loaded) => {
+			if (progressCallback) {
+				if (loaded) loadedFiles++;
+				progressCallback({
+					stage: "character",
+					filename,
+					loaded: loadedFiles,
+					total: totalFiles,
+					progress: loadedFiles / totalFiles
+				});
+			}
+		};
+		const characterData = {};
+		const cacheInfos = [];
+		const parallelStartTime = Date.now();
+		const downloadPromises = filesToLoad.map(async ({ key, url, filename, optional }) => {
+			updateProgress(filename, false);
+			try {
+				const { data: arrayBuffer, cacheInfo } = await downloadResource(url, {
+					signal,
+					characterId: characterMeta.characterId ?? void 0,
+					resourceType: "character"
+				});
+				if (key === "shape") characterData.shape = arrayBuffer;
+				else if (key === "pointCloud") characterData.pointCloud = arrayBuffer;
+				else if (key === "idleAnimation") characterData.idleAnimation = arrayBuffer;
+				else if (key === "monoAnimation") characterData.monoAnimation = arrayBuffer;
+				cacheInfos.push(cacheInfo);
+				updateProgress(filename, true);
+				return {
+					key,
+					success: true,
+					size: arrayBuffer.byteLength
+				};
+			} catch (error) {
+				if (error instanceof Error && (error.name === "AbortError" || error.message === "Download cancelled")) {
+					logEvent("download_avatar_assets_cancelled", "info", { avatar_id: characterMeta.characterId ?? "unknown" });
+					throw error;
+				}
+				if (!optional) {
+					const errorMessage = error instanceof Error ? error.message : String(error);
+					logEvent("download_avatar_assets_failed", "error", {
+						avatar_id: characterMeta.characterId ?? "unknown",
+						description: `Failed to download required resource: ${filename}`,
+						resource: key,
+						url,
+						error: errorMessage
+					});
+					throw error;
+				}
+				logger.warn(`⚠️ Optional resource ${filename} failed to load:`, error);
+				updateProgress(filename, true);
+				return {
+					key,
+					success: false,
+					size: 0
+				};
+			}
+		});
+		await Promise.all(downloadPromises);
+		const parallelDuration = Date.now() - parallelStartTime;
+		const totalDuration = Date.now() - totalStartTime;
+		if (!characterData.shape || !characterData.pointCloud) {
+			const reason = "Failed to load character data";
+			logEvent("download_avatar_assets_failed", "error", {
+				avatar_id: characterMeta.characterId ?? "unknown",
+				description: reason
+			});
+			throw new Error(reason);
+		}
+		const cacheHit = cacheInfos.length > 0 && cacheInfos.every((info) => info.cacheHit);
+		const cacheType = cacheInfos[0]?.cacheType || "none";
+		const totalSize = Object.values(characterData).reduce((sum, buffer) => {
+			return sum + (buffer ? buffer.byteLength : 0);
+		}, 0);
+		logMetric("download_avatar_assets_latency", totalDuration, {
+			resolution: "default",
+			use_compressed_model: useCompressedModel,
+			file_count: filesToLoad.length,
+			cache_hit: cacheHit,
+			cache_type: cacheType
+		}, {
+			avatar_id: characterMeta.characterId ?? "unknown",
+			parallel_duration: parallelDuration,
+			total_size: totalSize
+		});
+		return characterData;
+	}
+	/**
+	* Preload all resources (template + character data + camera info + settings)
+	* @internal
+	*/
+	async preloadResources(characterMeta, options) {
+		const { progressCallback = null, signal, useCompressedModel = false } = options || {};
+		if (signal?.aborted) throw new Error("Preload cancelled");
+		const [characterData, preloadCameraSettings] = await Promise.all([this.loadCharacterData(characterMeta, {
+			signal,
+			useCompressedModel,
+			progressCallback: (info) => {
+				if (progressCallback) progressCallback({
+					...info,
+					stage: `character-${info.stage}`
+				});
+			}
+		}), this.loadCameraSettings(characterMeta, { signal })]);
+		return {
+			characterData,
+			preloadCameraSettings,
+			characterSettings: characterMeta.characterSettings
+		};
+	}
+	/**
+	* Get AvatarKit SDK API Client (region-templated endpoint composed by AvatarSDK.getEnvironmentConfig).
+	* Used for: character details and resource URLs (public endpoints, no auth required)
+	* Note: This endpoint does not require authentication, so we don't add X-App-Id or Authorization headers
+	* to avoid CORS preflight requests for simple GET requests
+	*/
+	getSdkApiClient() {
+		return { async request(url, options = {}) {
+			const baseUrl = AvatarSDK.getEnvironmentConfig().sdkApiBaseUrl;
+			const fullUrl = baseUrl + url;
+			const headers = {};
+			const method = options.method || "GET";
+			if (method !== "GET" && options.body) headers["Content-Type"] = "application/json";
+			const operation = url.split("?")[0].replace(/\/v2\/avatar\/[^/?]+/, "/v2/avatar/{id}");
+			let serverAddress;
+			try {
+				serverAddress = new URL(baseUrl).host;
+			} catch {}
+			const startMs = performance.now();
+			try {
+				const response = await fetch(fullUrl, {
+					method,
+					headers: {
+						...headers,
+						...options.headers
+					},
+					body: options.body ? JSON.stringify(options.body) : void 0,
+					signal: options.signal
+				});
+				recordHttpClientDuration({
+					operation,
+					method,
+					durationMs: Math.round(performance.now() - startMs),
+					statusCode: response.status,
+					serverAddress
+				});
+				if (!response.ok) {
+					let serverMessage = "";
+					try {
+						const body = await response.json();
+						if (body?.errors && Array.isArray(body.errors) && body.errors.length > 0) {
+							const e = body.errors[0];
+							serverMessage = e.detail || e.title || e.message || JSON.stringify(e);
+						} else serverMessage = body?.message || body?.error || JSON.stringify(body);
+					} catch {
+						serverMessage = response.statusText;
+					}
+					let error;
+					if (response.status === 404) {
+						const urlMatch = url.match(/\/v2\/(?:character|avatar)\/([^/?]+)/);
+						const extractedCharacterId = urlMatch ? urlMatch[1] : "unknown";
+						const callerTraceId = (options.headers || {})["x-sp-trace-id"];
+						logEvent("avatar_id_unrecognized", "error", {
+							avatar_id: extractedCharacterId,
+							description: `HTTP 404: ${serverMessage}`,
+							...callerTraceId ? { trace_id: callerTraceId } : {}
+						});
+						error = new AvatarError(`HTTP 404: ${serverMessage}`, ErrorCode.avatarIDUnrecognized);
+					} else error = new AvatarError(`HTTP ${response.status}: ${serverMessage}`, ErrorCode.failedToFetchAvatarMetadata);
+					throw error;
+				}
+				try {
+					return await response.json();
+				} catch {
+					throw new AvatarError("Avatar data is invalid. Please contact Spatius support.", ErrorCode.invalidAvatarMetadata);
+				}
+			} catch (err) {
+				if (err instanceof AvatarError) throw err;
+				recordHttpClientDuration({
+					operation,
+					method,
+					durationMs: Math.round(performance.now() - startMs),
+					serverAddress
+				});
+				throw new AvatarError("Failed to load avatar due to network issues, please check your connection and try again.", ErrorCode.failedToFetchAvatarMetadata);
+			}
+		} };
+	}
+	/**
+	* Map the new `/v2/avatar/{id}` `AvatarAsset` payload onto the internal
+	* `CharacterMeta` shape used by the existing download / render pipeline.
+	*
+	* The backend (grpc-gateway) serialises proto fields as camelCase JSON, so the
+	* runtime object is loosely shaped like the generated `AvatarAsset`. We:
+	* - lift `models.gs` into `models.gsStandard` (downloader/asset-count read gsStandard)
+	* - rename `animations.frameFallback` → `animations.frameMono`
+	* - fold the inline `camera` / `transform` into `characterSettings` so the
+	*   renderer's `resolveCameraConfig` reads structured values and no camera
+	*   resource is downloaded (top-level `camera` is intentionally left unset)
+	* @internal
+	*/
+	mapAvatarAssetToCharacterMeta(asset, avatarId) {
+		const characterSettings = {
+			...asset.camera ? { camera: { ...asset.camera } } : {},
+			...asset.transform ? { transform: { ...asset.transform } } : {}
+		};
+		return {
+			characterId: avatarId,
+			version: asset.version ?? "",
+			compatibilityFlags: asset.compatibilityFlags ?? [],
+			updatedAt: asset.updatedAt,
+			models: {
+				shape: asset.models?.shape,
+				gsStandard: asset.models?.gs
+			},
+			animations: {
+				frameIdle: asset.animations?.frameIdle,
+				frameMono: asset.animations?.frameFallback
+			},
+			customAnimations: asset.animations?.customAnimations ?? [],
+			characterSettings
+		};
+	}
+	/**
+	* Get single avatar by ID from AvatarKit SDK API (v2 driven-ingress avatar API).
+	* Domain: composed from region as api.${region}.spatius.ai
+	* Auth: Public endpoint, no authentication required
+	* Fetches the new `AvatarAsset` payload from `/v2/avatar/{id}` and maps it onto
+	* the internal `CharacterMeta` shape consumed by the download / render pipeline:
+	* - `models.gs` → `models.gsStandard`
+	* - `animations.frameFallback` → `animations.frameMono`
+	* - inline `camera` / `transform` → `characterSettings.{camera,transform}`
+	*   (so the renderer reads structured values directly and no camera resource is downloaded)
+	* @internal
+	*/
+	async getCharacterById(characterId, options) {
+		const { signal } = options || {};
+		const startTime = Date.now();
+		const traceId = generateTraceId();
+		try {
+			if (signal?.aborted) throw new Error("Request cancelled");
+			const response = await this.getSdkApiClient().request(`/v2/avatar/${characterId}`, {
+				method: "GET",
+				headers: { "x-sp-trace-id": traceId },
+				signal
+			});
+			if (response?.errors && Array.isArray(response.errors) && response.errors.length > 0) {
+				const firstError = response.errors[0];
+				const serverMessage = firstError.detail || firstError.title || firstError.message || "Unknown server error";
+				throw new AvatarError(`${firstError.code || firstError.status || "SERVER_ERROR"}: ${serverMessage}`, ErrorCode.failedToFetchAvatarMetadata);
+			}
+			logMetric("fetch_avatar_metadata_latency", Date.now() - startTime, {}, {
+				avatar_id: characterId,
+				trace_id: traceId
+			});
+			return this.mapAvatarAssetToCharacterMeta(response, characterId);
+		} catch (error) {
+			if (error instanceof Error && (error.name === "AbortError" || error.message === "Request cancelled")) {
+				logEvent("fetch_avatar_metadata_cancelled", "info", {
+					avatar_id: characterId ?? "unknown",
+					trace_id: traceId
+				});
+				throw error;
+			}
+			logger.error("Failed to fetch character:", error);
+			if (error instanceof AvatarError) {
+				logEvent("fetch_avatar_metadata_failed", "error", {
+					avatar_id: characterId ?? "unknown",
+					description: error.message,
+					trace_id: traceId
+				});
+				throw error;
+			}
+			const errorMessage = error && typeof error === "object" && "message" in error ? String(error.message) : "Failed to fetch character";
+			const dataMessage = error && typeof error === "object" && "data" in error && typeof error.data === "object" && error.data?.message ? String(error.data.message) : null;
+			logEvent("fetch_avatar_metadata_failed", "error", {
+				avatar_id: characterId ?? "unknown",
+				description: dataMessage || errorMessage,
+				trace_id: traceId
+			});
+			throw new AvatarError("Failed to load avatar due to network issues, please check your connection and try again.", ErrorCode.failedToFetchAvatarMetadata);
+		}
+	}
+};
+//#endregion
+export { AvatarDownloader };