Fixes

Author: alwx

CHANGELOG.md

@@ -19,6 +19,7 @@
     ```
   - The existing `record` prop is **unchanged** and continues to behave exactly as before — instances using `record` are independent and do not gate or get gated by `ready` peers. Existing apps require no migration.
   - `record` is now deprecated in favor of `ready`. Migrating to `ready` is a one-line rename that opts the instance into multi-instance coordination. `record` will be removed in the next major version.
+  - Mounting a not-yet-ready peer on the next render commit (typical `useEffect` → `setState` → child mount waves) cancels any pending fire from an earlier-ready peer, preventing premature TTFD recording. Up-flips of the aggregate are deferred by one macrotask to absorb same-task peer mounts; down-flips are immediate.
 
 ### Fixes
 

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

@@ -4,6 +4,7 @@ import { debug } from '@sentry/core';
 
 import { NATIVE } from '../../wrapper';
 import { UI_LOAD_FULL_DISPLAY, UI_LOAD_INITIAL_DISPLAY } from '../ops';
+import { clearSpan as clearTimeToDisplayCoordinatorSpan } from '../timeToDisplayCoordinator';
 import { SPAN_ORIGIN_AUTO_UI_TIME_TO_DISPLAY, SPAN_ORIGIN_MANUAL_UI_TIME_TO_DISPLAY } from '../origin';
 import { getReactNavigationIntegration } from '../reactnavigation';
 import { SEMANTIC_ATTRIBUTE_ROUTE_HAS_BEEN_SEEN } from '../semanticAttributes';
@@ -86,6 +87,12 @@ export const timeToDisplayIntegration = (): Integration => {
         event.timestamp = newTransactionEndTimestampSeconds;
       }
 
+      // Drop the per-span coordinator state now that we've read the native
+      // ttid/ttfd values. Prevents the module-level registries from
+      // accumulating entries for screens that outlive their span (keep-alive,
+      // idle-timeout discarded transactions, etc.).
+      clearTimeToDisplayCoordinatorSpan(rootSpanId);
+
       return event;
     },
   };

packages/core/src/js/tracing/timeToDisplayCoordinator.ts

@@ -1,6 +1,27 @@
 /**
  * Coordinator for multi-instance `<TimeToInitialDisplay>` / `<TimeToFullDisplay>`
  * components on a single screen (active span).
+ *
+ * The aggregate "ready" state exposed via `isAllReady` is *deferred* on its
+ * way up: when the raw aggregate flips false→true, we schedule the public
+ * value to flip on the next macrotask. Down-flips (true→false) are
+ * immediate and cancel any pending up-flip.
+ *
+ * Why: in React 18, a typical "parent renders → parent useEffect setState
+ * → child mounts on next commit" wave executes synchronously inside one
+ * event-loop task. A `setTimeout(0)` reliably runs after that whole wave,
+ * so cross-commit-but-same-task peer registrations are absorbed before the
+ * coordinator declares itself ready. Without the defer, a header that
+ * registers and is alone-and-ready would emit `fullDisplay=true`
+ * immediately, the native reporter would fire on the next draw, and a
+ * sibling sidebar mounting on the next commit could only un-ready the
+ * aggregate after the (now stuck) native timestamp has already been
+ * recorded.
+ *
+ * The defer does NOT cover arbitrary-async deferred mounting (e.g. mount a
+ * checkpoint after a fetch resolves). That class of usage is documented
+ * against — the recommended pattern is to mount all checkpoints at screen
+ * mount with `ready=false` and flip them as data arrives.
  */
 
 type Checkpoint = { ready: boolean };
@@ -10,12 +31,20 @@ interface SpanRegistry {
   checkpoints: Map<string, Checkpoint>;
   listeners: Set<Listener>;
   /**
-   * Last-observed aggregate ready state. Used to avoid waking subscribers when
-   * a checkpoint change does not flip the aggregate — the dominant lifecycle
-   * pattern is "all checkpoints register as not-ready, then flip to ready over
-   * time", and only the final flip needs to notify.
+   * Stable, deferred view of the aggregate exposed via `isAllReady`. Lags
+   * raw `computeAggregate` on up-flips by `READY_DEFER_MS`, immediate on
+   * down-flips. Used to avoid waking subscribers when a checkpoint change
+   * does not flip the aggregate — the dominant lifecycle pattern is "all
+   * checkpoints register as not-ready, then flip to ready over time", and
+   * only the final flip needs to notify.
    */
   aggregateReady: boolean;
+  /**
+   * Pending up-flip timer. When non-null, an up-flip is scheduled but has
+   * not yet been applied to `aggregateReady`. Cleared either when the timer
+   * fires or when an intervening change cancels the pending up-flip.
+   */
+  pendingUpFlip: ReturnType<typeof setTimeout> | null;
   /**
    * Checkpoint ids whose components have unmounted but are kept in the
    * registry to prevent a premature aggregate flip (sole-blocker safeguard).
@@ -25,6 +54,12 @@ interface SpanRegistry {
   sticky: Set<string>;
 }
 
+/**
+ * Defer applied to up-flips. Zero macrotask is enough to absorb a same-task
+ * cascade of useEffect-driven child mounts in React 18.
+ */
+const READY_DEFER_MS = 0;
+
 const TTID = 'ttid';
 const TTFD = 'ttfd';
 
@@ -43,13 +78,21 @@ function getOrCreate(kind: DisplayKind, parentSpanId: string): SpanRegistry {
       checkpoints: new Map(),
       listeners: new Set(),
       aggregateReady: false,
+      pendingUpFlip: null,
       sticky: new Set(),
     };
     map.set(parentSpanId, entry);
   }
   return entry;
 }
 
+function cancelPendingUpFlip(entry: SpanRegistry): void {
+  if (entry.pendingUpFlip !== null) {
+    clearTimeout(entry.pendingUpFlip);
+    entry.pendingUpFlip = null;
+  }
+}
+
 function computeAggregate(entry: SpanRegistry): boolean {
   if (entry.checkpoints.size === 0) {
     return false;
@@ -63,17 +106,47 @@ function computeAggregate(entry: SpanRegistry): boolean {
 }
 
 /**
- * Recompute the aggregate; if it flipped, update the cached value and notify.
- * No-op when the aggregate is unchanged — this is what avoids the O(N²)
- * notify-storm when many checkpoints register/update without crossing the
- * aggregate boundary.
+ * Recompute the raw aggregate and reconcile it with the cached
+ * `aggregateReady`. Up-flips are deferred to absorb same-task peer mounts;
+ * down-flips are immediate and cancel any pending up-flip.
+ *
+ * Transition matrix (raw, stable) → action:
+ *   (false, false): no-op; cancel pending up-flip if any (it became stale).
+ *   (true,  true):  no-op; cancel pending up-flip if any.
+ *   (false, true):  immediate down-flip + notify; cancel pending up-flip.
+ *   (true,  false): schedule up-flip if not already pending.
  */
 function reevaluate(entry: SpanRegistry): void {
-  const next = computeAggregate(entry);
-  if (next === entry.aggregateReady) {
+  const raw = computeAggregate(entry);
+
+  if (raw === entry.aggregateReady) {
+    cancelPendingUpFlip(entry);
     return;
   }
-  entry.aggregateReady = next;
+
+  if (!raw) {
+    cancelPendingUpFlip(entry);
+    entry.aggregateReady = false;
+    notifyListeners(entry);
+    return;
+  }
+
+  // raw=true, stable=false: schedule deferred up-flip.
+  if (entry.pendingUpFlip !== null) {
+    return;
+  }
+  entry.pendingUpFlip = setTimeout(() => {
+    entry.pendingUpFlip = null;
+    // Re-check on fire — a peer may have un-readied between schedule and now.
+    if (!computeAggregate(entry) || entry.aggregateReady) {
+      return;
+    }
+    entry.aggregateReady = true;
+    notifyListeners(entry);
+  }, READY_DEFER_MS);
+}
+
+function notifyListeners(entry: SpanRegistry): void {
   for (const listener of entry.listeners) {
     listener();
   }
@@ -92,6 +165,7 @@ function reevaluate(entry: SpanRegistry): void {
 function performCleanup(kind: DisplayKind, parentSpanId: string, entry: SpanRegistry): void {
   const liveCheckpoints = entry.checkpoints.size - entry.sticky.size;
   if (liveCheckpoints === 0 && entry.listeners.size === 0) {
+    cancelPendingUpFlip(entry);
     registries[kind].delete(parentSpanId);
   }
 }
@@ -217,10 +291,39 @@ export function subscribe(kind: DisplayKind, parentSpanId: string, listener: Lis
   };
 }
 
+/**
+ * Drop coordinator state for `parentSpanId` across both kinds.
+ *
+ * Called by the time-to-display integration once a transaction has been
+ * processed, since the per-span coordinator state is no longer relevant
+ * after the native draw timestamps have been read. Without this hook,
+ * entries for screens that stay mounted past the end of their span
+ * (React Navigation keep-alive, idle-timeout discarded transactions,
+ * etc.) would accumulate in the module-level registries.
+ *
+ * Components that are still subscribed when their span is cleared remain
+ * functional: their next interaction recreates the entry under the same
+ * (now stale) parentSpanId. Since the integration has already read the
+ * native ttid/ttfd values for that span, any subsequent fires are inert.
+ */
+export function clearSpan(parentSpanId: string): void {
+  for (const kind of [TTID, TTFD] as const) {
+    const entry = registries[kind].get(parentSpanId);
+    if (entry) {
+      cancelPendingUpFlip(entry);
+      registries[kind].delete(parentSpanId);
+    }
+  }
+}
+
 /**
  * Test-only. Clears all coordinator state.
  */
 export function _resetTimeToDisplayCoordinator(): void {
-  registries.ttid.clear();
-  registries.ttfd.clear();
+  for (const kind of [TTID, TTFD] as const) {
+    for (const entry of registries[kind].values()) {
+      cancelPendingUpFlip(entry);
+    }
+    registries[kind].clear();
+  }
 }

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

@@ -189,14 +189,26 @@ function useCoordinatedDisplay(
     return subscribe(kind, parentSpanId, force);
   }, [kind, parentSpanId, useRegistry]);
 
+  // Tracks whether this component's checkpoint is currently registered with
+  // the coordinator. Used to detect the pre-register render so we don't
+  // inherit a peer's ready=true verdict before our own checkpoint exists in
+  // the aggregate. Reset on unregister so re-mount under a new active span
+  // re-clamps correctly.
+  const registeredRef = useRef(false);
+
   // Register on mount / when the active span changes; unregister on unmount.
   // Legacy-mode components do not register — they are independent and don't
   // gate or get gated by peers.
   useEffect(() => {
     if (!parentSpanId || !useRegistry) {
       return undefined;
     }
-    return registerCheckpoint(kind, parentSpanId, checkpointId, localReady);
+    const unregister = registerCheckpoint(kind, parentSpanId, checkpointId, localReady);
+    registeredRef.current = true;
+    return () => {
+      registeredRef.current = false;
+      unregister();
+    };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [kind, parentSpanId, useRegistry, checkpointId]);
 
@@ -217,7 +229,15 @@ function useCoordinatedDisplay(
   if (!useRegistry) {
     return localReady;
   }
-  // Registry: gated on the per-span aggregate.
+  // Registry, pre-register render: our checkpoint is not yet in the
+  // registry, so `isAllReady` reflects only peer state. Combine it with our
+  // own `localReady` so we never inherit a peer's true verdict before our
+  // own checkpoint has had a chance to report.
+  if (!registeredRef.current) {
+    return localReady && isAllReady(kind, parentSpanId);
+  }
+  // Registry, post-register: gated on the per-span aggregate, which now
+  // includes our checkpoint.
   return isAllReady(kind, parentSpanId);
 }