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

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.1-beta.4] - 2026-07-30
+
+### Added
+- Opus audio support. `AudioFormat.inputAudioFormat` (`'pcm'` default, or `'opus'`) declares the format the host feeds into the SDK via `send`/`yieldAudioData`; `'opus'` input is decoded back to PCM16 for local rendering and forwarded upstream as-is in direct mode. `AudioFormat.opusUplinkEnabled` (default `false`) opts the direct-mode uplink into Opus compression (roughly 1/8 the upload, at the cost of client-side encoding), and `AudioFormat.opusBitrate` (default `48000`) tunes the target bitrate. Only effective in direct mode.
+
+### Changed
+- When `opusUplinkEnabled` is `true` but the configured `sampleRate` is not Opus-compatible, `initialize` now logs a warning and automatically falls back to a raw PCM uplink instead of silently failing to build the encoder.
+- `initialize` with a missing `appId` now fails fast (throws) with an updated message pointing to https://app.spatius.ai/ to obtain an app ID.
+
+### Fixed
+- Fixed playback failing to start when the first audio arrived slightly after the animation frames (both host and direct modes) — playback now begins correctly instead of stalling.
+- Fixed an intermittent burst of harsh noise at the start of Opus-input playback: on a fast start the first audio could be played before the Opus decoder finished initializing. Opus input is now always decoded before playback, so no raw Opus is ever played as PCM.
+- Fixed the idle animation freezing (and a delayed start) in direct mode with Opus input when animation frames arrived before the decoded audio: playback now waits for both audio and animation to be ready, and the avatar keeps looping idle smoothly until the round actually begins.
+
+## [1.3.1-beta.3] - 2026-07-18
+
+### Changed
+- Internal playback telemetry only; no changes to the public API or runtime behavior.
+
 ## [1.3.1-beta.2] - 2026-07-17
 
 ### Fixed

package/dist/AvatarDownloader-C2JJVqKm.js

@@ -0,0 +1,525 @@
+import { n as __exportAll } from "./rolldown-runtime-B-1-B7_t.js";
+import { t as AvatarSDK } from "./AvatarSDK-CuejGi0J.js";
+import { Et as ErrorCode, c as logEvent, gt as generateTraceId, l as logMetric, t as logger, vt as AvatarError, y as recordHttpClientDuration } from "./logger-C3fw-NWP.js";
+import { n as APP_CONFIG, r as getFlameCdnBase, t as errorToMessage } from "./error-utils-PtNzUHiL.js";
+import { t as PwaCacheManager } from "./pwa-cache-manager-D3nj4sd5.js";
+//#region core/AvatarDownloader.ts
+var AvatarDownloader_exports = /* @__PURE__ */ __exportAll({ AvatarDownloader: () => AvatarDownloader });
+/**
+* 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) {
+		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: {
+				...asset.camera ? { camera: { ...asset.camera } } : {},
+				...asset.transform ? { transform: { ...asset.transform } } : {}
+			}
+		};
+	}
+	/**
+	* 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];
+				throw new AvatarError(`${firstError.code || firstError.status || "SERVER_ERROR"}: ${firstError.detail || firstError.title || firstError.message || "Unknown server error"}`, 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_exports as n, AvatarDownloader as t };