@spatius/avatarkit 1.3.6 → 1.3.8

package/dist/core/AvatarController.d.ts

@@ -82,10 +82,6 @@ export declare class AvatarController {
      * Orthogonal to user pause — user pause/resume does not change it; only frame arrival does.
      */
     private isAudioStalledForStarvation;
-    private playbackStuckCheckState;
-    private readonly MAX_AUDIO_TIME_ZERO_COUNT;
-    private readonly MAX_AUDIO_TIME_STUCK_COUNT;
-    private readonly AUDIO_TIME_STUCK_THRESHOLD;
     private latencyMarks;
     /**
      * W3C `traceparent` the driving service stamped on this round's animation

package/dist/core/AvatarView.d.ts

@@ -52,6 +52,44 @@ export declare class AvatarView {
         width: number;
         height: number;
     };
+    /**
+     * Set once the first-frame callback has fired; the render loop samples the
+     * canvas on the first frame after this deadline and then clears it.
+     *
+     * The check exists because "the render loop is running" does not mean anything
+     * reached the screen. Failures along the render path mostly log and return, so
+     * a user seeing nothing produces no signal at all. This asks the only question
+     * that matters at the end: did this layer draw anything?
+     *
+     * Sampling has to happen inside the loop, right after renderFrame() — the
+     * context runs with preserveDrawingBuffer:false, so the buffer is only valid
+     * there. Reading from a timer would find it already cleared and report every
+     * healthy session as blank.
+     */
+    private _blankCheckDueAt;
+    private _blankCheckDone;
+    /** How long after the first frame to sample. Long enough for the pipeline to settle. */
+    private static readonly BLANK_CHECK_DELAY_MS;
+    /**
+     * Sample size. The browser scales the full canvas into this, so it covers the
+     * whole frame rather than a crop — the avatar is found wherever it sits. Kept
+     * tiny because the question is only "any opaque pixel at all"; reading the
+     * full canvas would copy megabytes for a yes/no answer.
+     */
+    private static readonly BLANK_CHECK_WIDTH;
+    private static readonly BLANK_CHECK_HEIGHT;
+    private scheduleBlankCanvasCheck;
+    /**
+     * Called from the render loop immediately after renderFrame(), while the
+     * drawing buffer is still valid.
+     */
+    private runBlankCanvasCheckIfDue;
+    /**
+     * Count pixels that are not fully transparent. Null when the sample could not
+     * be taken at all, which is not the same as a blank frame and must not be
+     * reported as one.
+     */
+    private countOpaquePixels;
     private _exportBitmapResolve;
     /**
      * Exports the current rendering as a Blob (PNG).

package/dist/index.js

@@ -1,5 +1,5 @@
 import { n as __toESM, t as __commonJSMin } from "./rolldown-runtime-FDOR9p9I.js";
-import { $ as DEFAULT_REGION, A as clockSync, B as OTEL_LOGS_ENDPOINT, C as logMetric, D as monoMarkFrom, E as initializeOtel, F as recordHttpClientDuration, G as idManager, H as OTEL_STREAM_NAME, I as recordMetric, J as AvatarError, K as generateTraceId, L as getSdkPackage, M as hostOf, N as cleanupOtelMetrics, O as monoTimestamp, P as initializeOtelMetrics, Q as DEFAULT_OPUS_BITRATE, R as resolveSdkVersion, S as logEvent, T as cleanupOtel, U as OTEL_USERNAME, V as OTEL_PASSWORD, W as isDebugMode, X as ConnectionState, Y as AvatarState, Z as ConversationState, _ as logSink, a as startLoadTrace, at as LogLevel, b as getLogsFeatureFlag, c as AudioFormat, ct as TransitionType, d as MessageType, et as DEFAULT_REGION_REQUEST, f as TransportCompression, g as setLogLevel, h as logger, i as startInitTrace, it as LoadProgress, j as fetchBootstrap, k as resolveMarks, l as EgressType, lt as requireSDK, m as BinaryWriter, n as initializeOtelTrace, nt as ErrorCode, o as startPlaybackTrace, ot as RENDER_QUALITY_PARAMS, p as BinaryReader, q as AnimationType, r as startConnectTrace, rt as FrameStarvationMode, s as buildTraceparent, st as RenderQuality, t as cleanupOtelTrace, tt as DrivingServiceMode, u as Message, ut as setSDKRef, v as cleanupPostHog, w as updatePostHogPersonPropertiesForFlags, x as initializePostHog, y as clientContextFields } from "./otel-trace-B4E2lODB.js";
+import { $ as DEFAULT_REGION, A as monoTimestamp, B as resolveSdkVersion, C as logMetric, D as initializeOtel, E as cleanupOtel, F as cleanupOtelMetrics, G as idManager, H as OTEL_LOGS_ENDPOINT, I as initializeOtelMetrics, J as AvatarError, K as generateTraceId, L as recordHttpClientDuration, M as clockSync, N as fetchBootstrap, P as hostOf, Q as DEFAULT_OPUS_BITRATE, R as recordMetric, S as logEvent, T as updatePostHogPersonPropertiesForFlags, U as OTEL_STREAM_NAME, W as isDebugMode, X as ConnectionState, Y as AvatarState, Z as ConversationState, _ as logSink, a as startLoadTrace, at as LogLevel, b as getLogsFeatureFlag, c as AudioFormat, ct as TransitionType, d as MessageType, et as DEFAULT_REGION_REQUEST, f as TransportCompression, g as setLogLevel, h as logger, i as startInitTrace, it as LoadProgress, j as resolveMarks, k as monoMarkFrom, l as EgressType, lt as requireSDK, m as BinaryWriter, n as initializeOtelTrace, nt as ErrorCode, o as startPlaybackTrace, ot as RENDER_QUALITY_PARAMS, p as BinaryReader, q as AnimationType, r as startConnectTrace, rt as FrameStarvationMode, s as buildTraceparent, st as RenderQuality, t as cleanupOtelTrace, tt as DrivingServiceMode, u as Message, ut as setSDKRef, v as cleanupPostHog, w as trackEvent, x as initializePostHog, y as clientContextFields, z as getSdkPackage } from "./otel-trace-CZJAGjGg.js";
 //#region core/Avatar.ts
 var Avatar = class {
 	id;
@@ -41912,7 +41912,7 @@ var OpusDecoderProxy = class OpusDecoderProxy {
 			try {
 				worker = new Worker(new URL(
 					/* @vite-ignore */
-					"" + new URL("assets/OpusDecoderWorker.worker-DbdfH4qX.js", import.meta.url).href,
+					"" + new URL("assets/OpusDecoderWorker.worker-DVOREuTG.js", import.meta.url).href,
 					"" + import.meta.url
 				), { type: "module" });
 			} catch (err) {
@@ -44372,29 +44372,26 @@ function emitInitErrorLog(params) {
 		];
 		const client = clientContextFields();
 		for (const [k, v] of Object.entries(client)) logAttrs.push(kv(k, v));
-		const payload = { resourceLogs: [{
-			resource: { attributes: resourceAttrs },
-			scopeLogs: [{
-				scope: { name: OTEL_LOGGER_NAME },
-				logRecords: [{
-					timeUnixNano: nowNanos,
-					severityNumber: SEVERITY_ERROR,
-					severityText: "ERROR",
-					body: { stringValue: event },
-					attributes: logAttrs
-				}]
-			}]
-		}] };
-		const authToken = btoa(`${OTEL_USERNAME}:${OTEL_PASSWORD}`);
 		fetch(OTEL_LOGS_ENDPOINT, {
 			method: "POST",
 			keepalive: true,
 			headers: {
 				"Content-Type": "application/json",
-				Authorization: `Basic ${authToken}`,
 				"stream-name": OTEL_STREAM_NAME
 			},
-			body: JSON.stringify(payload)
+			body: JSON.stringify({ resourceLogs: [{
+				resource: { attributes: resourceAttrs },
+				scopeLogs: [{
+					scope: { name: OTEL_LOGGER_NAME },
+					logRecords: [{
+						timeUnixNano: nowNanos,
+						severityNumber: SEVERITY_ERROR,
+						severityText: "ERROR",
+						body: { stringValue: event },
+						attributes: logAttrs
+					}]
+				}]
+			}] })
 		}).catch(() => {});
 	} catch {}
 }
