@sendbird/ai-agent-messenger-react 1.35.1 → 1.37.0

package/dist/index.d.ts

@@ -4,7 +4,6 @@ import type { AIAgentModule } from '@sendbird/chat/aiAgent';
 import { AriaRole } from 'react';
 import type { BaseChannelCollectionEventHandler } from '@sendbird/chat/groupChannel';
 import type { BaseMessage } from '@sendbird/chat/message';
-import type { CollectionEventSource } from '@sendbird/chat';
 import { ComponentType } from 'react';
 import { Context } from 'react';
 import type { Conversation as Conversation_2 } from '@sendbird/chat/aiAgent';
@@ -292,29 +291,28 @@ declare abstract class AIAgentBaseStats {
     protected committed: boolean = false;
     protected commitCallback: StatsAppendCallback | null = null;
     protected conversationId: number | null = null;
-    protected channelUrl: string | null = null;
     protected errorCode: number | null = null;
     protected errorDescription: string | null = null;
     protected extraData: Record<string, unknown> = {};
 
+    protected abstract buildPayload(): AIAgentStatPayload | null;
+    protected abstract getMetricKey(): string;
+
     setCommitCallback(callback: StatsAppendCallback): this {
         this.commitCallback = callback;
         return this;
     }
 
-    setConversationId(id: number): this {
-        this.conversationId = id;
+    setConversationId(id?: number): this {
+        if (id) this.conversationId = id;
         return this;
     }
 
-    setChannelUrl(url: string): this {
-        this.setExtra('channel_url', url);
-        return this;
-    }
+    setError(error: unknown | null | undefined): this {
+        if (error === null || error === undefined) return this;
 
-    setError(code: number | undefined, description: string): this {
-        this.errorCode = code ?? DEFAULT_ERROR_CODE;
-        this.errorDescription = description;
+        this.errorCode = getErrorCode(error) ?? DEFAULT_ERROR_CODE;
+        this.errorDescription = getErrorDescription(error);
         return this;
     }
 
@@ -331,7 +329,7 @@ declare abstract class AIAgentBaseStats {
         const existing = this.timers.get(key);
         if (existing?.startTime !== null && existing?.startTime !== undefined) return this;
 
-        this.timers.set(key, { startTime: defaultStatsClock.now(), endTime: null });
+        this.timers.set(key, { startTime: performance.now(), endTime: null });
         return this;
     }
 
@@ -341,22 +339,51 @@ declare abstract class AIAgentBaseStats {
         const existing = this.timers.get(key);
         if (!existing || existing.startTime === null || existing.endTime !== null) return this;
 
-        this.timers.set(key, { ...existing, endTime: defaultStatsClock.now() });
+        this.timers.set(key, { ...existing, endTime: performance.now() });
         return this;
     }
 
-    protected getDuration(key: string): number | null {
+    getTimer(key: string): TimerReading {
         const timer = this.timers.get(key);
-        if (!timer || timer.startTime === null || timer.endTime === null) return null;
-        return timer.endTime - timer.startTime;
+        if (!timer || timer.startTime === null) return { startAt: null, endedAt: null, duration: null };
+        return {
+            startAt: timer.startTime,
+            endedAt: timer.endTime,
+            duration: timer.endTime === null ? null : timer.endTime - timer.startTime,
+        };
+    }
+
+    protected createPayload(value: string | number, params?: StatsPayloadParams): AIAgentStatPayload {
+        const payload: AIAgentStatPayload = {
+            key: this.getMetricKey(),
+            value: String(value),
+        };
+
+        const conversationId = params?.conversationId ?? this.conversationId ?? undefined;
+        if (conversationId !== undefined) payload.conversation_id = conversationId;
+
+        if (this.errorCode !== null) {
+            payload.error_code = this.errorCode;
+            payload.error_description = this.errorDescription ?? '';
+        }
+
+        const extra = dropNullish({
+            ...this.extraData,
+            ...params?.extra,
+        });
+        if (Object.keys(extra).length > 0) payload.extra = extra;
+
+        return payload;
     }
 
     isCommitted(): boolean {
         return this.committed;
     }
 
-    protected abstract buildPayload(): AIAgentStatPayload | null;
-    protected abstract getMetricKey(): string;
+    /** Consume without emitting: the metric counts as committed for once-per-session gating. */
+    discard(): void {
+        this.committed = true;
+    }
 
     commit(): boolean {
         if (this.committed || !this.commitCallback) {
@@ -364,14 +391,10 @@ declare abstract class AIAgentBaseStats {
         }
 
         const payload = this.buildPayload();
-
-        if (!payload) {
-            return false;
-        }
+        if (!payload) return false;
 
         this.committed = true;
-        const result = this.commitCallback(AI_AGENT_STAT_TYPE, payload);
-        return result;
+        return this.commitCallback(AI_AGENT_STAT_TYPE, payload);
     }
 }
 
@@ -587,7 +610,6 @@ declare interface AIAgentConversationContextValue {
         messages: ChatSDKBaseMessage[];
         newMessages: ChatSDKBaseMessage[];
         initialized: boolean;
-        subscribeMessageEvents: (listener: (event: ConversationMessageEvent) => void) => () => void;
         loadPrevious: () => Promise<void>;
         loadNext: () => Promise<void>;
         sendUserMessage: (params: ChatSDKUserMessageCreateParams) => Promise<ChatSDKUserMessage>;
@@ -608,6 +630,8 @@ declare interface AIAgentConversationContextValue {
         };
         input: InputState;
     };
+
+    _statsEnabled: boolean;
 }
 
 declare interface AIAgentConversationListContextValue {
@@ -728,6 +752,9 @@ declare interface AIAgentInterface {
     /** @internal Schedules metrics work that should only start while the app is foregrounded. */
     readonly scheduleForegroundTask?: ForegroundTaskScheduler;
 
+    /** @internal Watches whether the app was backgrounded during a stats measurement window. */
+    readonly watchBackgrounded?: BackgroundedWatcher;
+
     /** @internal Stats trackers owned by this SDK instance. */
     readonly statsTrackers: AIAgentStatsTrackers;
 
@@ -749,6 +776,8 @@ declare interface AIAgentInterface {
     updateContext: (channelUrl: string, context: Record<string, string>) => Promise<ContextObject>;
     /** Retrieves the context data for the specified channel */
     getContextObject: (channelUrl: string) => Promise<ContextObject>;
+    /** Requests a nudge message to be shown above the launcher. Fire-and-forget: the result is only broadcast to onNudgeMessageReceived subscribers */
+    requestNudgeMessage: (params: RequestNudgeMessageParams) => Promise<void>;
     /** Clears memories saved for the current user */
     clearUserMemories: (params?: ClearUserMemoriesParams) => Promise<void>;
 
@@ -759,7 +788,7 @@ declare interface AIAgentInterface {
     setUserMemoryState: (params: SetUserMemoryStateParams) => Promise<MemoryInfo>;
 
     /** @internal Initializes a conversation on the channel if needed (AI Agent channel without conversation). */
-    initConversationIfNeeded: (channel: ChatSDKGroupChannel) => Promise<void>;
+    initConversationIfNeeded: (channel: ChatSDKGroupChannel, params?: { initialUserMessage?: string }) => Promise<void>;
 
     /** @internal Live metric handler; bridged from {@link AIAgentClientHandlers.onLiveMetric}. */
     onLiveMetric?: LiveMetricDispatch;
@@ -770,6 +799,8 @@ declare interface AIAgentInterface {
     /** Disposes all resources held by this instance (WebSocket, desk auth, event handlers). */
     dispose: () => void;
 
+    /** Registers a handler for nudge message responses */
+    onNudgeMessageReceived: (handler: (response: NudgeMessageResponse) => void) => () => void;
     /** Registers a handler for messenger settings updates */
     onMessengerSettingsUpdated: (handler: (params: MessengerSettingsUpdatedParams) => void) => () => void;
     /** Registers a handler for active channel updates */
@@ -830,6 +861,8 @@ declare interface AIAgentMessengerSessionRef {
         /** Patches the context of a specific conversation by aiAgentId and channelUrl. */
         (aiAgentId: string, channelUrl: string, context: Record<string, string>): Promise<ContextObject>;
     };
+    /** Requests a nudge message to be shown above the launcher. Fire-and-forget: the response is not exposed. */
+    requestNudgeMessage: (params: RequestNudgeMessageParams) => Promise<void>;
 }
 
 export declare type AIAgentProps = PropsWithChildren<{
@@ -1136,6 +1169,7 @@ declare interface AIAgentStringSet {
         a11y_send_message: string;
         a11y_attach_file: string;
         a11y_close_messenger: string;
+        a11y_dismiss_nudge_message: string;
         a11y_expand_messenger: string;
         a11y_collapse_messenger: string;
         a11y_connect_agent: string;
@@ -1278,23 +1312,40 @@ declare interface AIAgentStringSet {
     };
 }
 
-declare class AIEVAuthExpiredUnhandledStatsTracker {
-    private readonly callback: StatsAppendCallback;
-
-    constructor(callback: StatsAppendCallback) {
-        this.callback = callback;
-    }
-
+/**
+ * Spec: aiev_auth_expired_unhandled
+ *
+ * Records a server EXTERNAL_AUTH_TOKEN_EXPIRED event that the SDK cannot
+ * deliver to the host app.
+ *
+ * Timeline:
+ * - Trigger when the SDK receives the external-token-expired AIEV payload.
+ * - Commit immediately if payload parsing fails or no host callback/delegate
+ *   can receive the event.
+ *
+ * Payload:
+ * - value: failure_reason = payload_parse_failed | callback_not_found.
+ * - extra.agent_id: AI Agent id when available.
+ *
+ * Policy:
+ * - Fire-and-forget; one failed event produces one stat.
+ * - Successful delivery to the host app is not recorded by this metric.
+ */
+declare class AIEVAuthExpiredUnhandledStatsTracker extends StatsTrackerBase {
     onPayloadParseFailed(params: { aiAgentId: string }): void {
-        append(this.callback, METRIC_KEY_AIEV_AUTH_EXPIRED_UNHANDLED, 'payload_parse_failed', {
-            extra: { agent_id: params.aiAgentId },
-        });
+        new AIEVAuthExpiredUnhandledStats()
+        .setReason('payload_parse_failed')
+        .setAIAgentId(params.aiAgentId)
+        .setCommitCallback(this.commitCallback)
+        .commit();
     }
 
     onCallbackNotFound(params: { aiAgentId: string }): void {
-        append(this.callback, METRIC_KEY_AIEV_AUTH_EXPIRED_UNHANDLED, 'callback_not_found', {
-            extra: { agent_id: params.aiAgentId },
-        });
+        new AIEVAuthExpiredUnhandledStats()
+        .setReason('callback_not_found')
+        .setAIAgentId(params.aiAgentId)
+        .setCommitCallback(this.commitCallback)
+        .commit();
     }
 
     clear(): void {}
@@ -1344,8 +1395,15 @@ declare interface AttachmentRules {
     getUploadSizeLimitInMB: (mimeType: string) => number;
 }
 
+declare type AuthState = 'idle' | 'in_progress' | 'completed' | 'failed';
+
+declare type AuthState_2 = 'idle' | 'in_progress' | 'completed' | 'failed';
+
 declare interface AuthTokenRefreshedParams {}
 
+/** Starts watching foreground state; the returned function stops watching and reports whether the app was backgrounded while watched. */
+declare type BackgroundedWatcher = () => () => boolean;
+
 declare abstract class BaseCommand {
     abstract type: CommandType;
     payload: any;
@@ -1389,7 +1447,7 @@ declare type CachedMessengerSettings = Omit<MessengerSettingsResponse, 'memory'>
 export declare type ChallengeActionParams = {
     key: string;
     requestId: string;
-    action: 'submit' | 'cancel';
+    action: 'submit' | 'cancel' | 'fail';
     data?: Record<string, unknown>;
 };
 
@@ -1407,8 +1465,6 @@ declare type ChatSDKBaseChannelCollectionEventHandler = BaseChannelCollectionEve
 
 declare type ChatSDKBaseMessage = BaseMessage;
 
-declare type ChatSDKCollectionEventSource = CollectionEventSource;
-
 declare type ChatSDKConversation = Conversation_2;
 
 declare type ChatSDKConversationStatus = ConversationStatus;
@@ -1491,6 +1547,9 @@ declare interface ColorSet {
     csat: {
         background: string;
     };
+    conversation: {
+        headerProfileSkeleton: string;
+    };
     memoryDialog: {
         titleText: string;
         markdownBodyText: string;
@@ -1529,6 +1588,7 @@ declare interface CommandPayloads {
     [CommandType.ActiveChannelUpdated]: ActiveChannelUpdatedParams;
     [CommandType.AnonymousSessionTokenExpired]: undefined;
     [CommandType.AuthTokenRefreshed]: AuthTokenRefreshedParams;
+    [CommandType.NudgeMessageReceived]: NudgeMessageResponse;
 }
 
 export declare const Commands = {
@@ -1537,6 +1597,7 @@ export declare const Commands = {
     ActiveChannelUpdated: (params: ActiveChannelUpdatedParams) => new ActiveChannelUpdatedCommand(params),
     AnonymousSessionTokenExpired: () => new AnonymousSessionTokenExpiredCommand(),
     AuthTokenRefreshed: () => new AuthTokenRefreshedCommand(),
+    NudgeMessageReceived: (response: NudgeMessageResponse) => new NudgeMessageReceivedCommand(response),
 };
 
 declare enum CommandType {
@@ -1545,6 +1606,7 @@ declare enum CommandType {
     ActiveChannelUpdated = 'active.channel.updated',
     AnonymousSessionTokenExpired = 'anon.token.expired',
     AuthTokenRefreshed = 'auth.token.refreshed',
+    NudgeMessageReceived = 'nudge.message.received',
 }
 
 export declare interface ConnectionDelayDialogProps {
@@ -1590,7 +1652,7 @@ declare interface ContextObject {
     context: Record<string, string>;
 }
 
-export declare const Conversation: ({ children, onNavigateToConversationList, channelUrl, onClearChannelUrl, shouldMarkAsRead, shouldInitializeConversation, announcementsEnabled, conversationStatsEnabled, initialFocusTarget, style, closedChannelUrl, onClearClosedChannelUrl, }: ConversationProps) => JSX.Element;
+export declare const Conversation: ({ children, onNavigateToConversationList, channelUrl, onClearChannelUrl, shouldMarkAsRead, shouldInitializeConversation, initialUserMessage, announcementsEnabled, conversationStatsEnabled, initialFocusTarget, style, closedChannelUrl, onClearClosedChannelUrl, }: ConversationProps) => JSX.Element;
 
 export declare const ConversationContext: Context<ConversationContextValue | null>;
 
@@ -1602,12 +1664,12 @@ declare interface ConversationContextProps {
     conversationStatsEnabled?: boolean;
     /** @internal */
     shouldInitializeConversation?: boolean;
+    initialUserMessage?: string;
 }
 
 export declare const ConversationContextProvider: ({ children, ...props }: PropsWithChildren<ConversationContextProps>) => JSX.Element;
 
 declare interface ConversationContextValue extends AIAgentConversationContextValue {
-    conversationStatsEnabled: boolean;
     scrollSource: ConversationScrollContextValue;
     goToActiveConversation: () => Promise<void>;
     onNavigateToConversationList?: () => void;
@@ -1704,234 +1766,326 @@ declare interface ConversationHeaderTemplateProps {
 
 declare type ConversationInitialFocusTarget = 'messageInput';
 
+declare type ConversationInitialRenderMeasure = {
+    channelUrl: string;
+    pageRenderState: PageRenderState;
+};
+
 declare class ConversationInitialRenderStats extends AIAgentBaseStats {
+    private channelUrl: string | null = null;
     private presentMethod: PresentMethod = 'direct_present';
 
+    setChannelUrl(url: string): this {
+        this.channelUrl = url;
+        return this;
+    }
+
     setPresentMethod(method: PresentMethod): this {
         this.presentMethod = method;
         return this;
     }
 
+    resetPageRenderSpan(): this {
+        this.timers.delete(DurationKey.PAGE_RENDER);
+        this.timers.delete(DurationKey.PAGE_RENDER_FROM_CACHE);
+        this.timers.delete(DurationKey.GET_CHANNEL);
+        this.timers.delete(DurationKey.GET_MESSAGES);
+        this.conversationId = null;
+        this.channelUrl = null;
+        this.errorCode = null;
+        this.errorDescription = null;
+        return this;
+    }
+
     protected getMetricKey(): string {
         return METRIC_KEY_CONVERSATION_INITIAL_RENDER;
     }
 
     protected buildPayload(): AIAgentStatPayload | null {
-        const authDuration = this.getDuration(DurationKey.AUTH);
-        const getChannelDuration = this.getDuration(DurationKey.GET_CHANNEL);
-        const getMessagesDuration = this.getDuration(DurationKey.GET_MESSAGES);
-        const totalDurationFromCache = this.getDuration(DurationKey.TOTAL_DURATION_FROM_CACHE);
-        const totalDuration = this.getDuration(DurationKey.TOTAL_DURATION);
+        const auth = this.getTimer(DurationKey.AUTH);
+        const pageRender = this.getTimer(DurationKey.PAGE_RENDER);
+        const fromCache = this.getTimer(DurationKey.PAGE_RENDER_FROM_CACHE);
 
-        const extra: Record<string, unknown> = {
-            ...this.extraData,
-            present_method: this.presentMethod,
-            ...(authDuration !== null && { [DurationKey.AUTH]: authDuration }),
-            ...(getChannelDuration !== null && { [DurationKey.GET_CHANNEL]: getChannelDuration }),
-            ...(getMessagesDuration !== null && { [DurationKey.GET_MESSAGES]: getMessagesDuration }),
-            ...(totalDurationFromCache !== null && { [DurationKey.TOTAL_DURATION_FROM_CACHE]: totalDurationFromCache }),
-        };
+        // Only the auth-error early commit legitimately lacks a page render duration;
+        // any other commit without it is an incomplete measurement and must not emit.
+        if (pageRender.duration === null && (this.errorCode === null || auth.duration === null)) return null;
+
+        // The timers race freely; subtracting the overlap counts the auth wait exactly once.
+        const pageRenderDuration = pageRender.duration === null ? 0 : pageRender.duration - overlapMs(auth, pageRender);
+        const fromCacheDuration = fromCache.duration === null ? null : fromCache.duration - overlapMs(auth, fromCache);
 
-        return createStatsPayload(this.getMetricKey(), totalDuration ?? 0, {
-            conversationId: this.conversationId ?? undefined,
-            error: this.errorCode !== null ? { code: this.errorCode, message: this.errorDescription ?? '' } : undefined,
-            extra,
+        return this.createPayload((auth.duration ?? 0) + pageRenderDuration, {
+            extra: {
+                channel_url: this.channelUrl,
+                present_method: this.presentMethod,
+                [DurationKey.AUTH]: auth.duration,
+                [DurationKey.GET_CHANNEL]: this.getTimer(DurationKey.GET_CHANNEL).duration,
+                [DurationKey.GET_MESSAGES]: this.getTimer(DurationKey.GET_MESSAGES).duration,
+                [DurationKey.PAGE_RENDER_FROM_CACHE]: fromCacheDuration,
+            },
         });
     }
 }
 
 /**
- * Manages ConversationInitialRenderStats lifecycle and encapsulates tracking logic.
+ * One Conversation entry attempt. Owns the page render phase machine; the tracker
+ * owns the cross-attempt policy (auth span, supersession, one commit per entry).
+ *
+ * Async-boundary events carry the channel identity so a result delivered to the
+ * wrong span is rejected instead of consuming a phase transition.
+ *
+ * Timers record their own event boundaries and race freely against auth; the
+ * metric subtracts the overlap at payload time, so event ordering needs no
+ * orchestration here.
  */
-declare class ConversationInitialRenderStatsTracker {
-    private readonly commitCallback: StatsAppendCallback;
-    private apiResultReceived = false;
-    private channelUrl?: string;
-    private consumed = false;
-    private consumedByAuthError = false;
-    private presentMethod: PresentMethod = 'direct_present';
-    private renderedAfterApiResult = false;
-    private stats: ConversationInitialRenderStats | null = null;
+declare class ConversationInitialRenderStatsSpan extends StatsSpanBase<
+ConversationInitialRenderStats,
+ConversationInitialRenderMeasure
+> {
+    protected measure: ConversationInitialRenderMeasure;
 
-    constructor(commitCallback: StatsAppendCallback) {
-        this.commitCallback = commitCallback;
+    constructor(stats: ConversationInitialRenderStats | null, channelUrl: string, visible: boolean) {
+        super(stats, visible);
+        this.measure = { channelUrl, pageRenderState: 'initialized' };
+        this.stats
+        ?.setChannelUrl(channelUrl)
+        .startTimer(DurationKey.PAGE_RENDER)
+        .startTimer(DurationKey.PAGE_RENDER_FROM_CACHE);
     }
 
-    private getOrCreateStats(): ConversationInitialRenderStats | null {
-        if (this.consumed) return null;
-        if (this.stats?.isCommitted()) {
-            this.consumed = true;
-            return null;
-        }
-        if (!this.stats) {
-            this.stats = new ConversationInitialRenderStats()
-            .setCommitCallback(this.commitCallback)
-            .setPresentMethod(this.presentMethod);
-            this.apiResultReceived = false;
-            this.renderedAfterApiResult = false;
-        }
-        return this.stats;
+    onGetChannelStart(channelUrl: string): void {
+        if (!this.stats || channelUrl !== this.measure.channelUrl || this.measure.pageRenderState !== 'initialized') return;
+
+        this.stats.startTimer(DurationKey.GET_CHANNEL);
+        this.measure.pageRenderState = 'channel_fetching';
     }
 
-    private getActiveStats(): ConversationInitialRenderStats | null {
-        if (this.consumed || !this.stats || this.stats.isCommitted()) return null;
-        return this.stats;
+    onGetChannelComplete(channelUrl: string, conversationId?: number): void {
+        if (!this.stats || channelUrl !== this.measure.channelUrl || this.measure.pageRenderState !== 'channel_fetching')
+        return;
+
+        this.stats.stopTimer(DurationKey.GET_CHANNEL).setConversationId(conversationId);
+        this.measure.pageRenderState = 'channel_fetched';
     }
 
-    private matchesChannelUrl(channelUrl?: string): boolean {
-        return channelUrl === undefined || this.channelUrl === undefined || channelUrl === this.channelUrl;
+    onGetChannelError(channelUrl: string, error: Error): void {
+        if (!this.stats || channelUrl !== this.measure.channelUrl || this.measure.pageRenderState !== 'channel_fetching')
+        return;
+
+        this.stats.stopTimer(DurationKey.GET_CHANNEL).setError(error).stopTimer(DurationKey.PAGE_RENDER);
+        this.measure.pageRenderState = 'channel_failed';
+        this.tryFinalize();
     }
 
-    private pinChannelUrl(channelUrl?: string): boolean {
-        if (channelUrl === undefined) return true;
-        if (!this.matchesChannelUrl(channelUrl)) return false;
+    onGetMessagesStart(): void {
+        if (!this.stats || this.measure.pageRenderState !== 'channel_fetched') return;
 
-        this.channelUrl = channelUrl;
-        this.stats?.setChannelUrl(channelUrl);
-        return true;
+        this.stats.startTimer(DurationKey.GET_MESSAGES);
+        this.measure.pageRenderState = 'messages_fetching';
     }
 
-    private consume(commitResult: boolean): boolean {
-        if (commitResult) {
-            this.consumed = true;
+    onGetMessagesCacheComplete(channelUrl: string, error: Error | null): void {
+        if (
+        !this.stats ||
+        channelUrl !== this.measure.channelUrl ||
+        error ||
+        this.measure.pageRenderState !== 'messages_fetching'
+        ) {
+            return;
         }
-        return commitResult;
-    }
 
-    private commitIfReady(channelUrl?: string): boolean {
-        if (this.consumed || !this.stats || this.stats.isCommitted()) return true;
-        if (!this.matchesChannelUrl(channelUrl)) return false;
-        if (!this.apiResultReceived || !this.renderedAfterApiResult) return false;
-        return this.consume(this.stats.stopTimer(DurationKey.TOTAL_DURATION).commit());
+        this.stats.stopTimer(DurationKey.PAGE_RENDER_FROM_CACHE);
     }
 
-    start(channelUrl?: string): void {
-        const stats = this.getOrCreateStats();
-        if (!stats || !this.pinChannelUrl(channelUrl)) return;
+    onGetMessagesComplete(channelUrl: string, error: Error | null): void {
+        if (!this.stats || channelUrl !== this.measure.channelUrl || this.measure.pageRenderState !== 'messages_fetching')
+        return;
 
-        stats.startTimer(DurationKey.TOTAL_DURATION).startTimer(DurationKey.TOTAL_DURATION_FROM_CACHE);
+        this.stats.stopTimer(DurationKey.GET_MESSAGES).setError(error);
+        this.measure.pageRenderState = 'messages_fetching_completed';
     }
 
-    onAuthStart(): void {
-        if (this.consumedByAuthError) {
-            this.clear();
-        }
-        this.getOrCreateStats()?.startTimer(DurationKey.AUTH);
+    onRendered(): void {
+        if (!this.stats || this.measure.pageRenderState !== 'messages_fetching_completed') return;
+
+        this.stats.stopTimer(DurationKey.PAGE_RENDER);
+        this.tryFinalize();
     }
 
-    onAuthComplete(): void {
-        this.getActiveStats()?.stopTimer(DurationKey.AUTH);
+    onRenderDiscarded(): void {
+        if (!this.stats || this.measure.pageRenderState !== 'messages_fetching_completed') return;
+
+        this.stats.discard();
+        this.stats = null;
     }
 
-    onAuthError(error: Error): void {
-        const stats = this.getActiveStats();
-        if (stats) {
-            const committed = this.consume(
-            stats
-            .stopTimer(DurationKey.AUTH)
-            .setError(error instanceof SendbirdError ? error.code : undefined, error.message)
-            .stopTimer(DurationKey.TOTAL_DURATION)
-            .commit(),
-            );
-            if (committed) {
-                this.consumedByAuthError = true;
-            }
-        }
+    /** Auth settled while this span was measuring; a finalize that waited on in-flight auth can proceed. */
+    onAuthSettled(): void {
+        this.tryFinalize();
     }
 
-    onGetChannelStart(channelUrl?: string): void {
-        const stats = this.getActiveStats();
-        if (!stats || !this.pinChannelUrl(channelUrl)) return;
+    /** Commit once both facts exist: the page render ended (render or failure) and auth is not in flight. */
+    private tryFinalize(): void {
+        if (!this.stats) return;
+        if (this.stats.getTimer(DurationKey.PAGE_RENDER).endedAt === null) return;
 
-        stats.startTimer(DurationKey.GET_CHANNEL);
+        const auth = this.stats.getTimer(DurationKey.AUTH);
+        if (auth.startAt !== null && auth.endedAt === null) return;
+
+        if (this.measure.pageRenderState === 'channel_failed') {
+            // Early error commit (iOS/Android convergence) bypasses the visibility gate, like onAuthError.
+            this.stats.commit();
+            this.stats = null;
+            return;
+        }
+        this.commitOrDefer();
     }
+}
 
-    onGetChannelComplete(params?: number | GetChannelCompleteParams): void {
-        const channelUrl = typeof params === 'object' ? params.channelUrl : undefined;
-        const conversationId = typeof params === 'object' ? params.conversationId : params;
-        const stats = this.getActiveStats();
-        if (!stats || !this.pinChannelUrl(channelUrl)) return;
+/**
+ * Spec: conversation_initial_render
+ *
+ * Measures the first Conversation screen render as the sum of auth and the
+ * page render span required before the first remote-rendered message list frame.
+ *
+ * Timeline:
+ * - Resolve present method.
+ * - Track auth independently; it can start before any Conversation screen exists.
+ * - Start a span when the Conversation screen display lifecycle begins.
+ * - Track get-channel and get-messages phases on the span.
+ * - Capture cache completion as best-effort total_duration_from_cache_ms, but
+ *   do not commit until the remote render path completes.
+ * - Commit on the first remote rendered frame. While the screen is hidden the
+ *   measurement still freezes at that frame, but emission is deferred until the
+ *   screen becomes visible.
+ * - Discard (no payload) when the rendered frame was deferred by a
+ *   backgrounded page/app; the session stays consumed.
+ * - Confluence/iOS/Android converge on early error commit for auth or
+ *   get-channel failures that prevent Conversation entry.
+ * - Cache message-list failure is not terminal; remote message-list failure
+ *   stores error data, and the rendered signal commits the initial render attempt.
+ *
+ * Payload:
+ * - value: total_duration_ms.
+ * - extra.auth_duration_ms, get_channel_duration_ms, get_messages_duration_ms.
+ * - extra.total_duration_from_cache_ms, present_method, channel_url.
+ *
+ * Method call order:
+ * - Resolve present method - setPresentMethod()
+ * - Start auth - onAuthStart()
+ * - Complete auth - onAuthComplete()
+ * - Fail auth - onAuthError()
+ * - Enter display lifecycle - startSpan(channelUrl)
+ * - Screen visibility change - setVisible(visible)
+ * - Start get channel - span.onGetChannelStart(channelUrl)
+ * - Complete get channel - span.onGetChannelComplete(channelUrl, conversationId)
+ * - Fail get channel - span.onGetChannelError(channelUrl, error)
+ * - Start remote message list - span.onGetMessagesStart()
+ * - Complete cache message list - span.onGetMessagesCacheComplete(channelUrl, error)
+ * - Complete remote message list - span.onGetMessagesComplete(channelUrl, error)
+ * - Render conversation - span.onRendered()
+ * - Render deferred by background - span.onRenderDiscarded()
+ * - Abandon entry attempt - span.cancel()
+ * - Logout (deauthenticate/dispose) - clear()
+ *
+ * Policy:
+ * - Session-scoped; collect at most once per authenticated session. Only the
+ *   logout-time clear() reopens measurement: re-entering a conversation after
+ *   a commit is a warm navigation and is deliberately not re-measured.
+ * - value = auth + (page render − overlap): the timers record their own event
+ *   boundaries and race freely, and the metric subtracts the overlapping
+ *   interval at payload time, so the auth wait is counted exactly once in any
+ *   ordering — a render, cache completion, or channel failure landing mid-auth
+ *   included; the cache extra derives the same way. The commit waits for
+ *   in-flight auth to settle, since the value needs the auth duration.
+ * - startSpan supersedes the previous span: the old span becomes non-recording
+ *   and the page render phase restarts. Auth data carries over to the new span.
+ * - After success or error commit, new spans are born non-recording until clear().
+ * - An auth failure before any span started allows a fresh measurement on retry.
+ * - A backgrounded page/app pauses requestAnimationFrame, so a render signal
+ *   arriving after background time would fold the idle dwell into
+ *   total_duration_ms. Such samples are discarded without a payload
+ *   (web-vitals convention) and consume the session like a commit.
+ * - Measurement is independent of screen visibility: a hidden (launcher-closed
+ *   or route-inactive) preload keeps measuring with the same render criterion,
+ *   so visibility toggles never tear a measurement. Visibility only gates
+ *   emission: a render completed while hidden commits the moment the screen
+ *   becomes visible (setVisible), and a preload that is never shown is
+ *   cancelled with its span and never emitted.
+ */
+declare class ConversationInitialRenderStatsTracker extends SpanStatsTrackerBase<ConversationInitialRenderStatsSpan> {
+    private stats: ConversationInitialRenderStats | null = null;
+    private authState: AuthState = 'idle';
+    private presentMethod: PresentMethod = 'direct_present';
 
-        stats.stopTimer(DurationKey.GET_CHANNEL);
-        if (conversationId !== undefined) {
-            stats.setConversationId(conversationId);
+    private getOrCreateStats(): ConversationInitialRenderStats | null {
+        if (this.stats?.isCommitted()) return null;
+        if (!this.stats) {
+            this.stats = new ConversationInitialRenderStats()
+            .setCommitCallback(this.commitCallback)
+            .setPresentMethod(this.presentMethod);
         }
-        stats.startTimer(DurationKey.GET_MESSAGES);
+        return this.stats;
     }
 
-    onGetChannelError(params: Error | GetChannelErrorParams): void {
-        const channelUrl = params instanceof Error ? undefined : params.channelUrl;
-        const error = params instanceof Error ? params : params.error;
-        const stats = this.getActiveStats();
-        if (stats && this.pinChannelUrl(channelUrl)) {
-            this.consume(
-            stats
-            .stopTimer(DurationKey.GET_CHANNEL)
-            .setError(error instanceof SendbirdError ? error.code : undefined, error.message)
-            .stopTimer(DurationKey.TOTAL_DURATION)
-            .commit(),
-            );
-        }
+    private getActiveStats(): ConversationInitialRenderStats | null {
+        if (!this.stats || this.stats.isCommitted()) return null;
+        return this.stats;
     }
 
-    onCacheResult(error: Error | null): void {
-        const stats = this.getActiveStats();
-        if (stats) {
-            if (error) {
-                stats.setError(error instanceof SendbirdError ? error.code : undefined, error.message);
-            }
-            stats.stopTimer(DurationKey.TOTAL_DURATION_FROM_CACHE);
-        }
+    setPresentMethod(method: PresentMethod): void {
+        this.presentMethod = method;
+        this.getActiveStats()?.setPresentMethod(method);
     }
 
-    onApiResult(error: Error | null): void {
-        const stats = this.getActiveStats();
-        if (stats) {
-            if (error) {
-                this.consume(
-                stats
-                .setError(error instanceof SendbirdError ? error.code : undefined, error.message)
-                .stopTimer(DurationKey.TOTAL_DURATION)
-                .stopTimer(DurationKey.GET_MESSAGES)
-                .commit(),
-                );
-                return;
-            }
-            this.apiResultReceived = true;
-            this.renderedAfterApiResult = false;
-            stats.stopTimer(DurationKey.GET_MESSAGES);
-            this.commitIfReady();
+    onAuthStart(): void {
+        if (this.stats?.isCommitted()) {
+            if (this.authState !== 'failed' || this.activeSpan !== null) return;
+            // Auth failed before any Conversation entry: retrying auth starts a new measurement.
+            this.stats = null;
+            this.authState = 'idle';
         }
-    }
+        if (this.authState !== 'idle') return;
 
-    setChannelUrl(url: string): void {
-        this.pinChannelUrl(url);
+        this.authState = 'in_progress';
+        this.getOrCreateStats()?.startTimer(DurationKey.AUTH);
     }
 
-    commitPending(): boolean {
-        const stats = this.getActiveStats();
-        return stats ? this.consume(stats.stopTimer(DurationKey.TOTAL_DURATION).commit()) : true;
+    onAuthComplete(): void {
+        if (this.authState === 'in_progress') {
+            this.authState = 'completed';
+            this.getActiveStats()?.stopTimer(DurationKey.AUTH);
+        }
+
+        this.activeSpan?.onAuthSettled();
     }
 
-    markRendered(channelUrl?: string): boolean {
-        if (!this.matchesChannelUrl(channelUrl)) return false;
+    onAuthError(error: Error): void {
+        if (this.authState !== 'in_progress') return;
 
-        this.renderedAfterApiResult = true;
-        return this.commitIfReady(channelUrl);
+        this.authState = 'failed';
+        this.getActiveStats()?.stopTimer(DurationKey.AUTH).setError(error).commit();
+        // Keep the superseded reference: it marks that a span existed in this era,
+        // which blocks the auth-retry reset above.
+        this.activeSpan?.cancel();
     }
 
-    setPresentMethod(method: PresentMethod): void {
-        this.presentMethod = method;
-        this.getActiveStats()?.setPresentMethod(method);
+    startSpan(channelUrl: string): ConversationInitialRenderStatsSpan {
+        const superseded = this.activeSpan;
+        superseded?.cancel();
+
+        const stats = this.getOrCreateStats();
+        if (stats && superseded) stats.resetPageRenderSpan();
+
+        this.activeSpan = new ConversationInitialRenderStatsSpan(stats, channelUrl, this.visible);
+        return this.activeSpan;
     }
 
     clear(): void {
+        this.activeSpan?.cancel();
+        this.activeSpan = null;
         this.stats = null;
-        this.apiResultReceived = false;
-        this.channelUrl = undefined;
-        this.consumed = false;
-        this.consumedByAuthError = false;
-        this.renderedAfterApiResult = false;
+        this.authState = 'idle';
     }
 }
 
@@ -2065,153 +2219,263 @@ declare interface ConversationListHeaderTemplateProps {
     titleAlign?: 'start' | 'center' | 'end';
 }
 
-declare class ConversationListInitialRenderStatsTracker {
-    private readonly callback: StatsAppendCallback;
-    private readonly clock: StatsClock;
-    private measurement = createEmptyProgress();
-    private renderedCommitted = false;
-    private startedAt: number | null = null;
-    private listStartedAt: number | null = null;
-    private authStartedAt: number | null = null;
-    private authDuration: number | null = null;
-    private listDuration: number | null = null;
+declare type ConversationListInitialRenderMeasure = {
+    listStarted: boolean;
+    listCompleted: boolean;
+};
+
+declare class ConversationListInitialRenderStats extends AIAgentBaseStats {
     private presentMethod: PresentMethod = 'direct_present';
-    private committed = false;
 
-    constructor(callback: StatsAppendCallback, options?: TrackerOptions) {
-        this.callback = callback;
-        this.clock = getClock(options);
+    setPresentMethod(method: PresentMethod): this {
+        this.presentMethod = method;
+        return this;
     }
 
-    onInitializeStart(): void {
-        if (this.measurement.rendered) return;
-        if (this.measurement.initialized) {
-            this.clearMeasurementState();
-        }
-        this.renderedCommitted = false;
-        this.startMeasurement();
+    resetPageRenderSpan(): this {
+        this.timers.delete(DurationKey.PAGE_RENDER);
+        this.timers.delete(DurationKey.GET_LIST);
+        this.errorCode = null;
+        this.errorDescription = null;
+        return this;
     }
 
-    onListRequestStart(): void {
-        if (this.measurement.listStarted && !this.measurement.listCompleted && !this.measurement.rendered) {
-            this.clearMeasurementState();
-        }
-
-        this.markListRequestStartOnce();
+    protected getMetricKey(): string {
+        return METRIC_KEY_CONVERSATION_LIST_INITIAL_RENDER;
     }
 
-    onListRequestComplete(): void {
-        this.markListRequestCompleteOnce();
-    }
+    protected buildPayload(): AIAgentStatPayload | null {
+        const auth = this.getTimer(DurationKey.AUTH);
+        const pageRender = this.getTimer(DurationKey.PAGE_RENDER);
+        const listDuration = this.getTimer(DurationKey.GET_LIST).duration;
 
-    onRendered(): void {
-        this.markRenderedOnce();
-    }
+        // Only the auth-error early commit legitimately lacks a page render duration;
+        // any other commit without it is an incomplete measurement and must not emit.
+        if (pageRender.duration === null && (this.errorCode === null || auth.duration === null)) return null;
 
-    setPresentMethod(method: PresentMethod): void {
-        this.presentMethod = method;
+        // The timers race freely; subtracting the overlap counts the auth wait exactly once.
+        const pageRenderDuration = pageRender.duration === null ? 0 : pageRender.duration - overlapMs(auth, pageRender);
+        const totalDuration = (auth.duration ?? 0) + pageRenderDuration;
+
+        return this.createPayload(totalDuration, {
+            extra: {
+                present_method: this.presentMethod,
+                [DurationKey.AUTH]: auth.duration,
+                [DurationKey.GET_LIST]: listDuration,
+            },
+        });
     }
+}
+
+/**
+ * One ConversationList entry attempt. Owns the list request phase; the tracker
+ * owns the cross-attempt policy (auth span, supersession, one commit per entry).
+ *
+ * Timers record their own event boundaries and race freely against auth; the
+ * metric subtracts the overlap at payload time, so event ordering needs no
+ * orchestration here.
+ */
+declare class ConversationListInitialRenderStatsSpan extends StatsSpanBase<
+ConversationListInitialRenderStats,
+ConversationListInitialRenderMeasure
+> {
+    protected measure: ConversationListInitialRenderMeasure = { listStarted: false, listCompleted: false };
 
-    start(presentMethod?: PresentMethod): void {
-        if (this.committed) return;
-        this.startedAt = this.clock.now();
-        if (presentMethod) this.presentMethod = presentMethod;
+    constructor(stats: ConversationListInitialRenderStats | null, visible: boolean) {
+        super(stats, visible);
+        this.stats?.startTimer(DurationKey.PAGE_RENDER);
     }
 
-    onAuthStart(): void {
-        if (this.committed) {
-            this.clearMeasurementState();
-            this.renderedCommitted = false;
-        }
-        this.authDuration = null;
-        this.authStartedAt = this.clock.now();
+    onListRequestStart(): void {
+        if (!this.stats || this.measure.listStarted) return;
+
+        // After a failed attempt cleared the timers via resetPageRenderSpan(), this
+        // re-baselines them to the retry so the earlier failure and downtime are excluded.
+        this.stats.startTimer(DurationKey.PAGE_RENDER);
+        this.stats.startTimer(DurationKey.GET_LIST);
+        this.measure.listStarted = true;
     }
 
-    onAuthComplete(): void {
-        if (this.committed || this.authDuration !== null) return;
-        if (this.authStartedAt === null) {
-            this.authDuration = 0;
+    onListRequestComplete(error?: unknown): void {
+        if (!this.stats || !this.measure.listStarted || this.measure.listCompleted) return;
+
+        if (error) {
+            // Post-auth failures are not collected; drop the in-flight attempt so a retry restarts clean.
+            this.stats.resetPageRenderSpan();
+            this.measure.listStarted = false;
             return;
         }
-        this.authDuration = this.clock.now() - this.authStartedAt;
-        this.authStartedAt = null;
+
+        this.stats.stopTimer(DurationKey.GET_LIST);
+        this.measure.listCompleted = true;
     }
 
-    markListRequestStart(): void {
-        if (this.committed) return;
-        if (this.startedAt === null) this.start();
-        this.listStartedAt = this.clock.now();
+    onRendered(): void {
+        if (!this.stats || !this.measure.listCompleted) return;
+
+        this.stats.stopTimer(DurationKey.PAGE_RENDER);
+        this.tryFinalize();
     }
 
-    markListRequestComplete(): void {
-        if (this.committed || this.listStartedAt === null) return;
-        this.listDuration = this.clock.now() - this.listStartedAt;
+    onRenderDiscarded(): void {
+        if (!this.stats || !this.measure.listCompleted) return;
+
+        this.stats.discard();
+        this.stats = null;
     }
 
-    markRendered(): void {
-        if (this.committed || this.startedAt === null) return;
-        this.committed = true;
-        append(this.callback, METRIC_KEY_CONVERSATION_LIST_INITIAL_RENDER, this.clock.now() - this.startedAt, {
-            extra: {
-                ...(this.authDuration !== null && { auth_duration_ms: this.authDuration }),
-                ...(this.listDuration !== null && { get_list_duration_ms: this.listDuration }),
-                present_method: this.presentMethod,
-            },
-        });
+    /** Auth settled while this span was measuring; a finalize that waited on in-flight auth can proceed. */
+    onAuthSettled(): void {
+        this.tryFinalize();
     }
 
-    clear(): void {
-        this.clearMeasurementState();
-        this.clearAuthState();
-        this.renderedCommitted = false;
+    /** Commit once both facts exist: the render happened and auth is not in flight. */
+    private tryFinalize(): void {
+        if (!this.stats) return;
+        if (this.stats.getTimer(DurationKey.PAGE_RENDER).endedAt === null) return;
+
+        const auth = this.stats.getTimer(DurationKey.AUTH);
+        if (auth.startAt !== null && auth.endedAt === null) return;
+
+        this.commitOrDefer();
     }
+}
+
+/**
+ * Spec: conversation_list_initial_render
+ *
+ * Measures the first ConversationList screen render as the sum of auth and the
+ * page render span required before the first rendered list frame.
+ *
+ * Timeline:
+ * - Track auth independently; it can start before the list screen exists.
+ * - Start a span when entering the display lifecycle.
+ * - Track the list request phase on the span.
+ * - Commit on the first rendered list frame. While the screen is hidden the
+ *   measurement still freezes at that frame, but emission is deferred until the
+ *   screen becomes visible.
+ * - Discard (no payload) when the rendered frame was deferred by a
+ *   backgrounded page/app; the session stays consumed.
+ *
+ * Method call order:
+ * - Resolve present method - setPresentMethod()
+ * - Start auth - onAuthStart()
+ * - Complete auth - onAuthComplete()
+ * - Fail auth - onAuthError()
+ * - Enter display lifecycle - startSpan()
+ * - Screen visibility change - setVisible(visible)
+ * - Start list request - span.onListRequestStart()
+ * - Complete list request - span.onListRequestComplete()
+ * - Fail list request - span.onListRequestComplete(error)
+ * - Render list - span.onRendered()
+ * - Render deferred by background - span.onRenderDiscarded()
+ * - Abandon entry attempt - span.cancel()
+ * - Logout (deauthenticate/dispose) - clear()
+ *
+ * Payload:
+ * - value: total_duration_ms.
+ * - extra.auth_duration_ms, get_list_duration_ms, present_method.
+ *
+ * Policy:
+ * - Session-scoped; collect at most once per authenticated session. Only the
+ *   logout-time clear() reopens measurement: re-entering the list after a
+ *   commit is a warm navigation and is deliberately not re-measured.
+ * - value = auth + (page render − overlap): both timers record their own event
+ *   boundaries and race freely, and the metric subtracts the overlapping
+ *   interval at payload time, so the auth wait is counted exactly once in any
+ *   ordering. The commit waits for in-flight auth to settle, since the value
+ *   needs the auth duration. A failed attempt re-baselines the page render
+ *   timer at its retry, excluding the failure and downtime.
+ * - startSpan supersedes the previous span: the old span becomes non-recording
+ *   and the page render phase restarts. Auth data carries over to the new span.
+ * - Success or auth failure closes collection until clear(). Post-auth failures
+ *   are not collected.
+ * - An auth failure before any span is recording drops the pending measurement;
+ *   an auth retry starts a new one.
+ * - A backgrounded page/app pauses requestAnimationFrame, so a render signal
+ *   arriving after background time would fold the idle dwell into
+ *   total_duration_ms. Such samples are discarded without a payload
+ *   (web-vitals convention) and consume the session like a commit.
+ * - Measurement is independent of screen visibility: a hidden (launcher-closed
+ *   or route-inactive) preload keeps measuring with the same render criterion,
+ *   so visibility toggles never tear a measurement. Visibility only gates
+ *   emission: a render completed while hidden commits the moment the screen
+ *   becomes visible (setVisible), and a preload that is never shown is
+ *   cancelled with its span and never emitted.
+ */
+declare class ConversationListInitialRenderStatsTracker extends SpanStatsTrackerBase<ConversationListInitialRenderStatsSpan> {
+    private stats: ConversationListInitialRenderStats | null = null;
+    private authState: AuthState_2 = 'idle';
+    private presentMethod: PresentMethod = 'direct_present';
 
-    private clearMeasurementState(): void {
-        this.startedAt = null;
-        this.listStartedAt = null;
-        this.listDuration = null;
-        this.committed = false;
-        this.measurement = createEmptyProgress();
+    private getOrCreateStats(): ConversationListInitialRenderStats | null {
+        if (this.stats?.isCommitted()) return null;
+        if (!this.stats) {
+            this.stats = new ConversationListInitialRenderStats()
+            .setCommitCallback(this.commitCallback)
+            .setPresentMethod(this.presentMethod);
+        }
+        return this.stats;
     }
 
-    private clearAuthState(): void {
-        this.authStartedAt = null;
-        this.authDuration = null;
+    private getActiveStats(): ConversationListInitialRenderStats | null {
+        if (!this.stats || this.stats.isCommitted()) return null;
+        return this.stats;
     }
 
-    private startMeasurement(): void {
-        if (this.measurement.initialized) return;
+    setPresentMethod(method: PresentMethod): void {
+        this.presentMethod = method;
+        this.getActiveStats()?.setPresentMethod(method);
+    }
 
-        this.clearMeasurementState();
-        this.start();
-        this.measurement.initialized = true;
+    onAuthStart(): void {
+        this.authState = 'in_progress';
+        this.getOrCreateStats()?.startTimer(DurationKey.AUTH);
     }
 
-    private markListRequestStartOnce(): void {
-        this.startMeasurement();
-        if (this.measurement.listStarted) return;
+    onAuthComplete(): void {
+        const wasInProgress = this.authState === 'in_progress';
+        this.authState = 'completed';
+        if (wasInProgress) this.getActiveStats()?.stopTimer(DurationKey.AUTH);
 
-        this.markListRequestStart();
-        this.measurement.listStarted = true;
+        this.activeSpan?.onAuthSettled();
     }
 
-    private markListRequestCompleteOnce(): void {
-        this.markListRequestStartOnce();
-        if (this.measurement.listCompleted) return;
+    onAuthError(error: Error): void {
+        const wasInProgress = this.authState === 'in_progress';
+        this.authState = 'failed';
+
+        const stats = this.getActiveStats();
+        if (!stats) return;
+        if (!this.activeSpan?.isRecording) {
+            // Auth failed before any span was recording: drop the pending measurement so an auth retry re-measures cleanly.
+            this.stats = null;
+            return;
+        }
+
+        if (wasInProgress) stats.stopTimer(DurationKey.AUTH);
 
-        this.markListRequestComplete();
-        this.measurement.listCompleted = true;
+        stats.setError(error).commit();
+        this.activeSpan.cancel();
     }
 
-    private markRenderedOnce(): void {
-        if (this.renderedCommitted) return;
+    startSpan(): ConversationListInitialRenderStatsSpan {
+        const superseded = this.activeSpan;
+        superseded?.cancel();
+
+        const stats = this.getOrCreateStats();
+        if (stats && superseded) stats.resetPageRenderSpan();
+        if (stats && this.authState === 'in_progress') stats.startTimer(DurationKey.AUTH);
 
-        this.startMeasurement();
-        if (this.measurement.rendered) return;
+        this.activeSpan = new ConversationListInitialRenderStatsSpan(stats, this.visible);
+        return this.activeSpan;
+    }
 
-        this.markRendered();
-        this.measurement.rendered = true;
-        this.renderedCommitted = true;
+    clear(): void {
+        this.activeSpan?.cancel();
+        this.activeSpan = null;
+        this.stats = null;
+        this.authState = 'idle';
     }
 }
 
@@ -2284,107 +2548,133 @@ export declare type ConversationListProps = PropsWithChildren<{
     conversationListFilter?: Partial<AIAgentGroupChannelFilter>;
     onOpenConversationView?: (channelUrl: string, status: 'open' | 'closed', options?: ConversationListOpenOptions) => void;
     announcementsEnabled?: boolean;
+    /** @default true */
     conversationListStatsEnabled?: boolean;
     /** Custom styles for the conversation list container. */
     style?: CSSProperties;
 }>;
 
-declare type ConversationMessageEvent = ConversationMessageEventPayload & { id: number };
-
-declare type ConversationMessageEventPayload =
-| {
-    kind: 'messagesAdded';
-    source: ChatSDKCollectionEventSource;
-    messages: ChatSDKBaseMessage[];
-}
-| {
-    kind: 'messagesUpdated';
-    source: ChatSDKCollectionEventSource;
-    messages: ChatSDKBaseMessage[];
-}
-| {
-    kind: 'initialized';
-    source: 'cache' | 'api';
-    messages: ChatSDKBaseMessage[];
-};
-
-declare type ConversationNotInteractiveMeasurement = {
-    timer: TimeoutId | null;
-    startedAt: number;
-    committed: boolean;
-    inputEnabled: boolean;
-    phaseReached: ConversationNotInteractivePhase;
-    historyLoadResult: HistoryLoadResult;
-    conversationId?: number;
+declare type ConversationNotInteractiveMeasure = {
     channelUrl?: string;
+    historyLoadResult: HistoryLoadResult;
+    inputEnabled: boolean;
+    timer: TimeoutId | null;
 };
 
 declare type ConversationNotInteractivePhase = 'auth' | 'channel_join' | 'history_load' | 'input_enable' | 'render';
 
-declare class ConversationNotInteractiveTimeoutStatsTracker {
-    private readonly callback: StatsAppendCallback;
-    private readonly clock: StatsClock;
-    private readonly setTimeoutFn: typeof setTimeout;
-    private readonly clearTimeoutFn: typeof clearTimeout;
-    private readonly measurements = new Map<string, ConversationNotInteractiveMeasurement>();
+declare class ConversationNotInteractiveTimeoutStats extends AIAgentBaseStats {
+    private phaseReached: ConversationNotInteractivePhase = 'auth';
+    private historyLoadResult: HistoryLoadResult = 'pending';
 
-    constructor(callback: StatsAppendCallback, options?: TimedTrackerOptions) {
-        this.callback = callback;
-        this.clock = getClock(options);
-        this.setTimeoutFn = getSetTimeout(options);
-        this.clearTimeoutFn = getClearTimeout(options);
+    setHistoryLoadResult(result: HistoryLoadResult): this {
+        this.historyLoadResult = result;
+        return this;
     }
 
-    start(params?: { channelUrl?: string; conversationId?: number }): void {
-        const key = this.getKey(params?.channelUrl);
-        this.clearKey(key);
-
-        const measurement = {
-            startedAt: this.clock.now(),
-            channelUrl: params?.channelUrl,
-            conversationId: params?.conversationId,
-            committed: false,
-            inputEnabled: false,
-            phaseReached: 'auth' as ConversationNotInteractivePhase,
-            historyLoadResult: 'pending' as HistoryLoadResult,
-            timer: null as TimeoutId | null,
-        };
-        measurement.timer = this.setTimeoutFn(() => this.commitTimeout(key), 10_000);
-        this.measurements.set(key, measurement);
+    setPhaseReached(phase: ConversationNotInteractivePhase): this {
+        this.phaseReached = phase;
+        return this;
     }
 
-    markChannelJoined(conversationId?: number, channelUrl?: string): void {
-        const measurement = this.getMeasurement(channelUrl);
-        if (!measurement || measurement.committed) return;
-        measurement.phaseReached = 'channel_join';
-        if (conversationId !== undefined) measurement.conversationId = conversationId;
+    protected getMetricKey(): string {
+        return METRIC_KEY_CONVERSATION_NOT_INTERACTIVE_TIMEOUT;
     }
 
-    markHistoryLoaded(result: HistoryLoadResult, channelUrl?: string): void {
-        const measurement = this.getMeasurement(channelUrl);
-        if (!measurement || measurement.committed) return;
-        measurement.phaseReached = 'history_load';
-        measurement.historyLoadResult = result;
-        this.cancelIfReady(channelUrl);
-    }
+    protected buildPayload(): AIAgentStatPayload | null {
+        const duration = this.getTimer(DurationKey.TIMEOUT).duration;
+        if (duration === null) return null;
 
-    markInputEnabled(channelUrl?: string): void {
-        const measurement = this.getMeasurement(channelUrl);
-        if (!measurement || measurement.committed) return;
-        measurement.phaseReached = 'input_enable';
-        measurement.inputEnabled = true;
+        return this.createPayload(duration, {
+            extra: {
+                outcome: 'timeout',
+                phase_reached: this.phaseReached,
+                history_load_result: this.historyLoadResult,
+            },
+        });
+    }
+}
+
+/**
+ * Spec: conversation_not_interactive_timeout
+ *
+ * Detects a new Conversation entry that remains unusable for 10s.
+ *
+ * Timeline:
+ * - Start when the Conversation screen display lifecycle begins.
+ * - Track the farthest reached phase in auth -> channel_join -> history_load
+ *   -> input_enable -> render order.
+ * - Success is input available and history display decision completed.
+ * - Commit only if the 10s timeout fires before success.
+ *
+ * Payload:
+ * - value: total_duration_ms.
+ * - extra.phase_reached: farthest reached phase.
+ * - extra.history_load_result: success | verified_empty | failed | pending.
+ *
+ * Policy:
+ * - Entry-scoped; success or lifecycle abort clears the pending measurement.
+ * - Placeholder/empty UI alone is not success unless the empty history result
+ *   is explicitly verified.
+ */
+declare class ConversationNotInteractiveTimeoutStatsTracker extends MultiStatsTrackerBase<
+ConversationNotInteractiveTimeoutStats,
+ConversationNotInteractiveMeasure
+> {
+    start(params?: { channelUrl?: string; conversationId?: number }): void {
+        const key = this.getKey(params?.channelUrl);
+        this.clearKey(key);
+
+        const record: StatsRecord<ConversationNotInteractiveTimeoutStats, ConversationNotInteractiveMeasure> = {
+            stats: new ConversationNotInteractiveTimeoutStats()
+            .setCommitCallback(this.commitCallback)
+            .startTimer(DurationKey.TIMEOUT),
+            measure: {
+                channelUrl: params?.channelUrl,
+                historyLoadResult: 'pending',
+                inputEnabled: false,
+                timer: null,
+            },
+        };
+        if (params?.conversationId !== undefined) record.stats.setConversationId(params.conversationId);
+        record.measure.timer = setTimeout(() => this.commitTimeout(key), 10_000);
+        this.records.set(key, record);
+    }
+
+    markChannelJoined(conversationId?: number, channelUrl?: string): void {
+        const record = this.getRecord(channelUrl);
+        if (!record) return;
+        record.stats.setPhaseReached('channel_join');
+        if (conversationId !== undefined) record.stats.setConversationId(conversationId);
+    }
+
+    markHistoryLoaded(result: HistoryLoadResult, channelUrl?: string): void {
+        const record = this.getRecord(channelUrl);
+        if (!record) return;
+        record.measure.historyLoadResult = result;
+        record.stats.setHistoryLoadResult(result).setPhaseReached('history_load');
+        this.cancelIfReady(channelUrl);
+    }
+
+    markInputReady(channelUrl?: string): void {
+        const record = this.getRecord(channelUrl);
+        if (!record) return;
+        record.measure.inputEnabled = true;
+        record.stats.setPhaseReached('input_enable');
         this.cancelIfReady(channelUrl);
     }
 
     markRendered(channelUrl?: string): void {
-        const measurement = this.getMeasurement(channelUrl);
-        if (!measurement || measurement.committed) return;
-        measurement.phaseReached = 'render';
+        const record = this.getRecord(channelUrl);
+        if (!record) return;
+        record.stats.setPhaseReached('render');
     }
 
     clear(): void {
-        this.measurements.forEach((measurement) => clearTimer(measurement.timer, this.clearTimeoutFn));
-        this.measurements.clear();
+        this.records.forEach((record) => {
+            if (record.measure.timer !== null) clearTimeout(record.measure.timer);
+        });
+        this.records.clear();
     }
 
     clearChannel(channelUrl?: string): void {
@@ -2393,39 +2683,32 @@ declare class ConversationNotInteractiveTimeoutStatsTracker {
     }
 
     private clearKey(key: string): void {
-        const measurement = this.measurements.get(key);
-        if (!measurement) return;
-        clearTimer(measurement.timer, this.clearTimeoutFn);
-        this.measurements.delete(key);
+        const record = this.records.get(key);
+        if (!record) return;
+        if (record.measure.timer !== null) clearTimeout(record.measure.timer);
+        this.records.delete(key);
     }
 
     private cancelIfReady(channelUrl?: string): void {
-        const measurement = this.getMeasurement(channelUrl);
-        if (!measurement || !measurement.inputEnabled || measurement.historyLoadResult === 'pending') return;
-        this.clearKey(this.getKey(measurement.channelUrl));
+        const record = this.getRecord(channelUrl);
+        if (!record || !record.measure.inputEnabled || record.measure.historyLoadResult === 'pending') return;
+        this.clearKey(this.getKey(record.measure.channelUrl));
     }
 
     private commitTimeout(key: string): void {
-        const measurement = this.measurements.get(key);
-        if (!measurement || measurement.committed) return;
-        measurement.committed = true;
-        measurement.timer = null;
-        append(this.callback, METRIC_KEY_CONVERSATION_NOT_INTERACTIVE_TIMEOUT, this.clock.now() - measurement.startedAt, {
-            conversationId: measurement.conversationId,
-            error: { message: METRIC_KEY_CONVERSATION_NOT_INTERACTIVE_TIMEOUT },
-            extra: {
-                outcome: 'timeout',
-                phase_reached: measurement.phaseReached,
-                history_load_result: measurement.historyLoadResult,
-            },
-        });
-        this.measurements.delete(key);
+        const record = this.records.get(key);
+        if (!record) return;
+        record.measure.timer = null;
+        this.records.delete(key);
+        record.stats.stopTimer(DurationKey.TIMEOUT).commit();
     }
 
-    private getMeasurement(channelUrl?: string): ConversationNotInteractiveMeasurement | undefined {
-        if (channelUrl !== undefined) return this.measurements.get(this.getKey(channelUrl));
-        if (this.measurements.size === 1) return Array.from(this.measurements.values())[0];
-        return this.measurements.get(this.getKey());
+    private getRecord(
+    channelUrl?: string,
+    ): StatsRecord<ConversationNotInteractiveTimeoutStats, ConversationNotInteractiveMeasure> | undefined {
+        if (channelUrl !== undefined) return this.records.get(this.getKey(channelUrl));
+        if (this.records.size === 1) return this.records.values().next().value;
+        return this.records.get(this.getKey());
     }
 
     private getKey(channelUrl?: string): string {
@@ -2440,7 +2723,14 @@ export declare type ConversationProps = PropsWithChildren<{
     shouldMarkAsRead?: boolean;
     /** @internal */
     shouldInitializeConversation?: boolean;
+    /**
+     * Message to send as the first user message when the conversation is initialized
+     * on the server (e.g., the callback user message of a clicked nudge message).
+     * Applied only when the channel has no conversation yet.
+     */
+    initialUserMessage?: string;
     announcementsEnabled?: boolean;
+    /** @default true */
     conversationStatsEnabled?: boolean;
     initialFocusTarget?: ConversationInitialFocusTarget;
     /** Custom styles for the conversation container. */
@@ -2638,11 +2928,20 @@ declare interface Dispatcher {
 }
 
 declare enum DurationKey {
+    ACK_TO_FIRST_CHUNK = 'ack_to_first_chunk_ms',
+    AFTER_TPEN_ABSENT = 'after_tpen_absent_ms',
     AUTH = 'auth_duration_ms',
+    BEFORE_TPST_ABSENT = 'before_tpst_absent_ms',
+    FIRST_CHUNK_TO_RENDER = 'first_chunk_to_render_ms',
     GET_CHANNEL = 'get_channel_duration_ms',
+    GET_LIST = 'get_list_duration_ms',
     GET_MESSAGES = 'get_messages_duration_ms',
-    TOTAL_DURATION = 'total_duration_ms',
-    TOTAL_DURATION_FROM_CACHE = 'total_duration_from_cache_ms',
+    // Internal timer key; the emitted value derives from it and is never emitted raw.
+    PAGE_RENDER = 'page_render_duration_ms',
+    // Emitted field name predates the auth/page-render split; kept for dashboard compatibility.
+    PAGE_RENDER_FROM_CACHE = 'total_duration_from_cache_ms',
+    SEND_TO_ACK = 'send_to_ack_ms',
+    TIMEOUT = 'timeout_ms',
 }
 
 declare type ErrorAnnouncementParams =
@@ -2651,8 +2950,6 @@ declare type ErrorAnnouncementParams =
 | { type: 'csatFormError' }
 | { type: 'generic'; message: string };
 
-declare type ErrorLike = StatsPayloadError;
-
 /**
  * For better understanding: https://sendbird.atlassian.net/wiki/spaces/AA/pages/3075014695/Extended+Message+Payload+Spec
  */
@@ -2821,16 +3118,6 @@ export declare interface FunctionCallsInfo {
     };
 }
 
-declare type GetChannelCompleteParams = {
-    channelUrl?: string;
-    conversationId?: number;
-};
-
-declare type GetChannelErrorParams = {
-    channelUrl?: string;
-    error: Error;
-};
-
 export declare interface GroundednessInfo {
     id: number;
     source_type:
@@ -5210,92 +5497,139 @@ export declare const MessageListUILayout: {
 
 export declare const MessageLogs: ({ actionbook, functionCalls, groundedness, agentMessageTemplates, flaggedTypes, onClickActionbook, onClickFunctionCall, onClickFunctionCallDetail, onClickGroundedness, onClickAgentMessageTemplate, topContent, bottomContent, renderCustomGroundednessIcon, style, }: Props_2) => JSX.Element;
 
-declare class MessagePendingStuckStatsTracker {
-    private readonly callback: StatsAppendCallback;
-    private readonly setTimeoutFn: typeof setTimeout;
-    private readonly clearTimeoutFn: typeof clearTimeout;
-    private readonly measurements = new Map<string, PendingMeasurement>();
+declare class MessagePendingStuckStats extends AIAgentBaseStats {
+    private requestId?: string;
+    private messageType?: PendingMessageType;
+    private stuckReason?: PendingStuckReason;
 
-    constructor(callback: StatsAppendCallback, options?: PendingStuckTrackerOptions) {
-        this.callback = callback;
-        this.setTimeoutFn = getSetTimeout(options);
-        this.clearTimeoutFn = getClearTimeout(options);
+    setRequestId(requestId: string): this {
+        this.requestId = requestId;
+        return this;
     }
 
+    setMessageType(messageType: PendingMessageType): this {
+        this.messageType = messageType;
+        return this;
+    }
+
+    setStuckReason(stuckReason: PendingStuckReason): this {
+        this.stuckReason = stuckReason;
+        return this;
+    }
+
+    protected getMetricKey(): string {
+        return METRIC_KEY_MESSAGE_PENDING_STUCK;
+    }
+
+    protected buildPayload(): AIAgentStatPayload | null {
+        if (this.requestId === undefined || this.messageType === undefined || this.stuckReason === undefined) return null;
+
+        return this.createPayload(this.stuckReason, {
+            extra: {
+                message_type: this.messageType,
+                request_id: this.requestId,
+            },
+        });
+    }
+}
+
+/**
+ * Spec: message_pending_stuck
+ *
+ * Detects a user message send that stays pending too long.
+ *
+ * Timeline:
+ * - Start after the SDK registers a pending send with a request_id.
+ * - Text messages commit after 5s without send completion.
+ * - File messages commit after 10s without upload progress or send completion.
+ * - Upload progress resets the file no-progress timer.
+ *
+ * Payload:
+ * - value: stuck_reason = pending_too_long | upload_no_progress.
+ * - extra.message_type, request_id.
+ *
+ * Policy:
+ * - Send-scoped; each request_id is measured independently.
+ * - Send completion, disappearance, or lifecycle abort clears the measurement
+ *   without emitting.
+ * - Offline sends are excluded from measurement.
+ * - There is no duration value and no resolved follow-up stat.
+ */
+declare class MessagePendingStuckStatsTracker extends MultiStatsTrackerBase<MessagePendingStuckStats, PendingMeasure> {
     start(params: {
         requestId: string;
         channelUrl?: string;
         messageType: PendingMessageType;
         tracksUploadProgress?: boolean;
     }): void {
-        if (!params.requestId || this.measurements.has(params.requestId)) return;
+        if (!params.requestId || this.records.has(params.requestId)) return;
 
         const usesUploadProgress = params.messageType !== 'text' && params.tracksUploadProgress === true;
-        const measurement: PendingMeasurement = {
-            channelUrl: params.channelUrl,
-            messageType: params.messageType,
-            stuckReason: usesUploadProgress ? 'upload_no_progress' : 'pending_too_long',
-            timer: null,
+        const stats = new MessagePendingStuckStats()
+        .setRequestId(params.requestId)
+        .setMessageType(params.messageType)
+        .setStuckReason(usesUploadProgress ? 'upload_no_progress' : 'pending_too_long')
+        .setCommitCallback(this.commitCallback);
+        const record: StatsRecord<MessagePendingStuckStats, PendingMeasure> = {
+            stats,
+            measure: {
+                channelUrl: params.channelUrl,
+                timer: null,
+                usesUploadProgress,
+            },
         };
         const timeoutMs = usesUploadProgress ? FILE_UPLOAD_NO_PROGRESS_TIMEOUT_MS : TEXT_PENDING_TIMEOUT_MS;
-        measurement.timer = this.setTimeoutFn(() => this.detect(params.requestId), timeoutMs);
-        this.measurements.set(params.requestId, measurement);
+        record.measure.timer = setTimeout(() => this.detect(params.requestId), timeoutMs);
+        this.records.set(params.requestId, record);
     }
 
     resolve(params: { requestId: string }): void {
-        const measurement = this.measurements.get(params.requestId);
-        if (!measurement) return;
-
-        clearTimer(measurement.timer, this.clearTimeoutFn);
-        this.measurements.delete(params.requestId);
+        this.cancel(params.requestId);
     }
 
     disappear(params: { requestId: string }): void {
-        const measurement = this.measurements.get(params.requestId);
-        if (!measurement) return;
+        this.cancel(params.requestId);
+    }
+
+    private cancel(requestId: string): void {
+        const record = this.records.get(requestId);
+        if (!record) return;
 
-        clearTimer(measurement.timer, this.clearTimeoutFn);
-        this.measurements.delete(params.requestId);
+        if (record.measure.timer !== null) clearTimeout(record.measure.timer);
+        this.records.delete(requestId);
     }
 
     markUploadProgress(requestId: string): void {
-        const measurement = this.measurements.get(requestId);
-        if (!measurement) return;
-        if (measurement.stuckReason !== 'upload_no_progress') return;
+        const record = this.records.get(requestId);
+        if (!record) return;
+        if (!record.measure.usesUploadProgress) return;
 
-        clearTimer(measurement.timer, this.clearTimeoutFn);
-        measurement.timer = this.setTimeoutFn(() => this.detect(requestId), FILE_UPLOAD_NO_PROGRESS_TIMEOUT_MS);
+        if (record.measure.timer !== null) clearTimeout(record.measure.timer);
+        record.measure.timer = setTimeout(() => this.detect(requestId), FILE_UPLOAD_NO_PROGRESS_TIMEOUT_MS);
     }
 
     clear(): void {
-        this.measurements.forEach((measurement) => clearTimer(measurement.timer, this.clearTimeoutFn));
-        this.measurements.clear();
+        this.records.forEach((record) => {
+            if (record.measure.timer !== null) clearTimeout(record.measure.timer);
+        });
+        this.records.clear();
     }
 
     clearChannel(channelUrl?: string): void {
         if (!channelUrl) return;
-        this.measurements.forEach((measurement, requestId) => {
-            if (measurement.channelUrl !== channelUrl) return;
-            clearTimer(measurement.timer, this.clearTimeoutFn);
-            this.measurements.delete(requestId);
+        this.records.forEach((record, requestId) => {
+            if (record.measure.channelUrl !== channelUrl) return;
+            if (record.measure.timer !== null) clearTimeout(record.measure.timer);
+            this.records.delete(requestId);
         });
     }
 
     private detect(requestId: string): void {
-        const measurement = this.measurements.get(requestId);
-        if (!measurement) return;
+        const record = this.records.get(requestId);
+        if (!record) return;
 
-        this.measurements.delete(requestId);
-        this.commit(requestId, measurement);
-    }
-
-    private commit(requestId: string, measurement: PendingMeasurement): void {
-        append(this.callback, METRIC_KEY_MESSAGE_PENDING_STUCK, measurement.stuckReason, {
-            extra: {
-                message_type: measurement.messageType,
-                request_id: requestId,
-            },
-        });
+        this.records.delete(requestId);
+        record.stats.commit();
     }
 }
 
@@ -5515,6 +5849,10 @@ declare type MultiSelectField = {
     };
 };
 
+declare abstract class MultiStatsTrackerBase<TStats, TMeasure> extends StatsTrackerBase {
+    protected readonly records = new Map<string | number, StatsRecord<TStats, TMeasure>>();
+}
+
 declare interface NetworkStateAdapter {
     /** Returns true if network is currently online */
     isOnline: () => boolean;
@@ -5522,6 +5860,13 @@ declare interface NetworkStateAdapter {
     subscribe: (callback: (isOnline: boolean) => void) => () => void;
 }
 
+export declare interface NudgeMessageResponse {
+    /** Message to display above the launcher. */
+    message: string;
+    /** Message to send as the first user message when the nudge is clicked. */
+    callbackUserMessage?: string;
+}
+
 declare type NumberField = {
     key: string;
     type: 'number';
@@ -5665,6 +6010,14 @@ declare type OutgoingMessageUnion =
 
 declare function OutgoingTextBody(props: OutgoingMessageBodyProps): JSX.Element;
 
+declare type PageRenderState =
+| 'initialized'
+| 'channel_fetching'
+| 'channel_fetched'
+| 'channel_failed'
+| 'messages_fetching'
+| 'messages_fetching_completed';
+
 declare interface PaletteColor {
     extraDark: string;
     dark: string;
@@ -5713,19 +6066,16 @@ declare type PendingAIResponseStart = {
     startedAt: number;
 };
 
-declare type PendingMeasurement = {
+declare type PendingMeasure = {
     channelUrl?: string;
-    messageType: PendingMessageType;
-    stuckReason: PendingStuckReason;
     timer: TimeoutId | null;
+    usesUploadProgress: boolean;
 };
 
 declare type PendingMessageType = 'text' | 'file_image' | 'file_video' | 'file_document' | 'file_audio';
 
 declare type PendingStuckReason = 'pending_too_long' | 'upload_no_progress';
 
-declare type PendingStuckTrackerOptions = Pick<TimedTrackerOptions, 'setTimeout' | 'clearTimeout'>;
-
 declare type PickMessageProps<
 Union,
 T extends Union extends { messageType: infer MT } ? MT : never = Union extends { messageType: infer MT } ? MT : never,
@@ -5863,74 +6213,113 @@ declare type Props_2 = {
 
 declare type ReactOnlyIconName = 'expand' | 'collapse' | 'chevron-right' | 'attach' | 'close-filled' | 'actionbook' | 'function' | 'confluence' | 'zendesk' | 'salesforce' | 'sprinklr' | 'website' | 'snippet' | 'template' | 'show' | 'mute' | 'activity';
 
-declare type RecoveryMeasurement = {
-    timer: TimeoutId | null;
-    startedAt: number | null;
-    triggerType: RecoveryTriggerType | null;
+declare type RecoveryMeasure = {
     inputEnabled: boolean;
+    started: boolean;
+    timer: TimeoutId | null;
 };
 
-declare class RecoveryNotInteractiveTimeoutStatsTracker {
-    private readonly callback: StatsAppendCallback;
-    private readonly clock: StatsClock;
-    private readonly setTimeoutFn: typeof setTimeout;
-    private readonly clearTimeoutFn: typeof clearTimeout;
-    private readonly measurements = new Map<string, RecoveryMeasurement>();
+declare class RecoveryNotInteractiveTimeoutStats extends AIAgentBaseStats {
+    private triggerType?: RecoveryTriggerType;
+
+    setTriggerType(triggerType: RecoveryTriggerType): this {
+        this.triggerType = triggerType;
+        return this;
+    }
+
+    protected getMetricKey(): string {
+        return METRIC_KEY_RECOVERY_NOT_INTERACTIVE_TIMEOUT;
+    }
+
+    protected buildPayload(): AIAgentStatPayload | null {
+        const duration = this.getTimer(DurationKey.TIMEOUT).duration;
+        if (duration === null || this.triggerType === undefined) return null;
 
-    constructor(callback: StatsAppendCallback, options?: TimedTrackerOptions) {
-        this.callback = callback;
-        this.clock = getClock(options);
-        this.setTimeoutFn = getSetTimeout(options);
-        this.clearTimeoutFn = getClearTimeout(options);
+        return this.createPayload(duration, {
+            extra: {
+                trigger_type: this.triggerType,
+            },
+        });
     }
+}
 
+/**
+ * Spec: recovery_not_interactive_timeout
+ *
+ * Detects a Conversation that does not become interactive within 10s after a
+ * recovery trigger.
+ *
+ * Timeline:
+ * - Start after foreground_resume when the app was backgrounded for at least
+ *   5s, or after ws_reconnected.
+ * - Skip the measurement when the input is already enabled.
+ * - Cancel when input becomes enabled before the timeout.
+ * - Commit only if the 10s timeout fires while input is still unavailable.
+ *
+ * Payload:
+ * - value: total_duration_ms.
+ * - extra.trigger_type: foreground_resume | ws_reconnected.
+ *
+ * Policy:
+ * - Recovery-cycle scoped; one active measurement per Conversation/recovery
+ *   trigger.
+ * - Successful recovery is not recorded by this metric.
+ */
+declare class RecoveryNotInteractiveTimeoutStatsTracker extends MultiStatsTrackerBase<
+RecoveryNotInteractiveTimeoutStats,
+RecoveryMeasure
+> {
     start(triggerType: RecoveryTriggerType, channelUrl?: string): void {
         const key = this.getKey(channelUrl);
-        let measurement = this.measurements.get(key);
-        if (measurement && measurement.startedAt !== null) return;
-        if (measurement?.inputEnabled) return;
-
-        measurement = {
-            startedAt: this.clock.now(),
-            triggerType,
-            inputEnabled: measurement?.inputEnabled ?? false,
-            timer: this.setTimeoutFn(() => this.commitTimeout(key), 10_000),
-        };
-        this.measurements.set(key, measurement);
+        let record = this.records.get(key);
+        if (record?.measure.started) return;
+        if (record?.measure.inputEnabled) return;
+
+        if (!record) {
+            record = this.createRecord(false);
+        }
+
+        record.measure.started = true;
+        record.stats = new RecoveryNotInteractiveTimeoutStats()
+        .setTriggerType(triggerType)
+        .setCommitCallback(this.commitCallback)
+        .startTimer(DurationKey.TIMEOUT);
+        record.measure.timer = setTimeout(() => this.commitTimeout(key), 10_000);
+        this.records.set(key, record);
     }
 
     setInputEnabled(enabled: boolean, channelUrl?: string): void {
         const key = this.getKey(channelUrl);
-        let measurement = this.measurements.get(key);
+        let record = this.records.get(key);
 
-        if (!measurement) {
+        if (!record) {
             if (!enabled) return;
-            measurement = {
-                startedAt: null,
-                triggerType: null,
-                inputEnabled: enabled,
-                timer: null,
-            };
-            this.measurements.set(key, measurement);
+            record = this.createRecord(enabled);
+            this.records.set(key, record);
+            return;
         }
 
-        measurement.inputEnabled = enabled;
+        record.measure.inputEnabled = enabled;
         if (enabled) {
-            this.cancelMeasurement(measurement);
+            this.cancelRecord(record);
+        } else if (!record.measure.started) {
+            this.records.delete(key);
         }
     }
 
     cancelPending(channelUrl: string): void {
         const key = this.getKey(channelUrl);
-        const measurement = this.measurements.get(key);
-        if (!measurement) return;
-        this.cancelMeasurement(measurement);
-        if (!measurement.inputEnabled) this.measurements.delete(key);
+        const record = this.records.get(key);
+        if (!record) return;
+        this.cancelRecord(record);
+        if (!record.measure.inputEnabled) this.records.delete(key);
     }
 
     clear(): void {
-        this.measurements.forEach((measurement) => clearTimer(measurement.timer, this.clearTimeoutFn));
-        this.measurements.clear();
+        this.records.forEach((record) => {
+            if (record.measure.timer !== null) clearTimeout(record.measure.timer);
+        });
+        this.records.clear();
     }
 
     clearChannel(channelUrl?: string): void {
@@ -5939,35 +6328,41 @@ declare class RecoveryNotInteractiveTimeoutStatsTracker {
     }
 
     private clearKey(key: string): void {
-        const measurement = this.measurements.get(key);
-        if (!measurement) return;
-        clearTimer(measurement.timer, this.clearTimeoutFn);
-        this.measurements.delete(key);
+        const record = this.records.get(key);
+        if (!record) return;
+        if (record.measure.timer !== null) clearTimeout(record.measure.timer);
+        this.records.delete(key);
     }
 
     private commitTimeout(key: string): void {
-        const measurement = this.measurements.get(key);
-        if (!measurement || measurement.startedAt === null || measurement.triggerType === null) return;
-        if (measurement.inputEnabled) {
-            this.cancelMeasurement(measurement);
+        const record = this.records.get(key);
+        if (!record || !record.measure.started) return;
+        if (record.measure.inputEnabled) {
+            this.cancelRecord(record);
             return;
         }
-        const duration = this.clock.now() - measurement.startedAt;
-        const triggerType = measurement.triggerType;
+        record.stats.stopTimer(DurationKey.TIMEOUT);
         // Drop the entry so a subsequent trigger can record a fresh cycle.
-        this.measurements.delete(key);
-        append(this.callback, METRIC_KEY_RECOVERY_NOT_INTERACTIVE_TIMEOUT, duration, {
-            extra: {
-                trigger_type: triggerType,
-            },
-        });
+        this.records.delete(key);
+        record.stats.commit();
+    }
+
+    private cancelRecord(record: StatsRecord<RecoveryNotInteractiveTimeoutStats, RecoveryMeasure>): void {
+        if (record.measure.timer !== null) clearTimeout(record.measure.timer);
+        record.measure.timer = null;
+        record.measure.started = false;
+        record.stats = new RecoveryNotInteractiveTimeoutStats().setCommitCallback(this.commitCallback);
     }
 
-    private cancelMeasurement(measurement: RecoveryMeasurement): void {
-        clearTimer(measurement.timer, this.clearTimeoutFn);
-        measurement.timer = null;
-        measurement.startedAt = null;
-        measurement.triggerType = null;
+    private createRecord(inputEnabled: boolean): StatsRecord<RecoveryNotInteractiveTimeoutStats, RecoveryMeasure> {
+        return {
+            stats: new RecoveryNotInteractiveTimeoutStats().setCommitCallback(this.commitCallback),
+            measure: {
+                inputEnabled,
+                started: false,
+                timer: null,
+            },
+        };
     }
 
     private getKey(channelUrl?: string): string {
@@ -5987,39 +6382,79 @@ declare type ReleaseDisabledByValue =
 | 'reconnecting'
 | 'handoff_pending';
 
-declare class RenderedContentUnusableStatsTracker {
-    private readonly callback: StatsAppendCallback;
-    private readonly committed = new Set<string>();
+declare type RenderedContentError = {
+    code?: number;
+    message?: string;
+};
 
-    constructor(callback: StatsAppendCallback) {
-        this.callback = callback;
-    }
+declare type RenderedContentErrorDomain = 'empty_render' | 'template_error' | 'form_error';
+
+declare type RenderedContentKind = 'text' | 'image' | 'video' | 'audio' | 'template' | 'form';
+
+declare type RenderedContentUnusableMeasure = {
+    committed: Set<string>;
+};
+
+/**
+ * Spec: rendered_content_unusable
+ *
+ * Records AI response content that reaches the render pipeline but cannot be
+ * presented as usable visible content.
+ *
+ * Timeline:
+ * - Trigger on final render pipeline failures such as empty_render or
+ *   template_error.
+ * - Commit immediately when the SDK-owned renderer determines the content is
+ *   unusable.
+ *
+ * Payload:
+ * - value: error_domain.
+ * - extra.content_kind, message_id.
+ *
+ * Policy:
+ * - Message/content scoped; duplicate failures for the same message, content
+ *   kind, and domain are suppressed.
+ * - Transient network failures and retries that later render successfully are
+ *   not the target of this metric.
+ */
+declare class RenderedContentUnusableStatsTracker extends StatsTrackerBase {
+    private readonly measure: RenderedContentUnusableMeasure = {
+        committed: new Set<string>(),
+    };
 
     commit(params: {
         messageId: string | number;
-        contentKind: 'text' | 'image' | 'video' | 'audio' | 'template' | 'form';
-        errorDomain: 'empty_render' | 'template_error' | 'form_error';
-        error?: ErrorLike;
+        contentKind: RenderedContentKind;
+        errorDomain: RenderedContentErrorDomain;
+        error?: RenderedContentError;
     }): void {
         const key = `${params.messageId}:${params.contentKind}:${params.errorDomain}`;
-        if (this.committed.has(key)) return;
-        evictOldestIfAtLimit(this.committed, RENDERED_CONTENT_UNUSABLE_COMMITTED_LIMIT);
-        this.committed.add(key);
+        if (this.measure.committed.has(key)) return;
+        evictOldestIfAtLimit(this.measure.committed, RENDERED_CONTENT_UNUSABLE_COMMITTED_LIMIT);
+        this.measure.committed.add(key);
 
-        append(this.callback, METRIC_KEY_RENDERED_CONTENT_UNUSABLE, params.errorDomain, {
-            error: params.error ? { code: params.error.code, message: params.errorDomain } : undefined,
-            extra: {
-                content_kind: params.contentKind,
-                message_id: String(params.messageId),
-            },
-        });
+        const stats = new RenderedContentUnusableStats()
+        .setMessageId(params.messageId)
+        .setContentKind(params.contentKind)
+        .setErrorDomain(params.errorDomain)
+        .setError(params.error ? { code: params.error.code, message: params.errorDomain } : undefined)
+        .setCommitCallback(this.commitCallback);
+
+        stats.commit();
     }
 
     clear(): void {
-        this.committed.clear();
+        this.measure.committed.clear();
     }
 }
 
+export declare interface RequestNudgeMessageParams {
+    /** Event key that triggers the nudge message. */
+    key: string;
+    /** Additional context for the server to generate the message. */
+    context?: Record<string, string>;
+}
+
 declare interface ResolvedHandlers extends AgentClientHandlers {
     onClickLink: (params: {
         url: string;
@@ -6059,17 +6494,95 @@ declare type SingleSelectField = {
     layout: 'default';
 };
 
-declare type StatsAppendCallback = (type: string, data: AIAgentStatPayload) => boolean;
+declare abstract class SpanStatsTrackerBase<
+TSpan extends { onVisibilityChanged(visible: boolean): void },
+> extends StatsTrackerBase {
+    protected activeSpan: TSpan | null = null;
+    // Screen visibility is cross-attempt state (it outlives supersessions), so the
+    // tracker owns it and stamps it into each new span, like presentMethod.
+    protected visible: boolean = true;
 
-declare interface StatsClock {
-    now: () => number;
+    setVisible(visible: boolean): void {
+        this.visible = visible;
+        this.activeSpan?.onVisibilityChanged(visible);
+    }
 }
 
-declare type StatsPayloadError = {
-    code?: number;
-    message?: string;
+declare type StatsAppendCallback = (type: string, data: AIAgentStatPayload) => boolean;
+
+declare type StatsPayloadParams = {
+    conversationId?: number;
+    extra?: Record<string, unknown>;
 };
 
+declare type StatsRecord<TStats, TMeasure> = { stats: TStats; measure: TMeasure };
+
+/**
+ * One measurement attempt issued by a tracker (`startSpan`), reified as a handle.
+ *
+ * A span is a StatsRecord with lifecycle: `stats` is the metric instance and `measure`
+ * is the tracking metadata, exactly like a keyed record in MultiStatsTrackerBase. The
+ * two idioms differ only in how the record is held — looked up by an entity key versus
+ * captured as a handle at the moment the measured work starts, so late async events
+ * land on the span that owns them instead of whichever measurement is currently active.
+ *
+ * Cancelling severs the metric reference: a superseded or abandoned span becomes
+ * non-recording and can never emit, without any caller-side staleness guards.
+ *
+ * Emission is visibility-gated: the measurement runs regardless of screen
+ * visibility, but a completion reached while hidden (commitOrDefer) is held and
+ * flushed by onVisibilityChanged when the screen becomes visible.
+ */
+declare abstract class StatsSpanBase<TStats extends AIAgentBaseStats, TMeasure> {
+    protected stats: TStats | null;
+    protected abstract measure: TMeasure;
+    private visible: boolean;
+    private completedHidden = false;
+
+    constructor(stats: TStats | null, visible: boolean) {
+        this.stats = stats;
+        this.visible = visible;
+    }
+
+    get isRecording(): boolean {
+        return this.stats !== null && !this.stats.isCommitted();
+    }
+
+    onVisibilityChanged(visible: boolean): void {
+        if (!this.stats) return;
+
+        this.visible = visible;
+        if (visible && this.completedHidden) {
+            this.stats.commit();
+            this.stats = null;
+        }
+    }
+
+    /** Commit now when the screen is visible; otherwise hold the frozen measurement until it becomes visible. */
+    protected commitOrDefer(): void {
+        if (!this.stats) return;
+
+        if (!this.visible) {
+            this.completedHidden = true;
+            return;
+        }
+
+        this.stats.commit();
+        this.stats = null;
+    }
+
+    cancel(): void {
+        this.stats = null;
+    }
+}
+
+declare abstract class StatsTrackerBase {
+    protected readonly commitCallback: StatsAppendCallback;
+    constructor(commitCallback: StatsAppendCallback) {
+        this.commitCallback = commitCallback;
+    }
+}
+
 /** Per-event override for the platform `announceStatus` wrappers — same shape as `AnnounceOptions`. */
 declare type StatusAnnouncementOptions = AnnounceOptions;
 
@@ -6123,20 +6636,75 @@ declare enum StewardTaskStatus {
     CANCELED = 'CANCELED',
 }
 
-declare class StreamStalledStatsTracker {
-    private readonly callback: StatsAppendCallback;
-    private readonly clock: StatsClock;
-    private readonly setTimeoutFn: typeof setTimeout;
-    private readonly clearTimeoutFn: typeof clearTimeout;
-    private readonly streams = new Map<number, StreamState>();
-    private readonly emittedMessageChannels = new Map<number, string | undefined>();
+declare type StreamMeasure = {
+    channelUrl?: string;
+    deliveryTimer: TimeoutId | null;
+    lastRawAt: number;
+    lastRawLength: number;
+    lastRenderAt: number;
+    lastRenderedLength: number;
+    renderTimer: TimeoutId | null;
+};
+
+declare class StreamStalledStats extends AIAgentBaseStats {
+    private durationMs?: number;
+    private messageId?: number;
+    private stallKind?: StreamStallKind;
+
+    setMessageId(messageId: number): this {
+        this.messageId = messageId;
+        return this;
+    }
+
+    setStall(params: { stallKind: StreamStallKind; durationMs: number }): this {
+        this.durationMs = params.durationMs;
+        this.stallKind = params.stallKind;
+        return this;
+    }
+
+    protected getMetricKey(): string {
+        return METRIC_KEY_STREAM_STALLED;
+    }
+
+    protected buildPayload(): AIAgentStatPayload | null {
+        if (this.durationMs === undefined || this.messageId === undefined || this.stallKind === undefined) return null;
 
-    constructor(callback: StatsAppendCallback, options?: TimedTrackerOptions) {
-        this.callback = callback;
-        this.clock = getClock(options);
-        this.setTimeoutFn = getSetTimeout(options);
-        this.clearTimeoutFn = getClearTimeout(options);
+        return this.createPayload(this.durationMs, {
+            extra: {
+                message_id: String(this.messageId),
+                stall_kind: this.stallKind,
+            },
+        });
     }
+}
+
+/**
+ * Spec: stream_stalled
+ *
+ * Detects AI response stream stalls and classifies the stalled area. Tracking
+ * is keyed by message_id because multiple AI response messages can be active
+ * independently.
+ *
+ * Timeline:
+ * - Start when a streaming AI response produces raw data for a message_id.
+ * - delivery stall: raw response data does not advance for 10s.
+ * - render stall: raw response data is ahead/arriving, but visible render
+ *   progress does not advance for 5s.
+ * - Raw progress refreshes the delivery checkpoint; rendered progress refreshes
+ *   the render checkpoint.
+ *
+ * Payload:
+ * - value: stall_duration_ms.
+ * - extra.stall_kind: delivery | render.
+ * - extra.message_id: tracked AI response message id.
+ *
+ * Policy:
+ * - Message-scoped; first stall only per message_id.
+ * - Delivery and render stalls are mutually exclusive for the same turn.
+ * - A short response completing before either threshold is not recorded.
+ */
+declare class StreamStalledStatsTracker extends MultiStatsTrackerBase<StreamStalledStats, StreamMeasure> {
+    private readonly emittedMessageChannels = new Map<number, string | undefined>();
 
     markRawProgress(params: {
         messageId: number;
@@ -6151,54 +6719,52 @@ declare class StreamStalledStatsTracker {
 
         if (this.emittedMessageChannels.has(params.messageId)) return;
 
-        const stream = this.getOrCreate(params.messageId, params.channelUrl);
-
-        if (params.textLength > stream.lastRawLength) {
-            stream.chunksReceived += 1;
-            stream.lastRawLength = params.textLength;
-            stream.lastRawAt = this.clock.now();
+        const record = this.getOrCreate(params.messageId, params.channelUrl);
+        const measure = record.measure;
 
-            clearTimer(stream.deliveryTimer, this.clearTimeoutFn);
-            stream.deliveryTimer = null;
-            this.scheduleDeliveryStallCheck(params.messageId, stream);
+        if (this.markRawProgressForRecord(record, params.textLength, performance.now())) {
+            if (measure.deliveryTimer !== null) clearTimeout(measure.deliveryTimer);
+            measure.deliveryTimer = null;
+            this.scheduleDeliveryStallCheck(params.messageId, record);
         } else {
-            this.scheduleDeliveryStallCheck(params.messageId, stream);
+            this.scheduleDeliveryStallCheck(params.messageId, record);
         }
 
-        if (stream.lastRenderedLength < stream.lastRawLength && stream.renderTimer === null) {
-            stream.lastRenderAt = this.clock.now();
-            this.scheduleRenderStallCheck(params.messageId, stream, STREAM_RENDER_STALL_THRESHOLD_MS);
+        if (this.isRenderPending(record) && measure.renderTimer === null) {
+            measure.lastRenderAt = performance.now();
+            this.scheduleRenderStallCheck(params.messageId, record, STREAM_RENDER_STALL_THRESHOLD_MS);
         }
     }
 
     markRenderedProgress(params: { messageId: number; displayedLength: number }): void {
-        const stream = this.streams.get(params.messageId);
-        if (!stream || params.displayedLength <= stream.lastRenderedLength) return;
+        const record = this.records.get(params.messageId);
+        if (!record) return;
+        const measure = record.measure;
 
-        stream.lastRenderedLength = params.displayedLength;
-        stream.lastRenderAt = this.clock.now();
+        const progressed = this.markRenderedProgressForRecord(record, params.displayedLength, performance.now());
+        if (!progressed) return;
 
-        if (stream.lastRenderedLength >= stream.lastRawLength) {
-            if (stream.deliveryTimer === null) {
-                this.clearStream(params.messageId, stream);
+        if (!this.isRenderPending(record)) {
+            if (measure.deliveryTimer === null) {
+                this.clearRecord(params.messageId, record);
                 return;
             }
 
-            clearTimer(stream.renderTimer, this.clearTimeoutFn);
-            stream.renderTimer = null;
+            if (measure.renderTimer !== null) clearTimeout(measure.renderTimer);
+            measure.renderTimer = null;
             return;
         }
 
-        this.scheduleRenderStallCheck(params.messageId, stream, STREAM_RENDER_STALL_THRESHOLD_MS);
+        this.scheduleRenderStallCheck(params.messageId, record, STREAM_RENDER_STALL_THRESHOLD_MS);
     }
 
     hasPendingStream(messageId: number): boolean {
-        return this.streams.has(messageId);
+        return this.records.has(messageId);
     }
 
     complete(messageId: number): void {
-        const stream = this.streams.get(messageId);
-        if (stream) this.clearStream(messageId, stream);
+        const record = this.records.get(messageId);
+        if (record) this.clearRecord(messageId, record);
     }
 
     // Final stream update: no more raw chunks are coming, so stop delivery-stall
@@ -6208,52 +6774,53 @@ declare class StreamStalledStatsTracker {
     // raw length — otherwise a renderer that freezes mid-catch-up never emits a
     // 'render' stall.
     private completeDelivery(messageId: number, finalRawLength: number): void {
-        const stream = this.streams.get(messageId);
-        if (!stream) return;
+        const record = this.records.get(messageId);
+        if (!record) return;
+        const measure = record.measure;
 
         // The final stream:false payload can carry text beyond the last streamed
         // chunk; fold it into the raw length first so the render watch targets the
         // full text the animation still has to reveal (otherwise the stream could be
         // cleared while a freeze on that trailing text would go unreported).
-        if (finalRawLength > stream.lastRawLength) {
-            stream.lastRawLength = finalRawLength;
-            stream.lastRawAt = this.clock.now();
+        if (finalRawLength > measure.lastRawLength) {
+            measure.lastRawLength = finalRawLength;
+            measure.lastRawAt = performance.now();
         }
 
-        clearTimer(stream.deliveryTimer, this.clearTimeoutFn);
-        stream.deliveryTimer = null;
+        if (measure.deliveryTimer !== null) clearTimeout(measure.deliveryTimer);
+        measure.deliveryTimer = null;
 
-        if (stream.lastRenderedLength >= stream.lastRawLength) {
-            this.clearStream(messageId, stream);
+        if (!this.isRenderPending(record)) {
+            this.clearRecord(messageId, record);
             return;
         }
 
-        if (stream.renderTimer === null) {
-            stream.lastRenderAt = this.clock.now();
-            this.scheduleRenderStallCheck(messageId, stream, STREAM_RENDER_STALL_THRESHOLD_MS);
+        if (measure.renderTimer === null) {
+            measure.lastRenderAt = performance.now();
+            this.scheduleRenderStallCheck(messageId, record, STREAM_RENDER_STALL_THRESHOLD_MS);
         }
     }
 
     clearMessage(messageId: number): void {
-        const stream = this.streams.get(messageId);
-        if (stream) this.clearStream(messageId, stream);
+        const record = this.records.get(messageId);
+        if (record) this.clearRecord(messageId, record);
         this.emittedMessageChannels.delete(messageId);
     }
 
     clear(): void {
-        this.streams.forEach((stream) => {
-            clearTimer(stream.deliveryTimer, this.clearTimeoutFn);
-            clearTimer(stream.renderTimer, this.clearTimeoutFn);
+        this.records.forEach((record) => {
+            if (record.measure.deliveryTimer !== null) clearTimeout(record.measure.deliveryTimer);
+            if (record.measure.renderTimer !== null) clearTimeout(record.measure.renderTimer);
         });
-        this.streams.clear();
+        this.records.clear();
         this.emittedMessageChannels.clear();
     }
 
     clearChannel(channelUrl?: string): void {
         if (!channelUrl) return;
-        this.streams.forEach((stream, messageId) => {
-            if (stream.channelUrl !== channelUrl && stream.channelUrl !== undefined) return;
-            this.clearStream(messageId, stream);
+        this.records.forEach((record, messageId) => {
+            if (record.measure.channelUrl !== channelUrl && record.measure.channelUrl !== undefined) return;
+            this.clearRecord(messageId, record);
         });
         this.emittedMessageChannels.forEach((emittedChannelUrl, messageId) => {
             if (emittedChannelUrl === channelUrl || emittedChannelUrl === undefined)
@@ -6262,83 +6829,95 @@ declare class StreamStalledStatsTracker {
     }
 
     private detectDelivery(messageId: number): void {
-        const stream = this.streams.get(messageId);
-        if (!stream) return;
-        stream.deliveryTimer = null;
+        const record = this.records.get(messageId);
+        if (!record) return;
+        const measure = record.measure;
+        measure.deliveryTimer = null;
         // Mutex: cancel any in-flight render stall check so delivery wins this turn.
-        clearTimer(stream.renderTimer, this.clearTimeoutFn);
-        stream.renderTimer = null;
-        this.emit(messageId, stream, 'delivery');
+        if (measure.renderTimer !== null) clearTimeout(measure.renderTimer);
+        measure.renderTimer = null;
+        this.emit(messageId, record, 'delivery');
     }
 
     private detectRender(messageId: number): void {
-        const stream = this.streams.get(messageId);
-        if (!stream) return;
-        stream.renderTimer = null;
-        if (stream.lastRenderedLength >= stream.lastRawLength) return;
+        const record = this.records.get(messageId);
+        if (!record) return;
+        const measure = record.measure;
+        measure.renderTimer = null;
+        if (!this.isRenderPending(record)) return;
 
-        const elapsedSinceRender = this.clock.now() - stream.lastRenderAt;
+        const elapsedSinceRender = performance.now() - measure.lastRenderAt;
         if (elapsedSinceRender < STREAM_RENDER_STALL_THRESHOLD_MS) {
-            this.scheduleRenderStallCheck(messageId, stream, STREAM_RENDER_STALL_THRESHOLD_MS - elapsedSinceRender);
+            this.scheduleRenderStallCheck(messageId, record, STREAM_RENDER_STALL_THRESHOLD_MS - elapsedSinceRender);
             return;
         }
 
         // Mutex rule: when raw progress has been silent for at least the render threshold,
         // delivery is the root cause and will win. Defer the render emit until delivery has
         // had a chance to fire so we don't surface render as the symptom.
-        const elapsedSinceRaw = this.clock.now() - stream.lastRawAt;
-        if (elapsedSinceRaw >= STREAM_RENDER_STALL_THRESHOLD_MS && stream.deliveryTimer !== null) {
+        const elapsedSinceRaw = performance.now() - measure.lastRawAt;
+        if (elapsedSinceRaw >= STREAM_RENDER_STALL_THRESHOLD_MS && measure.deliveryTimer !== null) {
             const untilDelivery = STREAM_DELIVERY_STALL_THRESHOLD_MS - elapsedSinceRaw;
             if (untilDelivery > 0) {
-                this.scheduleRenderStallCheck(messageId, stream, untilDelivery);
+                this.scheduleRenderStallCheck(messageId, record, untilDelivery);
                 return;
             }
         }
 
-        this.emit(messageId, stream, 'render');
+        this.emit(messageId, record, 'render');
     }
 
-    private scheduleRenderStallCheck(messageId: number, stream: StreamState, delayMs: number): void {
-        if (stream.renderTimer !== null) return;
-        stream.renderTimer = this.setTimeoutFn(() => this.detectRender(messageId), delayMs);
+    private scheduleRenderStallCheck(
+    messageId: number,
+    record: StatsRecord<StreamStalledStats, StreamMeasure>,
+    delayMs: number,
+    ): void {
+        if (record.measure.renderTimer !== null) return;
+        record.measure.renderTimer = setTimeout(() => this.detectRender(messageId), delayMs);
     }
 
-    private scheduleDeliveryStallCheck(messageId: number, stream: StreamState): void {
-        if (stream.deliveryTimer !== null) return;
-        stream.deliveryTimer = this.setTimeoutFn(() => this.detectDelivery(messageId), STREAM_DELIVERY_STALL_THRESHOLD_MS);
+    private scheduleDeliveryStallCheck(messageId: number, record: StatsRecord<StreamStalledStats, StreamMeasure>): void {
+        if (record.measure.deliveryTimer !== null) return;
+        record.measure.deliveryTimer = setTimeout(() => this.detectDelivery(messageId), STREAM_DELIVERY_STALL_THRESHOLD_MS);
     }
 
-    private emit(messageId: number, stream: StreamState, stallKind: StreamStallKind): void {
+    private emit(
+    messageId: number,
+    record: StatsRecord<StreamStalledStats, StreamMeasure>,
+    stallKind: StreamStallKind,
+    ): void {
         if (this.emittedMessageChannels.has(messageId)) return;
 
-        const stallStartedAt = stallKind === 'delivery' ? stream.lastRawAt : stream.lastRenderAt;
-        append(this.callback, METRIC_KEY_STREAM_STALLED, this.clock.now() - stallStartedAt, {
-            extra: {
-                message_id: String(messageId),
-                stall_kind: stallKind,
-            },
-        });
-        this.rememberEmitted(messageId, stream.channelUrl);
-        this.clearStream(messageId, stream);
+        const stalledAt = performance.now();
+        const stallStartedAt = stallKind === 'delivery' ? record.measure.lastRawAt : record.measure.lastRenderAt;
+        record.stats.setStall({ stallKind, durationMs: stalledAt - stallStartedAt }).commit();
+        this.rememberEmitted(messageId, record.measure.channelUrl);
+        this.clearRecord(messageId, record);
     }
 
-    private getOrCreate(messageId: number, channelUrl: string | undefined): StreamState {
-        const existing = this.streams.get(messageId);
+    private getOrCreate(
+    messageId: number,
+    channelUrl: string | undefined,
+    ): StatsRecord<StreamStalledStats, StreamMeasure> {
+        const existing = this.records.get(messageId);
         if (existing) return existing;
 
-        const now = this.clock.now();
-        const stream: StreamState = {
-            channelUrl,
-            chunksReceived: 0,
-            lastRawAt: now,
-            lastRenderAt: now,
-            lastRawLength: 0,
-            lastRenderedLength: 0,
-            deliveryTimer: null,
-            renderTimer: null,
+        const startedAt = performance.now();
+
+        const record: StatsRecord<StreamStalledStats, StreamMeasure> = {
+            stats: new StreamStalledStats().setMessageId(messageId).setCommitCallback(this.commitCallback),
+            measure: {
+                channelUrl,
+                deliveryTimer: null,
+                lastRawAt: startedAt,
+                lastRawLength: 0,
+                lastRenderAt: startedAt,
+                lastRenderedLength: 0,
+                renderTimer: null,
+            },
         };
-        this.streams.set(messageId, stream);
-        return stream;
+        this.records.set(messageId, record);
+        return record;
     }
 
     private rememberEmitted(messageId: number, channelUrl: string | undefined): void {
@@ -6348,26 +6927,43 @@ declare class StreamStalledStatsTracker {
         this.emittedMessageChannels.set(messageId, channelUrl);
     }
 
-    private clearStream(messageId: number, stream: StreamState): void {
-        clearTimer(stream.deliveryTimer, this.clearTimeoutFn);
-        clearTimer(stream.renderTimer, this.clearTimeoutFn);
-        this.streams.delete(messageId);
+    private clearRecord(messageId: string | number, record: StatsRecord<StreamStalledStats, StreamMeasure>): void {
+        if (record.measure.deliveryTimer !== null) clearTimeout(record.measure.deliveryTimer);
+        if (record.measure.renderTimer !== null) clearTimeout(record.measure.renderTimer);
+        this.records.delete(messageId);
+    }
+
+    private isRenderPending(record: StatsRecord<StreamStalledStats, StreamMeasure>): boolean {
+        return record.measure.lastRenderedLength < record.measure.lastRawLength;
+    }
+
+    private markRawProgressForRecord(
+    record: StatsRecord<StreamStalledStats, StreamMeasure>,
+    textLength: number,
+    rawAt: number,
+    ): boolean {
+        if (textLength <= record.measure.lastRawLength) return false;
+
+        record.measure.lastRawLength = textLength;
+        record.measure.lastRawAt = rawAt;
+        return true;
+    }
+
+    private markRenderedProgressForRecord(
+    record: StatsRecord<StreamStalledStats, StreamMeasure>,
+    displayedLength: number,
+    renderedAt: number,
+    ): boolean {
+        if (displayedLength <= record.measure.lastRenderedLength) return false;
+
+        record.measure.lastRenderedLength = displayedLength;
+        record.measure.lastRenderAt = renderedAt;
+        return true;
     }
 }
 
 declare type StreamStallKind = 'delivery' | 'render';
 
-declare type StreamState = {
-    channelUrl?: string;
-    chunksReceived: number;
-    lastRawAt: number;
-    lastRenderAt: number;
-    lastRawLength: number;
-    lastRenderedLength: number;
-    deliveryTimer: TimeoutId | null;
-    renderTimer: TimeoutId | null;
-};
-
 /**
  * StringSet type for React components
  * Uses SNAKE_CASE keys for backward compatibility
@@ -6513,6 +7109,7 @@ export declare type StringSet = {
     A11Y_CONVERSATION_ITEM: (agent: string, status: string, time: string, count: number) => string;
     A11Y_CONNECT_AGENT: string;
     A11Y_CLOSE_MESSENGER: string;
+    A11Y_DISMISS_NUDGE_MESSAGE: string;
     A11Y_EXPAND_MESSENGER: string;
     A11Y_COLLAPSE_MESSENGER: string;
     A11Y_HINT_SEND_MESSAGE: string;
@@ -6642,11 +7239,6 @@ declare type TextField = {
     };
 };
 
-declare type TimedTrackerOptions = TrackerOptions & {
-    setTimeout?: typeof setTimeout;
-    clearTimeout?: typeof clearTimeout;
-};
-
 declare type TimeoutId = ReturnType<typeof setTimeout>;
 
 declare interface TimerData {
@@ -6654,42 +7246,94 @@ declare interface TimerData {
     endTime: number | null;
 }
 
-declare type TrackerOptions = {
-    clock?: StatsClock;
+/** A never-started timer reads as all-null; duration stays null until the timer stops. */
+declare type TimerReading = {
+    startAt: number | null;
+    endedAt: number | null;
+    duration: number | null;
 };
 
-declare class TypingIndicatorAbsentTimeoutStatsTracker {
-    private readonly callback: StatsAppendCallback;
-    private readonly clock: StatsClock;
-    private readonly setTimeoutFn: typeof setTimeout;
-    private readonly clearTimeoutFn: typeof clearTimeout;
-    private readonly turns = new Map<string, TypingTurn>();
-    private readonly pendingAIResponseStartsByUserMessageId = new Map<number, PendingAIResponseStart>();
+declare class TypingIndicatorAbsentTimeoutStats extends AIAgentBaseStats {
+    private beforeTpstAbsentMs?: number;
+    private afterTpenAbsentMs?: number;
 
-    constructor(callback: StatsAppendCallback, options?: TimedTrackerOptions) {
-        this.callback = callback;
-        this.clock = getClock(options);
-        this.setTimeoutFn = getSetTimeout(options);
-        this.clearTimeoutFn = getClearTimeout(options);
+    setBeforeTpstAbsentMs(duration: number): this {
+        this.beforeTpstAbsentMs = duration;
+        return this;
     }
 
+    setAfterTpenAbsentMs(duration: number): this {
+        this.afterTpenAbsentMs = duration;
+        return this;
+    }
+
+    protected getMetricKey(): string {
+        return METRIC_KEY_AI_TYPING_INDICATOR_ABSENT_TIMEOUT;
+    }
+
+    protected buildPayload(): AIAgentStatPayload | null {
+        if (this.beforeTpstAbsentMs === undefined && this.afterTpenAbsentMs === undefined) return null;
+
+        return this.createPayload((this.beforeTpstAbsentMs ?? 0) + (this.afterTpenAbsentMs ?? 0), {
+            extra: {
+                [DurationKey.BEFORE_TPST_ABSENT]: this.beforeTpstAbsentMs,
+                [DurationKey.AFTER_TPEN_ABSENT]: this.afterTpenAbsentMs,
+            },
+        });
+    }
+}
+
+/**
+ * Spec: ai_typing_indicator_absent_timeout
+ *
+ * Detects server typing signal gaps during an AI turn. The metric is emitted
+ * only for AI conversations and tracks two absent phases in the same turn.
+ *
+ * Timeline:
+ * - Start before-TPST measurement when the user message send turn starts.
+ * - Close before-TPST when TPST/typing-start is observed.
+ * - Start after-TPEN measurement when TPEN/typing-end is observed.
+ * - Close after-TPEN when the AI response message starts streaming.
+ * - Commit when either phase exceeds the 3s absent threshold, or when the
+ *   30s collection safety timeout is reached.
+ *
+ * Payload:
+ * - value: absent_duration_ms, the total measured absent duration.
+ * - extra.before_tpst_absent_ms: gap before TPST, when present.
+ * - extra.after_tpen_absent_ms: gap after TPEN, when present.
+ *
+ * Policy:
+ * - Turn-scoped; each user message turn is measured independently.
+ * - The Phase 2 example sums both measured absent phases in value, even when
+ *   only one phase reaches the threshold.
+ * - Human-agent handoff/abort clears the pending turn without emitting.
+ */
+declare class TypingIndicatorAbsentTimeoutStatsTracker extends MultiStatsTrackerBase<
+TypingIndicatorAbsentTimeoutStats,
+TypingMeasure
+> {
+    private readonly pendingAIResponseStartsByUserMessageId = new Map<number, PendingAIResponseStart>();
+
     startTurn(params: { requestId: string; channelUrl?: string }): void {
         this.cancelTurn(params.requestId);
-        const turn: TypingTurn = {
-            requestId: params.requestId,
-            channelUrl: params.channelUrl,
-            beforeTpstStartedAt: this.clock.now(),
-            afterTpenStartedAt: null,
-            timer: null,
+        const record: StatsRecord<TypingIndicatorAbsentTimeoutStats, TypingMeasure> = {
+            stats: new TypingIndicatorAbsentTimeoutStats().setCommitCallback(this.commitCallback),
+            measure: {
+                afterTpenStartedAt: null,
+                beforeTpstStartedAt: performance.now(),
+                channelUrl: params.channelUrl,
+                requestId: params.requestId,
+                timer: null,
+            },
         };
-        turn.timer = this.setTimeoutFn(() => this.commitTimeout(turn.requestId), TYPING_COLLECTION_TIMEOUT_MS);
-        this.turns.set(params.requestId, turn);
+        record.measure.timer = setTimeout(() => this.commitTimeout(record.measure.requestId), TYPING_COLLECTION_TIMEOUT_MS);
+        this.records.set(params.requestId, record);
     }
 
     markUserMessageAck(params: { requestId: string; messageId: number }): void {
-        const turn = this.turns.get(params.requestId);
-        if (!turn) return;
-        turn.userMessageId = params.messageId;
+        const record = this.records.get(params.requestId);
+        if (!record) return;
+        record.measure.userMessageId = params.messageId;
 
         const pending = this.pendingAIResponseStartsByUserMessageId.get(params.messageId);
         if (!pending) return;
@@ -6703,12 +7347,12 @@ declare class TypingIndicatorAbsentTimeoutStatsTracker {
     replaceTurnRequestId(currentRequestId: string, nextRequestId: string): void {
         if (currentRequestId === nextRequestId) return;
 
-        const turn = this.turns.get(currentRequestId);
-        if (!turn) return;
+        const record = this.records.get(currentRequestId);
+        if (!record) return;
 
-        this.turns.delete(currentRequestId);
-        turn.requestId = nextRequestId;
-        this.turns.set(nextRequestId, turn);
+        this.records.delete(currentRequestId);
+        record.measure.requestId = nextRequestId;
+        this.records.set(nextRequestId, record);
     }
 
     cancelTurn(requestId: string): void {
@@ -6716,20 +7360,20 @@ declare class TypingIndicatorAbsentTimeoutStatsTracker {
     }
 
     markTypingStarted(channelUrl?: string): void {
-        const now = this.clock.now();
-        this.turns.forEach((turn) => {
-            if (!matchesChannel(turn, channelUrl)) return;
-            this.recordAfterTpen(turn, now);
-            this.recordBeforeTpst(turn, now);
+        const now = performance.now();
+        this.records.forEach((record) => {
+            if (!matchesChannel(record.measure.channelUrl, channelUrl)) return;
+            this.recordAfterTpen(record, now);
+            this.recordBeforeTpst(record, now);
         });
     }
 
     markTypingEnded(channelUrl?: string): void {
-        const now = this.clock.now();
-        this.turns.forEach((turn) => {
-            if (!matchesChannel(turn, channelUrl)) return;
-            this.recordBeforeTpst(turn, now);
-            turn.afterTpenStartedAt = now;
+        const now = performance.now();
+        this.records.forEach((record) => {
+            if (!matchesChannel(record.measure.channelUrl, channelUrl)) return;
+            this.recordBeforeTpst(record, now);
+            record.measure.afterTpenStartedAt = now;
         });
     }
 
@@ -6737,9 +7381,15 @@ declare class TypingIndicatorAbsentTimeoutStatsTracker {
         const channelUrl = params.channelUrl;
         const userMessageId = params.userMessageId;
         const matchesUserMessage = userMessageId !== undefined;
-        const now = this.clock.now();
+        const now = performance.now();
         const matched = this.applyAIResponseStarted({ channelUrl, matchesUserMessage, userMessageId }, now);
-        if (matched || !matchesUserMessage || userMessageId === undefined || !this.hasUnackedTurn(channelUrl)) return;
+        if (
+        matched ||
+        !matchesUserMessage ||
+        userMessageId === undefined ||
+        !hasUnackedChannelTurn(this.records.values(), channelUrl)
+        )
+        return;
 
         if (!this.pendingAIResponseStartsByUserMessageId.has(userMessageId)) {
             evictOldestIfAtLimit(this.pendingAIResponseStartsByUserMessageId, 100);
@@ -6754,16 +7404,16 @@ declare class TypingIndicatorAbsentTimeoutStatsTracker {
         if (!params.matchesUserMessage) {
             const match = this.findSingleTurn(params.channelUrl);
             if (!match) return false;
-            this.completeTurn(match.requestId, match.turn, startedAt);
+            this.completeTurn(match.requestId, match.record, startedAt);
             return true;
         }
 
         let matched = false;
-        this.turns.forEach((turn, requestId) => {
-            if (!matchesChannel(turn, params.channelUrl)) return;
-            if (params.matchesUserMessage && turn.userMessageId !== params.userMessageId) return;
+        this.records.forEach((record) => {
+            if (!matchesChannel(record.measure.channelUrl, params.channelUrl)) return;
+            if (params.matchesUserMessage && record.measure.userMessageId !== params.userMessageId) return;
             matched = true;
-            this.completeTurn(requestId, turn, startedAt);
+            this.completeTurn(record.measure.requestId, record, startedAt);
         });
         return matched;
     }
@@ -6771,38 +7421,38 @@ declare class TypingIndicatorAbsentTimeoutStatsTracker {
     private findSingleTurn(channelUrl?: string): TypingTurnEntry | undefined {
         let match: TypingTurnEntry | undefined;
         let matchedCount = 0;
-        this.turns.forEach((turn, requestId) => {
-            if (!matchesChannel(turn, channelUrl)) return;
+        this.records.forEach((record) => {
+            if (!matchesChannel(record.measure.channelUrl, channelUrl)) return;
             matchedCount += 1;
             if (matchedCount > 1) return;
-            match = { requestId, turn };
+            match = { requestId: record.measure.requestId, record };
         });
         return matchedCount === 1 ? match : undefined;
     }
 
-    private completeTurn(requestId: string, turn: TypingTurn, startedAt: number): void {
-        this.recordBeforeTpst(turn, startedAt);
-        this.recordAfterTpen(turn, startedAt);
-        this.commitIfAbsent(requestId, turn);
-    }
-
-    private hasUnackedTurn(channelUrl?: string): boolean {
-        return hasUnackedChannelTurn(this.turns.values(), channelUrl);
+    private completeTurn(
+    requestId: string,
+    record: StatsRecord<TypingIndicatorAbsentTimeoutStats, TypingMeasure>,
+    startedAt: number,
+    ): void {
+        this.recordBeforeTpst(record, startedAt);
+        this.recordAfterTpen(record, startedAt);
+        this.commitIfAbsent(requestId, record);
     }
 
     clear(): void {
-        this.turns.forEach((turn) => {
-            clearTimer(turn.timer, this.clearTimeoutFn);
+        this.records.forEach((record) => {
+            if (record.measure.timer !== null) clearTimeout(record.measure.timer);
         });
-        this.turns.clear();
+        this.records.clear();
         this.pendingAIResponseStartsByUserMessageId.clear();
     }
 
     clearChannel(channelUrl?: string): void {
         if (!channelUrl) return;
-        this.turns.forEach((turn, requestId) => {
-            if (turn.channelUrl !== channelUrl) return;
-            this.cleanupTurn(requestId);
+        this.records.forEach((record) => {
+            if (record.measure.channelUrl !== channelUrl) return;
+            this.cleanupTurn(record.measure.requestId);
         });
         this.pendingAIResponseStartsByUserMessageId.forEach((pending, userMessageId) => {
             if (pending.channelUrl === channelUrl) this.pendingAIResponseStartsByUserMessageId.delete(userMessageId);
@@ -6810,78 +7460,62 @@ declare class TypingIndicatorAbsentTimeoutStatsTracker {
     }
 
     private commitTimeout(requestId: string): void {
-        const turn = this.turns.get(requestId);
-        if (!turn) return;
-        const now = this.clock.now();
-        this.recordBeforeTpst(turn, now);
-        this.recordAfterTpen(turn, now);
-        this.commitIfAbsent(requestId, turn);
+        const record = this.records.get(requestId);
+        if (!record) return;
+        const now = performance.now();
+        this.recordBeforeTpst(record, now);
+        this.recordAfterTpen(record, now);
+        this.commitIfAbsent(requestId, record);
+    }
+
+    private commitIfAbsent(
+    requestId: string,
+    record: StatsRecord<TypingIndicatorAbsentTimeoutStats, TypingMeasure>,
+    ): void {
+        record.stats.commit();
+        this.cleanupTurn(requestId);
+    }
+
+    private cleanupTurn(requestId: string): void {
+        const record = this.records.get(requestId);
+        if (!record) return;
+        if (record.measure.timer !== null) clearTimeout(record.measure.timer);
+        this.records.delete(requestId);
     }
 
     private recordBeforeTpst(
-    turn: { beforeTpstStartedAt: number | null; beforeTpstAbsentMs?: number },
+    record: StatsRecord<TypingIndicatorAbsentTimeoutStats, TypingMeasure>,
     endedAt: number,
     ): void {
-        if (turn.beforeTpstStartedAt === null) return;
-        const duration = endedAt - turn.beforeTpstStartedAt;
-        if (duration >= TYPING_ABSENT_THRESHOLD_MS) turn.beforeTpstAbsentMs = duration;
-        turn.beforeTpstStartedAt = null;
+        if (record.measure.beforeTpstStartedAt === null) return;
+        const duration = endedAt - record.measure.beforeTpstStartedAt;
+        if (duration >= TYPING_ABSENT_THRESHOLD_MS) record.stats.setBeforeTpstAbsentMs(duration);
+        record.measure.beforeTpstStartedAt = null;
     }
 
     private recordAfterTpen(
-    turn: { afterTpenStartedAt: number | null; afterTpenAbsentMs?: number },
+    record: StatsRecord<TypingIndicatorAbsentTimeoutStats, TypingMeasure>,
     endedAt: number,
     ): void {
-        if (turn.afterTpenStartedAt === null) return;
-        const duration = endedAt - turn.afterTpenStartedAt;
-        if (duration >= TYPING_ABSENT_THRESHOLD_MS) turn.afterTpenAbsentMs = duration;
-        turn.afterTpenStartedAt = null;
-    }
-
-    private commitIfAbsent(requestId: string, turn: { beforeTpstAbsentMs?: number; afterTpenAbsentMs?: number }): void {
-        const beforeTpstAbsentMs = turn.beforeTpstAbsentMs;
-        const afterTpenAbsentMs = turn.afterTpenAbsentMs;
-        if (beforeTpstAbsentMs === undefined && afterTpenAbsentMs === undefined) {
-            this.cleanupTurn(requestId);
-            return;
-        }
-
-        append(
-        this.callback,
-        METRIC_KEY_AI_TYPING_INDICATOR_ABSENT_TIMEOUT,
-        (beforeTpstAbsentMs ?? 0) + (afterTpenAbsentMs ?? 0),
-            {
-            extra: {
-                ...(beforeTpstAbsentMs !== undefined && { before_tpst_absent_ms: beforeTpstAbsentMs }),
-                ...(afterTpenAbsentMs !== undefined && { after_tpen_absent_ms: afterTpenAbsentMs }),
-            },
-        },
-        );
-        this.cleanupTurn(requestId);
-    }
-
-    private cleanupTurn(requestId: string): void {
-        const turn = this.turns.get(requestId);
-        if (!turn) return;
-        clearTimer(turn.timer, this.clearTimeoutFn);
-        this.turns.delete(requestId);
+        if (record.measure.afterTpenStartedAt === null) return;
+        const duration = endedAt - record.measure.afterTpenStartedAt;
+        if (duration >= TYPING_ABSENT_THRESHOLD_MS) record.stats.setAfterTpenAbsentMs(duration);
+        record.measure.afterTpenStartedAt = null;
     }
 }
 
-declare type TypingTurn = {
-    requestId: string;
-    channelUrl?: string;
-    userMessageId?: number;
-    beforeTpstStartedAt: number | null;
+declare type TypingMeasure = {
     afterTpenStartedAt: number | null;
-    beforeTpstAbsentMs?: number;
-    afterTpenAbsentMs?: number;
+    beforeTpstStartedAt: number | null;
+    channelUrl?: string;
+    requestId: string;
     timer: TimeoutId | null;
+    userMessageId?: number;
 };
 
 declare type TypingTurnEntry = {
     requestId: string;
-    turn: TypingTurn;
+    record: StatsRecord<TypingIndicatorAbsentTimeoutStats, TypingMeasure>;
 };
 
 declare interface TypographyShape {
@@ -6959,76 +7593,163 @@ export declare type UserActionStatus =
 
 export declare const useRefreshActiveChannel: (updater: () => Promise<void>) => () => Promise<void>;
 
-declare class UserPerceivedResponseTimeStatsTracker {
-    private readonly callback: StatsAppendCallback;
-    private readonly clock: StatsClock;
-    private readonly random: () => number;
-    private readonly sampledByRequestId = new Map<string, UserTurn>();
-    private readonly sampledByAIMessageId = new Map<number, UserTurn>();
+declare type UserPerceivedResponseTimeMeasure = {
+    ackAt?: number;
+    aiMessageId?: number;
+    channelUrl?: string;
+    firstChunkAt?: number;
+    isStreaming?: boolean;
+    requestId: string;
+    startedAt: number;
+    userMessageId?: number;
+};
+
+declare class UserPerceivedResponseTimeStats extends AIAgentBaseStats {
+    private ackToFirstChunkMs?: number;
+    private firstChunkToRenderMs?: number;
+    private isStreaming?: boolean;
+    private sendToAckMs?: number;
+    private totalDurationMs?: number;
+
+    setDurations(params: {
+        ackToFirstChunkMs: number;
+        firstChunkToRenderMs: number;
+        isStreaming: boolean;
+        sendToAckMs: number;
+        totalDurationMs: number;
+    }): this {
+        this.ackToFirstChunkMs = params.ackToFirstChunkMs;
+        this.firstChunkToRenderMs = params.firstChunkToRenderMs;
+        this.isStreaming = params.isStreaming;
+        this.sendToAckMs = params.sendToAckMs;
+        this.totalDurationMs = params.totalDurationMs;
+        return this;
+    }
+
+    protected getMetricKey(): string {
+        return METRIC_KEY_USER_PERCEIVED_RESPONSE_TIME;
+    }
+
+    protected buildPayload(): AIAgentStatPayload | null {
+        if (
+        this.ackToFirstChunkMs === undefined ||
+        this.firstChunkToRenderMs === undefined ||
+        this.isStreaming === undefined ||
+        this.sendToAckMs === undefined ||
+        this.totalDurationMs === undefined
+        ) {
+            return null;
+        }
+
+        return this.createPayload(this.totalDurationMs, {
+            extra: {
+                is_streaming: this.isStreaming,
+                [DurationKey.ACK_TO_FIRST_CHUNK]: this.ackToFirstChunkMs,
+                [DurationKey.FIRST_CHUNK_TO_RENDER]: this.firstChunkToRenderMs,
+                [DurationKey.SEND_TO_ACK]: this.sendToAckMs,
+            },
+        });
+    }
+}
+
+/**
+ * Spec: user_perceived_response_time
+ *
+ * Measures the user-visible latency from SDK send to the first AI response
+ * frame on screen. Sampling is per user message: 15% independent probability
+ * by default, capped at 10 collected turns per runtime session.
+ *
+ * Timeline:
+ * - T0: SDK send API is called, not the UI tap time.
+ * - T1: send completion handler runs.
+ * - T2: first raw AI response chunk reaches the SDK.
+ * - T3: the first response frame is rendered in the visible message cell.
+ *
+ * Payload:
+ * - value: total_perceived_ms = T3 - T0.
+ * - extra.send_to_ack_ms = T1 - T0.
+ * - extra.ack_to_first_chunk_ms = T2 - T1.
+ * - extra.first_chunk_to_render_ms = T3 - T2.
+ * - extra.is_streaming: whether the AI response is streaming.
+ *
+ * Policy:
+ * - Turn-scoped; commit only after T3.
+ * - Incomplete or aborted turns are not recorded.
+ * - Human-agent handoff/abort clears pending measurements without emitting.
+ */
+declare class UserPerceivedResponseTimeStatsTracker extends MultiStatsTrackerBase<
+UserPerceivedResponseTimeStats,
+UserPerceivedResponseTimeMeasure
+> {
+    private readonly samplingRate: number;
     private readonly pendingAIResponseByUserMessageId = new Map<number, PendingAIResponseRaw>();
     private collectedCount = 0;
 
-    constructor(callback: StatsAppendCallback, options?: TrackerOptions & { random?: () => number }) {
-        this.callback = callback;
-        this.clock = getClock(options);
-        this.random = options?.random ?? Math.random;
+    constructor(callback: StatsAppendCallback, options?: { samplingRate?: number }) {
+        super(callback);
+        this.samplingRate = options?.samplingRate ?? USER_PERCEIVED_RESPONSE_TIME_SAMPLING_RATE;
     }
 
     startTurn(params: { requestId: string; channelUrl?: string }): void {
-        if (this.collectedCount >= 10) return;
-        if (this.random() >= 0.15) return;
+        if (this.collectedCount >= MAX_COLLECTED_COUNT) return;
+        if (!isIncludedInSample(this.samplingRate)) return;
         this.collectedCount += 1;
-        this.sampledByRequestId.set(params.requestId, {
-            requestId: params.requestId,
-            channelUrl: params.channelUrl,
-            startedAt: this.clock.now(),
-        });
+
+        const record: StatsRecord<UserPerceivedResponseTimeStats, UserPerceivedResponseTimeMeasure> = {
+            stats: new UserPerceivedResponseTimeStats().setCommitCallback(this.commitCallback),
+            measure: {
+                channelUrl: params.channelUrl,
+                requestId: params.requestId,
+                startedAt: performance.now(),
+            },
+        };
+        this.records.set(params.requestId, record);
     }
 
     markUserMessageAck(params: { requestId: string; messageId: number }): void {
-        const turn = this.sampledByRequestId.get(params.requestId);
-        if (!turn) return;
+        const record = this.records.get(params.requestId);
+        if (!record) return;
 
-        turn.ackAt = this.clock.now();
-        turn.userMessageId = params.messageId;
+        record.measure.ackAt = performance.now();
+        record.measure.userMessageId = params.messageId;
 
         const pending = this.pendingAIResponseByUserMessageId.get(params.messageId);
         if (!pending) return;
         this.pendingAIResponseByUserMessageId.delete(params.messageId);
-        this.applyAIResponseRaw(turn, pending);
+        this.applyAIResponseRaw(record, pending);
     }
 
     replaceTurnRequestId(currentRequestId: string, nextRequestId: string): void {
         if (currentRequestId === nextRequestId) return;
 
-        const turn = this.sampledByRequestId.get(currentRequestId);
-        if (!turn) return;
+        const record = this.records.get(currentRequestId);
+        if (!record) return;
 
-        this.sampledByRequestId.delete(currentRequestId);
-        turn.requestId = nextRequestId;
-        this.sampledByRequestId.set(nextRequestId, turn);
+        this.records.delete(currentRequestId);
+        record.measure.requestId = nextRequestId;
+        this.records.set(nextRequestId, record);
     }
 
     cancelTurn(requestId: string): void {
-        const turn = this.sampledByRequestId.get(requestId);
-        if (!turn) return;
-        this.deleteTurn(turn);
+        const record = this.records.get(requestId);
+        if (!record) return;
+        this.deleteRecord(record);
         // Return the unused sample slot so cancelled turns don't burn the per-session cap.
         if (this.collectedCount > 0) this.collectedCount -= 1;
     }
 
     markAIResponseRaw(params: { messageId: number; channelUrl?: string; aiResponse: AIResponseMessageMetadata }): void {
-        const firstChunkAt = this.clock.now();
+        const firstChunkAt = performance.now();
         const userMessageId = params.aiResponse.userMessageId;
-        if (userMessageId === undefined && this.hasUnackedTurn(params.channelUrl)) return;
+        if (userMessageId === undefined && hasUnackedChannelTurn(this.records.values(), params.channelUrl)) return;
 
-        const turn = this.findPendingTurn(params.channelUrl, userMessageId);
-        if (turn) {
-            this.applyAIResponseRaw(turn, { ...params, firstChunkAt });
+        const record = this.findPendingRecord(params.channelUrl, userMessageId);
+        if (record) {
+            this.applyAIResponseRaw(record, { ...params, firstChunkAt });
             return;
         }
 
-        if (userMessageId === undefined || !this.hasUnackedTurn(params.channelUrl)) return;
+        if (userMessageId === undefined || !hasUnackedChannelTurn(this.records.values(), params.channelUrl)) return;
         this.bufferAIResponseRaw(
             {
             messageId: params.messageId,
@@ -7041,26 +7762,31 @@ declare class UserPerceivedResponseTimeStatsTracker {
     }
 
     markAIResponseVisible(aiMessageId: number): boolean {
-        const turn = this.sampledByAIMessageId.get(aiMessageId);
-        if (!turn || turn.ackAt === undefined || turn.firstChunkAt === undefined || turn.userMessageId === undefined)
-        return false;
+        const record = this.findRecordByAIMessageId(aiMessageId);
+        if (!record) return false;
 
-        const renderedAt = this.clock.now();
-        append(this.callback, METRIC_KEY_USER_PERCEIVED_RESPONSE_TIME, renderedAt - turn.startedAt, {
-            extra: {
-                ack_to_first_chunk_ms: turn.firstChunkAt - turn.ackAt,
-                first_chunk_to_render_ms: renderedAt - turn.firstChunkAt,
-                is_streaming: Boolean(turn.isStreaming),
-                send_to_ack_ms: turn.ackAt - turn.startedAt,
-            },
-        });
+        const measure = record.measure;
+        if (measure.ackAt === undefined || measure.firstChunkAt === undefined || measure.userMessageId === undefined) {
+            return false;
+        }
 
-        this.deleteTurn(turn);
+        const renderedAt = performance.now();
+        record.stats
+        .setDurations({
+            ackToFirstChunkMs: measure.firstChunkAt - measure.ackAt,
+            firstChunkToRenderMs: renderedAt - measure.firstChunkAt,
+            isStreaming: Boolean(measure.isStreaming),
+            sendToAckMs: measure.ackAt - measure.startedAt,
+            totalDurationMs: renderedAt - measure.startedAt,
+        })
+        .commit();
+
+        this.deleteRecord(record);
         return true;
     }
 
     hasPendingAIResponse(aiMessageId: number): boolean {
-        return this.sampledByAIMessageId.has(aiMessageId);
+        return this.findRecordByAIMessageId(aiMessageId) !== undefined;
     }
 
     clearMessage(aiMessageId: number): void {
@@ -7068,18 +7794,18 @@ declare class UserPerceivedResponseTimeStatsTracker {
             if (pending.messageId === aiMessageId) this.pendingAIResponseByUserMessageId.delete(userMessageId);
         });
 
-        const turn = this.sampledByAIMessageId.get(aiMessageId);
-        if (!turn) return;
+        const record = this.findRecordByAIMessageId(aiMessageId);
+        if (!record) return;
 
-        this.deleteTurn(turn);
+        this.deleteRecord(record);
         if (this.collectedCount > 0) this.collectedCount -= 1;
     }
 
     clearChannel(channelUrl?: string): void {
         if (!channelUrl) return;
-        this.sampledByRequestId.forEach((turn) => {
-            if (turn.channelUrl !== channelUrl) return;
-            this.deleteTurn(turn);
+        this.records.forEach((record) => {
+            if (record.measure.channelUrl !== channelUrl) return;
+            this.deleteRecord(record);
             if (this.collectedCount > 0) this.collectedCount -= 1;
         });
         this.pendingAIResponseByUserMessageId.forEach((pending, userMessageId) => {
@@ -7088,40 +7814,54 @@ declare class UserPerceivedResponseTimeStatsTracker {
     }
 
     clear(): void {
-        this.sampledByRequestId.clear();
-        this.sampledByAIMessageId.clear();
+        this.records.clear();
         this.pendingAIResponseByUserMessageId.clear();
         this.collectedCount = 0;
     }
 
-    private findPendingTurn(channelUrl?: string, userMessageId?: number): UserTurn | undefined {
+    private findRecordByAIMessageId(
+    aiMessageId: number,
+    ): StatsRecord<UserPerceivedResponseTimeStats, UserPerceivedResponseTimeMeasure> | undefined {
+        for (const record of this.records.values()) {
+            if (record.measure.aiMessageId === aiMessageId) return record;
+        }
+        return undefined;
+    }
+
+    private findPendingRecord(
+    channelUrl?: string,
+    userMessageId?: number,
+    ): StatsRecord<UserPerceivedResponseTimeStats, UserPerceivedResponseTimeMeasure> | undefined {
         if (userMessageId !== undefined) {
-            for (const turn of this.sampledByRequestId.values()) {
-                if (turn.ackAt === undefined || turn.firstChunkAt !== undefined) continue;
-                if (!matchesChannel(turn, channelUrl)) continue;
-                if (turn.userMessageId === userMessageId) return turn;
+            for (const record of this.records.values()) {
+                if (record.measure.ackAt === undefined || record.measure.firstChunkAt !== undefined) continue;
+                if (!matchesChannel(record.measure.channelUrl, channelUrl)) continue;
+                if (record.measure.userMessageId === userMessageId) return record;
             }
             return undefined;
         }
 
-        let match: UserTurn | undefined;
-        for (const turn of this.sampledByRequestId.values()) {
-            if (turn.ackAt === undefined || turn.firstChunkAt !== undefined) continue;
-            if (!matchesChannel(turn, channelUrl)) continue;
+        let match: StatsRecord<UserPerceivedResponseTimeStats, UserPerceivedResponseTimeMeasure> | undefined;
+        for (const record of this.records.values()) {
+            if (record.measure.ackAt === undefined || record.measure.firstChunkAt !== undefined) continue;
+            if (!matchesChannel(record.measure.channelUrl, channelUrl)) continue;
             if (match) return undefined;
-            match = turn;
+            match = record;
         }
         return match;
     }
 
-    private applyAIResponseRaw(turn: UserTurn, params: PendingAIResponseRaw): void {
-        if (turn.firstChunkAt !== undefined) return;
+    private applyAIResponseRaw(
+    record: StatsRecord<UserPerceivedResponseTimeStats, UserPerceivedResponseTimeMeasure>,
+    params: PendingAIResponseRaw,
+    ): void {
+        if (record.measure.firstChunkAt !== undefined) return;
 
-        turn.firstChunkAt = turn.ackAt === undefined ? params.firstChunkAt : Math.max(params.firstChunkAt, turn.ackAt);
-        turn.aiMessageId = params.messageId;
-        turn.channelUrl = turn.channelUrl ?? params.channelUrl;
-        turn.isStreaming = params.aiResponse.isStreaming;
-        this.sampledByAIMessageId.set(params.messageId, turn);
+        record.measure.firstChunkAt =
+        record.measure.ackAt === undefined ? params.firstChunkAt : Math.max(params.firstChunkAt, record.measure.ackAt);
+        record.measure.aiMessageId = params.messageId;
+        record.measure.channelUrl = record.measure.channelUrl ?? params.channelUrl;
+        record.measure.isStreaming = params.aiResponse.isStreaming;
     }
 
     private bufferAIResponseRaw(params: PendingAIResponseRaw, userMessageId: number): void {
@@ -7131,14 +7871,10 @@ declare class UserPerceivedResponseTimeStatsTracker {
         }
     }
 
-    private hasUnackedTurn(channelUrl?: string): boolean {
-        return hasUnackedChannelTurn(this.sampledByRequestId.values(), channelUrl);
-    }
-
-    private deleteTurn(turn: UserTurn): void {
-        this.sampledByRequestId.delete(turn.requestId);
-        if (turn.aiMessageId !== undefined) this.sampledByAIMessageId.delete(turn.aiMessageId);
-        if (turn.userMessageId !== undefined) this.pendingAIResponseByUserMessageId.delete(turn.userMessageId);
+    private deleteRecord(record: StatsRecord<UserPerceivedResponseTimeStats, UserPerceivedResponseTimeMeasure>): void {
+        this.records.delete(record.measure.requestId);
+        if (record.measure.userMessageId !== undefined)
+        this.pendingAIResponseByUserMessageId.delete(record.measure.userMessageId);
     }
 }
 
@@ -7159,17 +7895,6 @@ declare interface UserSessionInfo {
     sessionHandler: AIAgentSessionHandler;
 }
 
-declare type UserTurn = {
-    requestId: string;
-    channelUrl?: string;
-    startedAt: number;
-    ackAt?: number;
-    firstChunkAt?: number;
-    userMessageId?: number;
-    aiMessageId?: number;
-    isStreaming?: boolean;
-};
-
 export { }