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>

Author: antonis

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/timetodisplay.tsx

@@ -41,9 +41,11 @@ const FRAME_DATA_CLEANUP_TIMEOUT_MS = 60_000;
 export const manualInitialDisplaySpans = new WeakMap<Span, true>();
 
 /**
- * Flag full display called before initial display for an active span.
+ * Stores deferred full display state when reportFullyDisplayed / updateFullDisplaySpan
+ * is called before TTID completes. Preserves the isAutoInstrumented flag so the
+ * correct span origin is applied when the deferred call fires.
  */
-const fullDisplayBeforeInitialDisplay = new WeakMap<Span, true>();
+const fullDisplayBeforeInitialDisplay = new WeakMap<Span, { isAutoInstrumented: boolean }>();
 
 interface FrameDataForSpan {
   startFrames: NativeFramesResponse | null;
@@ -391,10 +393,11 @@ export function updateInitialDisplaySpan(
       span.setStatus({ code: SPAN_STATUS_OK });
       debug.log(`[TimeToDisplay] ${spanToJSON(span).description} span updated with end timestamp and frame data.`);
 
-      if (fullDisplayBeforeInitialDisplay.has(activeSpan)) {
+      const deferred = fullDisplayBeforeInitialDisplay.get(activeSpan);
+      if (deferred) {
         fullDisplayBeforeInitialDisplay.delete(activeSpan);
         debug.log(`[TimeToDisplay] Updating full display with initial display (${span.spanContext().spanId}) end.`);
-        updateFullDisplaySpan(frameTimestampSeconds, span);
+        updateFullDisplaySpan(frameTimestampSeconds, span, deferred.isAutoInstrumented);
       }
 
       setSpanDurationAsMeasurementOnSpan('time_to_initial_display', span, activeSpan);
@@ -404,17 +407,36 @@ export function updateInitialDisplaySpan(
       span.end(frameTimestampSeconds);
       span.setStatus({ code: SPAN_STATUS_OK });
 
-      if (fullDisplayBeforeInitialDisplay.has(activeSpan)) {
+      const deferred = fullDisplayBeforeInitialDisplay.get(activeSpan);
+      if (deferred) {
         fullDisplayBeforeInitialDisplay.delete(activeSpan);
         debug.log(`[TimeToDisplay] Updating full display with initial display (${span.spanContext().spanId}) end.`);
-        updateFullDisplaySpan(frameTimestampSeconds, span);
+        updateFullDisplaySpan(frameTimestampSeconds, span, deferred.isAutoInstrumented);
       }
 
       setSpanDurationAsMeasurementOnSpan('time_to_initial_display', span, activeSpan);
     });
 }
 
-function updateFullDisplaySpan(frameTimestampSeconds: number, passedInitialDisplaySpan?: Span): void {
+/**
+ * Reports that the screen is fully displayed.
+ *
+ * Ends the TTFD span (`ui.load.full_display`) with the current timestamp.
+ * If called before TTID completes, the TTFD span is deferred until TTID ends.
+ * Subsequent calls are ignored once the span has ended.
+ *
+ * This is the imperative equivalent of the `<TimeToFullDisplay>` component,
+ * matching the cross-SDK `Sentry.reportFullyDisplayed()` API.
+ */
+export function reportFullyDisplayed(): void {
+  updateFullDisplaySpan(Date.now() / 1000, undefined, false);
+}
+
+function updateFullDisplaySpan(
+  frameTimestampSeconds: number,
+  passedInitialDisplaySpan?: Span,
+  isAutoInstrumented: boolean = true,
+): void {
   const activeSpan = getActiveSpan();
   if (!activeSpan) {
     debug.warn('[TimeToDisplay] No active span found to update ui.load.full_display in.');
@@ -426,15 +448,15 @@ function updateFullDisplaySpan(frameTimestampSeconds: number, passedInitialDispl
     getSpanDescendants(activeSpan).find(span => spanToJSON(span).op === 'ui.load.initial_display');
   const initialDisplayEndTimestamp = existingInitialDisplaySpan && spanToJSON(existingInitialDisplaySpan).timestamp;
   if (!initialDisplayEndTimestamp) {
-    fullDisplayBeforeInitialDisplay.set(activeSpan, true);
+    fullDisplayBeforeInitialDisplay.set(activeSpan, { isAutoInstrumented });
     debug.warn(
       `[TimeToDisplay] Full display called before initial display for active span (${activeSpan.spanContext().spanId}).`,
     );
     return;
   }
 
   const span = startTimeToFullDisplaySpan({
-    isAutoInstrumented: true,
+    isAutoInstrumented,
   });
   if (!span) {
     debug.warn('[TimeToDisplay] No TimeToFullDisplay span found or created, possibly performance is disabled.');

packages/core/test/tracing/timetodisplay.test.tsx

@@ -31,6 +31,7 @@ import {
 } from '../../src/js/tracing/semanticAttributes';
 import { SPAN_THREAD_NAME, SPAN_THREAD_NAME_JAVASCRIPT } from '../../src/js/tracing/span';
 import {
+  reportFullyDisplayed,
   startTimeToFullDisplaySpan,
   startTimeToInitialDisplaySpan,
   TimeToFullDisplay,
@@ -990,3 +991,161 @@ describe('Frame Data', () => {
     });
   });
 });
+
+describe('reportFullyDisplayed', () => {
+  let client: TestClient;
+
+  beforeEach(() => {
+    clearMockedOnDrawReportedProps();
+    _resetTimeToDisplayCoordinator();
+    getCurrentScope().clear();
+    getIsolationScope().clear();
+    getGlobalScope().clear();
+
+    const options = getDefaultTestClientOptions({
+      tracesSampleRate: 1.0,
+    });
+    client = new TestClient({
+      ...options,
+      integrations: [...options.integrations, timeToDisplayIntegration()],
+    });
+    setCurrentClient(client);
+    client.init();
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+    mockWrapper.NATIVE.enableNative = true;
+  });
+
+  test('creates full display span with manual origin and measurement', async () => {
+    await startSpanManual(
+      {
+        name: 'Root Manual Span',
+        startTime: secondAgoTimestampMs(),
+      },
+      async (activeSpan: Span | undefined) => {
+        const ttidSpan = startTimeToInitialDisplaySpan();
+        render(<TimeToInitialDisplay record={true} />);
+
+        await Promise.resolve();
+        await Promise.resolve();
+        await Promise.resolve();
+
+        updateInitialDisplaySpan(nowInSeconds(), { activeSpan, span: ttidSpan });
+
+        for (let i = 0; i < 15; i++) {
+          await Promise.resolve();
+        }
+
+        reportFullyDisplayed();
+
+        for (let i = 0; i < 15; i++) {
+          await Promise.resolve();
+        }
+
+        activeSpan?.end();
+      },
+    );
+
+    await jest.runOnlyPendingTimersAsync();
+    await client.flush();
+
+    const ttfdSpan = getFullDisplaySpanJSON(client.event!.spans!);
+    expect(ttfdSpan).toBeDefined();
+    expect(ttfdSpan!.op).toBe('ui.load.full_display');
+    expect(ttfdSpan!.status).toBe('ok');
+    expect(ttfdSpan!.timestamp).toBeDefined();
+    expect(ttfdSpan!.data[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]).toBe(SPAN_ORIGIN_MANUAL_UI_TIME_TO_DISPLAY);
+    expectFullDisplayMeasurementOnSpan(client.event!);
+  });
+
+  test('defers full display when called before initial display with correct origin', async () => {
+    await startSpanManual(
+      {
+        name: 'Root Manual Span',
+        startTime: secondAgoTimestampMs(),
+      },
+      async (activeSpan: Span | undefined) => {
+        const ttidSpan = startTimeToInitialDisplaySpan();
+        render(<TimeToInitialDisplay record={true} />);
+
+        await Promise.resolve();
+        await Promise.resolve();
+        await Promise.resolve();
+
+        reportFullyDisplayed();
+
+        updateInitialDisplaySpan(nowInSeconds(), { activeSpan, span: ttidSpan });
+
+        for (let i = 0; i < 15; i++) {
+          await Promise.resolve();
+        }
+
+        activeSpan?.end();
+      },
+    );
+
+    await jest.runOnlyPendingTimersAsync();
+    await client.flush();
+
+    const ttfdSpan = getFullDisplaySpanJSON(client.event!.spans!);
+    expect(ttfdSpan).toBeDefined();
+    expect(ttfdSpan!.op).toBe('ui.load.full_display');
+    expect(ttfdSpan!.status).toBe('ok');
+    expect(ttfdSpan!.data[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]).toBe(SPAN_ORIGIN_MANUAL_UI_TIME_TO_DISPLAY);
+
+    const ttidSpanJSON = getInitialDisplaySpanJSON(client.event!.spans!);
+    expect(ttfdSpan!.timestamp).toEqual(ttidSpanJSON!.timestamp);
+
+    expectFullDisplayMeasurementOnSpan(client.event!);
+  });
+
+  test('does nothing without an active span', () => {
+    expect(() => reportFullyDisplayed()).not.toThrow();
+    expect(debug.warn).toHaveBeenCalledWith(expect.stringContaining('No active span found'));
+  });
+
+  test('second call is ignored after span already ended', async () => {
+    await startSpanManual(
+      {
+        name: 'Root Manual Span',
+        startTime: secondAgoTimestampMs(),
+      },
+      async (activeSpan: Span | undefined) => {
+        const ttidSpan = startTimeToInitialDisplaySpan();
+        render(<TimeToInitialDisplay record={true} />);
+
+        await Promise.resolve();
+        await Promise.resolve();
+        await Promise.resolve();
+
+        updateInitialDisplaySpan(nowInSeconds(), { activeSpan, span: ttidSpan });
+
+        for (let i = 0; i < 15; i++) {
+          await Promise.resolve();
+        }
+
+        reportFullyDisplayed();
+
+        for (let i = 0; i < 15; i++) {
+          await Promise.resolve();
+        }
+
+        reportFullyDisplayed();
+
+        for (let i = 0; i < 15; i++) {
+          await Promise.resolve();
+        }
+
+        activeSpan?.end();
+      },
+    );
+
+    await jest.runOnlyPendingTimersAsync();
+    await client.flush();
+
+    const ttfdSpans = client.event!.spans!.filter((s: SpanJSON) => s.op === 'ui.load.full_display');
+    expect(ttfdSpans).toHaveLength(1);
+  });
+});