feat(tracing): Add reportFullyDisplayed() static API (#6419)

* feat(tracing): Add `reportFullyDisplayed()` static API

Add imperative `Sentry.reportFullyDisplayed()` API for signaling Time to
Full Display, matching the cross-SDK spec at develop.sentry.dev. This is
the imperative equivalent of the `<TimeToFullDisplay>` component.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: Add changelog entry for reportFullyDisplayed

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(tracing): Route reportFullyDisplayed through the integration

Store the timestamp in a JS-side map and let the timeToDisplayIntegration
pick it up during processEvent, instead of calling updateFullDisplaySpan
directly. The previous approach failed in production because it relied on
updateInitialDisplaySpan to drain the deferred queue, but that function
is never called in the real component/navigation flow — TTID timestamps
are read from native during processEvent.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(tracing): Use root span ID for imperative TTFD and guard duplicate spans

- Use `getRootSpan` in `reportFullyDisplayed()` so the stored key matches the
  integration's `rootSpanId` lookup, even when called inside a nested child span.
- Add early return in `addTimeToFullDisplay` when an existing ok TTFD span is
  found, preventing duplicate `ui.load.full_display` spans.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(tracing): Always pop imperative TTFD timestamp to prevent leak

Pop both native and imperative timestamps unconditionally so the
imperative entry is cleaned up even when native takes priority.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(tracing): Use timestampInSeconds and cap imperative TTFD map size

- Use `timestampInSeconds()` instead of `Date.now() / 1000` for clock
  consistency with the rest of the tracing module.
- Cap `_imperativeTtfdTimestamps` at 50 entries, evicting the oldest
  when full, to prevent unbounded growth on sampled-out transactions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Update changelog

* fix(tracing): Add timestamp guard to TTFD early-return, matching TTID pattern

Only return existing ok/unfinished TTFD span when no new timestamp is
available, so an imperative timestamp can still update an unfinished span.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(tracing): Restructure TTFD flow to eliminate dead code in existing-span guard

Split the combined `!ttidSpan || !ttfdEndTimestampSeconds` check so the
existing ok TTFD span guard runs between them, matching the TTID pattern.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(tracing): Update existing TTFD span when both component and imperative API are used

Broadens the existing-span update condition to handle spans with
undefined or ok status, preventing duplicate ui.load.full_display spans
when <TimeToFullDisplay> and reportFullyDisplayed() are both used.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(tracing): Fix existing-span update for both TTID and TTFD, add combined-use test

Broaden the TTID existing-span update condition to match the TTFD fix,
preventing duplicate spans when a component span with ok/undefined
status exists alongside a native timestamp. Add test for combined
<TimeToFullDisplay> component + reportFullyDisplayed() usage.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: antonis

CHANGELOG.md

@@ -6,6 +6,12 @@
 > make sure you follow our [migration guide](https://docs.sentry.io/platforms/react-native/migration/) first.
 <!-- prettier-ignore-end -->
 
+## Unreleased
+
+### Features
+
+- Add `Sentry.reportFullyDisplayed()` imperative API for signaling Time to Full Display ([#6419](https://github.com/getsentry/sentry-react-native/pull/6419))
+
 ## 8.18.0
 
 ### Features

packages/core/etc/sentry-react-native.api.md

@@ -633,6 +633,9 @@ export const reactNavigationIntegration: (input?: Partial<ReactNavigationIntegra
     options: ReactNavigationIntegrationOptions;
 };
 
+// @public
+export function reportFullyDisplayed(): void;
+
 // @public
 export function resumeAppHangTracking(): void;
 

packages/core/src/js/index.ts

@@ -132,6 +132,7 @@ export {
   TimeToFullDisplay,
   startTimeToInitialDisplaySpan,
   startTimeToFullDisplaySpan,
+  reportFullyDisplayed,
   startIdleNavigationSpan,
   startIdleSpan,
   getDefaultIdleNavigationSpanOptions,

packages/core/src/js/tracing/integrations/timeToDisplayIntegration.ts

@@ -8,6 +8,7 @@ import { SPAN_ORIGIN_AUTO_UI_TIME_TO_DISPLAY, SPAN_ORIGIN_MANUAL_UI_TIME_TO_DISP
 import { getReactNavigationIntegration } from '../reactnavigation';
 import { SEMANTIC_ATTRIBUTE_ROUTE_HAS_BEEN_SEEN } from '../semanticAttributes';
 import { SPAN_THREAD_NAME, SPAN_THREAD_NAME_JAVASCRIPT } from '../span';
+import { _popImperativeTtfdTimestamp } from '../timetodisplay';
 import { clearSpan as clearTimeToDisplayCoordinatorSpan } from '../timeToDisplayCoordinator';
 import { getTimeToInitialDisplayFallback } from '../timeToDisplayFallback';
 import { createSpanJSON } from '../utils';
@@ -140,7 +141,7 @@ async function addTimeToInitialDisplay({
   const manualDurationMs = (ttidEndTimestampSeconds - transactionStartTimestampSeconds) * 1000;
   const manualStatus = isDeadlineExceeded(manualDurationMs) ? 'deadline_exceeded' : 'ok';
 
-  if (ttidSpan?.status && ttidSpan.status !== 'ok') {
+  if (ttidSpan) {
     ttidSpan.status = manualStatus;
     ttidSpan.timestamp = ttidEndTimestampSeconds;
     debug.log(`[${INTEGRATION_NAME}] Updated existing ttid span.`, ttidSpan);
@@ -224,16 +225,27 @@ async function addTimeToFullDisplay({
   transactionStartTimestampSeconds: number;
   ttidSpan: SpanJSON | undefined;
 }): Promise<SpanJSON | undefined> {
-  const ttfdEndTimestampSeconds = await NATIVE.popTimeToDisplayFor(`ttfd-${rootSpanId}`);
+  const nativeTtfdTimestamp = await NATIVE.popTimeToDisplayFor(`ttfd-${rootSpanId}`);
+  const imperativeTtfdTimestamp = _popImperativeTtfdTimestamp(rootSpanId);
+  const ttfdEndTimestampSeconds = nativeTtfdTimestamp ?? imperativeTtfdTimestamp;
 
-  if (!ttidSpan || !ttfdEndTimestampSeconds) {
+  if (!ttidSpan) {
     return undefined;
   }
 
   event.spans = event.spans || [];
 
   let ttfdSpan = event.spans?.find(span => span.op === UI_LOAD_FULL_DISPLAY);
 
+  if (ttfdSpan && (ttfdSpan.status === undefined || ttfdSpan.status === 'ok') && !ttfdEndTimestampSeconds) {
+    debug.log(`[${INTEGRATION_NAME}] Ttfd span already exists and is ok.`, ttfdSpan);
+    return ttfdSpan;
+  }
+
+  if (!ttfdEndTimestampSeconds) {
+    return undefined;
+  }
+
   let ttfdAdjustedEndTimestampSeconds = ttfdEndTimestampSeconds;
   const ttfdIsBeforeTtid = ttidSpan.timestamp && ttfdEndTimestampSeconds < ttidSpan.timestamp;
   if (ttfdIsBeforeTtid && ttidSpan.timestamp) {
@@ -244,7 +256,7 @@ async function addTimeToFullDisplay({
 
   const ttfdStatus = isDeadlineExceeded(durationMs) ? 'deadline_exceeded' : 'ok';
 
-  if (ttfdSpan?.status && ttfdSpan.status !== 'ok') {
+  if (ttfdSpan) {
     ttfdSpan.status = ttfdStatus;
     ttfdSpan.timestamp = ttfdAdjustedEndTimestampSeconds;
     debug.log(`[${INTEGRATION_NAME}] Updated existing ttfd span.`, ttfdSpan);

packages/core/src/js/tracing/timetodisplay.tsx

@@ -5,12 +5,14 @@ import {
   debug,
   fill,
   getActiveSpan,
+  getRootSpan,
   getSpanDescendants,
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
   SPAN_STATUS_ERROR,
   SPAN_STATUS_OK,
   spanToJSON,
   startInactiveSpan,
+  timestampInSeconds,
 } from '@sentry/core';
 import * as React from 'react';
 import { useEffect, useReducer, useRef, useState } from 'react';
@@ -414,6 +416,57 @@ export function updateInitialDisplaySpan(
     });
 }
 
+/**
+ * Timestamps stored by the imperative `reportFullyDisplayed()` API.
+ * Keyed by the root span's span_id at call time.
+ * Consumed by `timeToDisplayIntegration.processEvent`.
+ */
+const _imperativeTtfdTimestamps = new Map<string, number>();
+const MAX_IMPERATIVE_TTFD_ENTRIES = 50;
+
+/**
+ * Reports that the screen is fully displayed.
+ *
+ * Stores the current timestamp so the Time to Display integration
+ * can create the TTFD span (`ui.load.full_display`) during event processing.
+ * If called before TTID completes, the integration adjusts the TTFD
+ * timestamp to the TTID end (per the cross-SDK spec).
+ * Subsequent calls for the same span are ignored.
+ *
+ * This is the imperative equivalent of the `<TimeToFullDisplay>` component,
+ * matching the cross-SDK `Sentry.reportFullyDisplayed()` API.
+ */
+export function reportFullyDisplayed(): void {
+  const activeSpan = getActiveSpan();
+  if (!activeSpan) {
+    debug.warn('[TimeToDisplay] No active span found to report full display.');
+    return;
+  }
+  const rootSpan = getRootSpan(activeSpan);
+  const rootSpanId = spanToJSON(rootSpan).span_id;
+  if (rootSpanId && !_imperativeTtfdTimestamps.has(rootSpanId)) {
+    if (_imperativeTtfdTimestamps.size >= MAX_IMPERATIVE_TTFD_ENTRIES) {
+      const oldestKey = _imperativeTtfdTimestamps.keys().next().value;
+      if (oldestKey) {
+        _imperativeTtfdTimestamps.delete(oldestKey);
+      }
+    }
+    _imperativeTtfdTimestamps.set(rootSpanId, timestampInSeconds());
+  }
+}
+
+export function _popImperativeTtfdTimestamp(spanId: string): number | undefined {
+  const ts = _imperativeTtfdTimestamps.get(spanId);
+  if (ts !== undefined) {
+    _imperativeTtfdTimestamps.delete(spanId);
+  }
+  return ts;
+}
+
+export function _resetImperativeTtfdTimestamps(): void {
+  _imperativeTtfdTimestamps.clear();
+}
+
 function updateFullDisplaySpan(frameTimestampSeconds: number, passedInitialDisplaySpan?: Span): void {
   const activeSpan = getActiveSpan();
   if (!activeSpan) {