@@ -45730,7 +45727,7 @@ var AvatarSDK = class {
 	static _initializationState = "uninitialized";
 	static _initializingPromise = null;
 	static _configuration = null;
-	static _version = "1.3.6";
+	static _version = "1.3.8";
 	static _avatarCore = null;
 	static _cachedDeviceScore = null;
 	static _rendererBackend = null;
@@ -46295,7 +46292,7 @@ var OpusEncoderProxy = class OpusEncoderProxy {
 			try {
 				worker = new Worker(new URL(
 					/* @vite-ignore */
-					"" + new URL("assets/OpusEncoderWorker.worker-DVnsr0L5.js", import.meta.url).href,
+					"" + new URL("assets/OpusEncoderWorker.worker-fkLsXEK1.js", import.meta.url).href,
 					"" + import.meta.url
 				), { type: "module" });
 			} catch (err) {
@@ -47830,15 +47827,6 @@ var AvatarController = class {
 	* Orthogonal to user pause — user pause/resume does not change it; only frame arrival does.
 	*/
 	isAudioStalledForStarvation = false;
-	playbackStuckCheckState = {
-		audioTimeZeroCount: 0,
-		lastAudioTime: 0,
-		audioTimeStuckCount: 0,
-		reported: false
-	};
-	MAX_AUDIO_TIME_ZERO_COUNT = 25;
-	MAX_AUDIO_TIME_STUCK_COUNT = 25;
-	AUDIO_TIME_STUCK_THRESHOLD = .001;
 	latencyMarks = {
 		accumulatedBytes: 0,
 		taps: /* @__PURE__ */ new Map(),
@@ -49141,79 +49129,6 @@ var AvatarController = class {
 	* Playback loop: Calculate animation frame based on audio time, notify render layer to render
 	*/
 	/**
-	* 检测播放是否卡住（在过渡动画完成后）
-	* 注意：AudioContext suspended 的情况现在由 StreamingAudioPlayer 自动处理，不再作为触发条件
-	* 此函数主要用于检测其他原因导致的播放卡住（如网络问题、音频数据问题等）
-	* 
-	* @param audioTime 当前音频时间
-	* @returns true 如果检测到卡住并已上报，false 否则
-	* @internal
-	*/
-	checkPlaybackStuck(audioTime) {
-		const streamingPlayer = this.animationPlayer?.getStreamingPlayer();
-		if (!streamingPlayer) return false;
-		const state = this.playbackStuckCheckState;
-		const hasAnimationData = this.currentKeyframes.length > 0;
-		const hasAudioData = streamingPlayer.audioChunks?.length > 0;
-		const isNotPaused = this.currentState !== AvatarState.paused;
-		if (this.isAudioStalledForStarvation) {
-			state.audioTimeZeroCount = 0;
-			state.audioTimeStuckCount = 0;
-			state.lastAudioTime = 0;
-			state.reported = false;
-			return false;
-		}
-		if (!hasAnimationData || !hasAudioData || this.currentState === AvatarState.paused) {
-			state.audioTimeZeroCount = 0;
-			state.audioTimeStuckCount = 0;
-			state.lastAudioTime = 0;
-			state.reported = false;
-			return false;
-		}
-		if (state.reported) return true;
-		const audioContextState = streamingPlayer.audioContext?.state || "unknown";
-		const activeSourcesCount = streamingPlayer.activeSources?.size || 0;
-		const scheduledChunks = streamingPlayer.scheduledChunks || 0;
-		const hasScheduledButNoActive = scheduledChunks > 0 && activeSourcesCount === 0;
-		if (audioTime === 0) state.audioTimeZeroCount++;
-		else state.audioTimeZeroCount = 0;
-		if (Math.abs(audioTime - state.lastAudioTime) < this.AUDIO_TIME_STUCK_THRESHOLD) state.audioTimeStuckCount++;
-		else state.audioTimeStuckCount = 0;
-		state.lastAudioTime = audioTime;
-		if ((state.audioTimeZeroCount > this.MAX_AUDIO_TIME_ZERO_COUNT || state.audioTimeStuckCount > this.MAX_AUDIO_TIME_STUCK_COUNT || hasScheduledButNoActive && this.isPlaying) && isNotPaused) {
-			state.reported = true;
-			logEvent("playback_stuck_after_transition", "error", {
-				avatar_id: this.avatar.id,
-				conversation_id: this.currentConversationId || void 0,
-				audio_context_state: audioContextState,
-				audio_time: audioTime,
-				audio_time_zero: audioTime === 0,
-				audio_time_zero_count: state.audioTimeZeroCount,
-				audio_time_stuck: state.audioTimeStuckCount > this.MAX_AUDIO_TIME_STUCK_COUNT,
-				audio_time_stuck_count: state.audioTimeStuckCount,
-				has_scheduled_but_no_active: hasScheduledButNoActive,
-				is_playing: this.isPlaying,
-				current_state: this.currentState,
-				animation_frames_count: this.currentKeyframes.length,
-				audio_chunks_count: streamingPlayer.audioChunks?.length || 0,
-				scheduled_chunks: scheduledChunks,
-				active_sources_count: activeSourcesCount
-			});
-			return true;
-		}
-		return false;
-	}
-	/**
-	* Reset playback stuck detection counters
-	* @internal
-	*/
-	resetPlaybackStuckCheckState() {
-		this.playbackStuckCheckState.audioTimeZeroCount = 0;
-		this.playbackStuckCheckState.audioTimeStuckCount = 0;
-		this.playbackStuckCheckState.lastAudioTime = 0;
-		this.playbackStuckCheckState.reported = false;
-	}
-	/**
 	* Memory optimization: clean old keyframes if array is too long.
 	* Extracted from the former computeAndRenderFrame so that the monitoring-only
 	* playback loop can still manage memory without doing WASM computation.
@@ -49342,11 +49257,6 @@ var AvatarController = class {
 	monitorPlaybackTick(audioTime, frameIndex) {
 		if (!this.isPlaying || this.currentState === AvatarState.paused) return;
 		try {
-			this.checkPlaybackStuck(audioTime);
-			if (audioTime > 0 && Math.abs(audioTime - this.playbackStuckCheckState.lastAudioTime) >= this.AUDIO_TIME_STUCK_THRESHOLD) {
-				this.playbackStuckCheckState.audioTimeZeroCount = 0;
-				this.playbackStuckCheckState.audioTimeStuckCount = 0;
-			}
 			if (audioTime > 0) {
 				if (frameIndex > this.lastRenderedFrameIndex) this.lastRenderedFrameIndex = frameIndex;
 				this.cleanupKeyframesIfNeeded(frameIndex);
@@ -49416,7 +49326,6 @@ var AvatarController = class {
 		this.resetConversationIdState();
 	}
 	stopPlayback() {
-		this.resetPlaybackStuckCheckState();
 		this.isStartingPlayback = false;
 		if (this.animationPlayer) {
 			this.animationPlayer.stop();
@@ -51794,7 +51703,7 @@ function generateTransitionFrames(from, to, durationMs, fps = 25) {
 }
 //#endregion
 //#region core/AvatarView.ts
-var AvatarView = class {
+var AvatarView = class AvatarView {
 	avatarController;
 	avatar;
 	onFirstRendering;
@@ -51982,6 +51891,83 @@ var AvatarView = class {
 			height: this.canvas.height
 		};
 	}
+	/**
+	* Set once the first-frame callback has fired; the render loop samples the
+	* canvas on the first frame after this deadline and then clears it.
+	*
+	* The check exists because "the render loop is running" does not mean anything
+	* reached the screen. Failures along the render path mostly log and return, so
+	* a user seeing nothing produces no signal at all. This asks the only question
+	* that matters at the end: did this layer draw anything?
+	*
+	* Sampling has to happen inside the loop, right after renderFrame() — the
+	* context runs with preserveDrawingBuffer:false, so the buffer is only valid
+	* there. Reading from a timer would find it already cleared and report every
+	* healthy session as blank.
+	*/
+	_blankCheckDueAt = null;
+	_blankCheckDone = false;
+	/** How long after the first frame to sample. Long enough for the pipeline to settle. */
+	static BLANK_CHECK_DELAY_MS = 1e3;
+	/**
+	* Sample size. The browser scales the full canvas into this, so it covers the
+	* whole frame rather than a crop — the avatar is found wherever it sits. Kept
+	* tiny because the question is only "any opaque pixel at all"; reading the
+	* full canvas would copy megabytes for a yes/no answer.
+	*/
+	static BLANK_CHECK_WIDTH = 64;
+	static BLANK_CHECK_HEIGHT = 128;
+	scheduleBlankCanvasCheck() {
+		if (this._blankCheckDone || this._blankCheckDueAt !== null) return;
+		this._blankCheckDueAt = performance.now() + AvatarView.BLANK_CHECK_DELAY_MS;
+	}
+	/**
+	* Called from the render loop immediately after renderFrame(), while the
+	* drawing buffer is still valid.
+	*/
+	runBlankCanvasCheckIfDue() {
+		const dueAt = this._blankCheckDueAt;
+		if (dueAt === null || performance.now() < dueAt) return;
+		this._blankCheckDueAt = null;
+		this._blankCheckDone = true;
+		const sampleStart = performance.now();
+		const opaquePixels = this.countOpaquePixels();
+		const sampleMs = performance.now() - sampleStart;
+		if (opaquePixels === null || opaquePixels > 0) return;
+		logger.error(`[AvatarView] Blank canvas: nothing was drawn ${AvatarView.BLANK_CHECK_DELAY_MS}ms after the first frame`);
+		trackEvent("render_blank_canvas", "error", {
+			canvas_width: this.canvas?.width ?? 0,
+			canvas_height: this.canvas?.height ?? 0,
+			sampled_pixels: AvatarView.BLANK_CHECK_WIDTH * AvatarView.BLANK_CHECK_HEIGHT,
+			delay_ms: AvatarView.BLANK_CHECK_DELAY_MS,
+			sample_ms: Number(sampleMs.toFixed(1))
+		});
+	}
+	/**
+	* Count pixels that are not fully transparent. Null when the sample could not
+	* be taken at all, which is not the same as a blank frame and must not be
+	* reported as one.
+	*/
+	countOpaquePixels() {
+		const canvas = this.canvas;
+		if (!canvas || canvas.width === 0 || canvas.height === 0) return null;
+		const w = AvatarView.BLANK_CHECK_WIDTH;
+		const h = AvatarView.BLANK_CHECK_HEIGHT;
+		try {
+			const scratch = document.createElement("canvas");
+			scratch.width = w;
+			scratch.height = h;
+			const ctx = scratch.getContext("2d", { willReadFrequently: true });
+			if (!ctx) return null;
+			ctx.drawImage(canvas, 0, 0, w, h);
+			const data = ctx.getImageData(0, 0, w, h).data;
+			let count = 0;
+			for (let i = 3; i < data.length; i += 4) if (data[i] !== 0) count++;
+			return count;
+		} catch {
+			return null;
+		}
+	}
 	_exportBitmapResolve = null;
 	/**
 	* Exports the current rendering as a Blob (PNG).
@@ -52210,6 +52196,7 @@ var AvatarView = class {
 			this.renderSystem.renderFrame();
 			if (APP_CONFIG.debug) logger.log("[AvatarView] First frame rendered successfully");
 			this.onFirstRendering?.();
+			this.scheduleBlankCanvasCheck();
 		} else throw new Error("Failed to compute first frame splat data");
 	}
 	/**
@@ -52289,8 +52276,10 @@ var AvatarView = class {
 					this.currentFrame = frame;
 					const wasmParams = convertProtoFlameToWasmParams(frame);
 					computeInFlight = true;
+					const computeStart = performance.now();
 					avatarCore.computeFrameFlatFromParams(wasmParams, this.characterHandle ?? void 0).then((splatData) => {
-						if (splatData && !this.isPureRenderingMode) this.doRender(splatData);
+						const computeMs = performance.now() - computeStart;
+						if (splatData && !this.isPureRenderingMode) this.doRender(splatData, computeMs);
 					}).catch((e) => logger.warn("[AvatarView] Transition frame compute failed:", e instanceof Error ? e.message : String(e))).finally(() => {
 						computeInFlight = false;
 					});
@@ -52312,8 +52301,10 @@ var AvatarView = class {
 							this.currentFrame = currentFrame;
 							const wasmParams = convertProtoFlameToWasmParams(currentFrame);
 							computeInFlight = true;
+							const computeStart = performance.now();
 							avatarCore.computeFrameFlatFromParams(wasmParams, this.characterHandle ?? void 0).then((splatData) => {
-								if (splatData && !this.isPureRenderingMode) this.doRender(splatData);
+								const computeMs = performance.now() - computeStart;
+								if (splatData && !this.isPureRenderingMode) this.doRender(splatData, computeMs);
 							}).catch((e) => logger.warn("[AvatarView] Conversation frame compute failed:", e instanceof Error ? e.message : String(e))).finally(() => {
 								computeInFlight = false;
 							});
@@ -52345,13 +52336,15 @@ var AvatarView = class {
 				computeInFlight = true;
 				(async () => {
 					try {
+						const computeStart = performance.now();
 						const splatData = await avatarCore.computeCompleteFrameFlat({
 							frameIndex: fi,
 							animationInfo: animInfo
 						}, this.characterHandle ?? void 0);
+						const computeMs = performance.now() - computeStart;
 						const currentParams = await avatarCore.getCurrentFrameParams(fi, this.characterId, animInfo);
 						this.currentFrame = convertWasmParamsToProtoFlame(currentParams);
-						if (splatData && !this.isPureRenderingMode) this.doRender(splatData);
+						if (splatData && !this.isPureRenderingMode) this.doRender(splatData, computeMs);
 					} catch (e) {
 						logger.warn("[AvatarView] Idle frame compute failed:", e instanceof Error ? e.message : String(e));
 					} finally {
@@ -52481,12 +52474,13 @@ var AvatarView = class {
 	* This is the single point of control for renderingEnabled flag
 	* @internal
 	*/
-	doRender(splatData) {
+	doRender(splatData, computeMs = 0) {
 		if (!this.renderSystem || !this._renderingEnabled) return;
-		const startTime = performance.now();
+		const startTime = performance.now() - computeMs;
 		this.updateFPS();
 		this.renderSystem.loadSplatsFromPackedData(splatData);
 		this.renderSystem.renderFrame();
+		this.runBlankCanvasCheckIfDue();
 		if (this._exportBitmapResolve) {
 			const resolve = this._exportBitmapResolve;
 			this._exportBitmapResolve = null;
@@ -52676,8 +52670,10 @@ var AvatarView = class {
 			const wasmParams = convertProtoFlameToWasmParams(flame);
 			const avatarCore = AvatarSDK.getAvatarCore();
 			if (!avatarCore) throw new Error("AvatarCore not available");
+			const computeStart = performance.now();
 			const splatData = await avatarCore.computeFrameFlatFromParams(wasmParams, this.characterHandle ?? void 0);
-			if (splatData) this.doRender(splatData);
+			const computeMs = performance.now() - computeStart;
+			if (splatData) this.doRender(splatData, computeMs);
 		} catch (error) {
 			logger.error("[AvatarView] Failed to render flame:", error instanceof Error ? error.message : String(error));
 			throw error;
@@ -52983,8 +52979,10 @@ var AvatarView = class {
 		const avatarCore = AvatarSDK.getAvatarCore();
 		if (!avatarCore || !this.renderSystem) return;
 		try {
+			const computeStart = performance.now();
 			const splatData = await avatarCore.computeCompleteFrameFlat({ frameIndex: this.activeAnimationState.frameIndex }, this.characterHandle ?? void 0);
-			if (splatData) this.doRender(splatData);
+			const computeMs = performance.now() - computeStart;
+			if (splatData) this.doRender(splatData, computeMs);
 		} catch (error) {
 			logger.warn("[AvatarView] Failed to render current idle frame:", error);
 		}

package/dist/internal-telemetry.d.ts

@@ -79,6 +79,41 @@ export declare function peekTraceparent(rawMessage: Uint8Array): string | undefi
  * dropped before it is sent.
  */
 export declare function recordMetric(name: string, value: number, attributes?: Attributes): void;
+/**
+ * Emit one event onto avatarkit's OTel log channel.
+ *
+ * Must go through here rather than the RTC SDK calling `logs.getLogger().emit()`
+ * itself. Sharing the global LoggerProvider only carries Resource-level
+ * attributes (app_id / region / sdk.version); the record-level identity fields
+ * — `user_id`, `client_id` — are stamped inside this SDK's emit path, so a
+ * record emitted directly through the provider carries none of them. Routing
+ * through here is what the Android / iOS RTC SDKs already do via their
+ * `RTCTelemetry.track` entry, and it additionally picks up crash-replay
+ * persistence and the pre-calibration queue.
+ *
+ * The timestamp is taken here rather than accepted from the caller: this path
+ * resolves it against the calibrated clock and stamps `server_timestamp`
+ * alongside, which a caller-supplied `Date.now()` cannot do.
+ */
+export declare function trackEvent(event: string, level?: 'debug' | 'info' | 'warning' | 'error', contents?: Record<string, unknown>): void;
+/**
+ * The client environment fields this SDK stamps on every OTel log record —
+ * `host`, `domain`, `url`, `pathname`, `referrer`, `user_agent`, `locale`,
+ * screen/viewport size and `timezone`.
+ *
+ * Shared with the RTC SDK rather than re-derived there. These are record-level
+ * fields, not Resource attributes: they are read from `window.location` at emit
+ * time because `url`/`pathname` change as a single-page app routes. Sharing the
+ * OTel providers therefore does not carry them across — the RTC SDK emits
+ * through its own logger and would report no `host` at all, which is what
+ * prompted this export. Re-implementing the collection on that side would let
+ * the two drift apart in field names and in how each value is read, and the
+ * backend aggregates on exactly these names.
+ *
+ * Call at emit time, once per record; spread the result before the caller's own
+ * properties so an explicit value at the call site still wins.
+ */
+export declare function clientContextFields(): Record<string, string | number>;
 /**
  * Declare which SDK these records come from, as the `sdk.package` and
  * `sdk.version` resource attributes.

package/dist/internal-telemetry.js

@@ -1,4 +1,4 @@
-import { A as clockSync, I as recordMetric$1, o as startPlaybackTrace$1, u as Message, z as setSdkIdentity$1 } from "./otel-trace-B4E2lODB.js";
+import { M as clockSync, O as trackEventOtel, R as recordMetric$1, V as setSdkIdentity$1, o as startPlaybackTrace$1, u as Message, y as clientContextFields$1 } from "./otel-trace-CZJAGjGg.js";
 //#region internal-telemetry.ts
 /**
 * Internal telemetry surface for the companion RTC SDK.
@@ -91,6 +91,45 @@ function recordMetric(name, value, attributes = {}) {
 	recordMetric$1(name, value, attributes);
 }
 /**
+* Emit one event onto avatarkit's OTel log channel.
+*
+* Must go through here rather than the RTC SDK calling `logs.getLogger().emit()`
+* itself. Sharing the global LoggerProvider only carries Resource-level
+* attributes (app_id / region / sdk.version); the record-level identity fields
+* — `user_id`, `client_id` — are stamped inside this SDK's emit path, so a
+* record emitted directly through the provider carries none of them. Routing
+* through here is what the Android / iOS RTC SDKs already do via their
+* `RTCTelemetry.track` entry, and it additionally picks up crash-replay
+* persistence and the pre-calibration queue.
+*
+* The timestamp is taken here rather than accepted from the caller: this path
+* resolves it against the calibrated clock and stamps `server_timestamp`
+* alongside, which a caller-supplied `Date.now()` cannot do.
+*/
+function trackEvent(event, level = "info", contents = {}) {
+	trackEventOtel(event, level, contents);
+}
+/**
+* The client environment fields this SDK stamps on every OTel log record —
+* `host`, `domain`, `url`, `pathname`, `referrer`, `user_agent`, `locale`,
+* screen/viewport size and `timezone`.
+*
+* Shared with the RTC SDK rather than re-derived there. These are record-level
+* fields, not Resource attributes: they are read from `window.location` at emit
+* time because `url`/`pathname` change as a single-page app routes. Sharing the
+* OTel providers therefore does not carry them across — the RTC SDK emits
+* through its own logger and would report no `host` at all, which is what
+* prompted this export. Re-implementing the collection on that side would let
+* the two drift apart in field names and in how each value is read, and the
+* backend aggregates on exactly these names.
+*
+* Call at emit time, once per record; spread the result before the caller's own
+* properties so an explicit value at the call site still wins.
+*/
+function clientContextFields() {
+	return clientContextFields$1();
+}
+/**
 * Declare which SDK these records come from, as the `sdk.package` and
 * `sdk.version` resource attributes.
 *
@@ -117,4 +156,4 @@ function setSdkIdentity(identity) {
 	setSdkIdentity$1(identity);
 }
 //#endregion
-export { isClockCalibrated, peekTraceparent, recordMetric, resolveMonoTimestamp, setSdkIdentity, startPlaybackTrace };
+export { clientContextFields, isClockCalibrated, peekTraceparent, recordMetric, resolveMonoTimestamp, setSdkIdentity, startPlaybackTrace, trackEvent };