@spatius/avatarkit 1.3.4 → 1.3.5

package/dist/assets/AvatarDownloader-DkReeoUZ.js

@@ -1,797 +0,0 @@
-import { St as ErrorCode, _t as generateTraceId, c as logEvent, h as hostOf, ht as isDebugMode, l as logMetric, t as logger, vt as AvatarError, y as recordHttpClientDuration } from "./logger-__jZD7QG.js";
-import { t as AvatarSDK } from "./AvatarSDK-DX8_-oyi.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
-	};
-}
-/**
-* 把整次角色加载的资产下载汇总成**一条** Transaction。
-*
-* 成败取「最差的一片」：任一片 transport error 即整次记 transport error；否则取
-* 状态码最大的那个（4xx/5xx 会盖过 200）。这样后端按状态码切出的成功率，含义是
-* 「这次加载的资产是否全部拿到」——与用户实际体验一致，一片挂了角色就出不来。
-*
-* duration 传整体耗时而非单片，与 `download_avatar_assets_latency` 同口径。
-*/
-function recordAssetTransaction(outcomes, durationMs, operation = ASSET_OPERATION) {
-	const real = outcomes.filter((o) => !o.skipped);
-	if (real.length === 0) return;
-	recordHttpClientDuration({
-		operation,
-		method: "GET",
-		durationMs,
-		statusCode: real.some((o) => o.statusCode === void 0) ? void 0 : real.reduce((max, o) => Math.max(max, o.statusCode ?? 0), 0),
-		serverAddress: real[0].host
-	});
-}
-/**
-* Transaction 的 `operation` 取值。必须低基数：资产 URL 带 avatar id 与文件名，
-* 直接当维度会让时间序列随角色数无限增长。要定位「哪个文件挂了」用
-* `download_avatar_assets_failed` log，它带 resource/url/error。
-*/
-const ASSET_OPERATION = "/assets/character";
-const TEMPLATE_OPERATION = "/assets/template";
-async function downloadResource(url, options) {
-	const { signal, characterId, resourceType, maxRetries = 3, outcomes } = options || {};
-	const outcomeSlotIndex = outcomes ? outcomes.length : -1;
-	if (outcomes) outcomes.push({ host: hostOf(url) });
-	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;
-			if (outcomes && outcomeSlotIndex >= 0) outcomes[outcomeSlotIndex] = {
-				host: hostOf(url),
-				skipped: true
-			};
-			return {
-				data: cached,
-				cacheInfo
-			};
-		}
-		let lastError = null;
-		for (let attempt = 1; attempt <= maxRetries; attempt++) {
-			if (signal?.aborted) throw new Error("Download cancelled");
-			const outcomeSlot = { host: hostOf(url) };
-			if (outcomes) outcomes[outcomeSlotIndex] = outcomeSlot;
-			try {
-				const response = await fetch(url, { signal });
-				outcomeSlot.statusCode = response.status;
-				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;
-		const templateOutcomes = [];
-		for (let attempt = 1; attempt <= maxRetries; attempt++) {
-			const outcomeSlot = { host: hostOf(url) };
-			templateOutcomes[0] = outcomeSlot;
-			try {
-				const response = await fetch(url);
-				outcomeSlot.statusCode = response.status;
-				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"
-				});
-				recordAssetTransaction(templateOutcomes, Date.now() - startTime, TEMPLATE_OPERATION);
-				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...`);
-			}
-		}
-		recordAssetTransaction(templateOutcomes, Date.now() - startTime, TEMPLATE_OPERATION);
-		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 = [];
-		/** 各片的 HTTP 结果，收尾时汇总成一条 Transaction（见 recordAssetTransaction）。 */
-		const httpOutcomes = [];
-		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",
-					outcomes: httpOutcomes
-				});
-				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
-				};
-			}
-		});
-		try {
-			await Promise.all(downloadPromises);
-		} finally {
-			recordAssetTransaction(httpOutcomes, Date.now() - totalStartTime);
-		}
-		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 {
-			data: characterData,
-			cacheHit,
-			cacheType
-		};
-	}
-	/**
-	* 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 [characterResult, 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: characterResult.data,
-			preloadCameraSettings,
-			characterSettings: characterMeta.characterSettings,
-			cacheHit: characterResult.cacheHit,
-			cacheType: characterResult.cacheType
-		};
-	}
-	/**
-	* 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 };