Add an experimental_onSafeAreaInsetsChange view prop

[janicduplessis]

Summary:

Reports the part of a view that is covered by the system UI, as a view prop:

<View
  experimental_onSafeAreaInsetsChange={({nativeEvent: {insets, frame}}) => {
    // insets: {top, right, bottom, left}, frame: {x, y, width, height}
  }}
/>

SafeAreaView is deprecated in favour of react-native-safe-area-context (react-native-community/discussions-and-proposals#827), but core surfaces like LogBox and the element inspector cannot depend on the library, so core keeps a private copy of the deprecated component alive. The smallest primitive that would let both sides go away is native code reporting inset values to JavaScript — today the library's own RNCSafeAreaProvider component. This adds that primitive as a view prop instead, with the payload the library already uses, so SafeAreaProvider can swap its native component for a plain View with no API change on its side.

Insets are relative to the view: one laid out inside the safe area reports zeros. That is what makes the prop composable and stops nested providers from double-padding.

Cost when unused. The prop is a bool in BaseViewProps, like onLayout; native only observes the safe area when it is set. On iOS the flag is read from props the view already holds and the last-sent insets live behind a single pointer ivar that stays nil unless the view observes, so the only unconditional cost is a branch in layoutSubviews, didMoveToWindow and safeAreaInsetsDidChange — worth a look from someone who profiles that path.

Cost when used. Events fire only when the insets change; the frame is in the payload but not in the trigger. A view moving inside a scroll view therefore emits nothing, and scroll frame times with 50 observing rows match 0 observers (the "Scroll benchmark" section of the new example, with event counters on both platforms). An earlier frame-triggered iteration sustained ~5,000 events/s on an idle screen — each synchronous render produces a new frame, which re-runs the pre-draw listener — and the inset-only trigger makes that loop structurally impossible. The consequence is that frame is "as of the last inset change": a consumer wanting continuously fresh frames doesn't get them.

One full synchronous inset event (dispatch → JS render → commit → mount, timed in native, 6 runs) is 2.1–3.1 ms on iOS and 2.9–3.3 ms on Android in debug builds re-rendering a small component, paid per inset change rather than per frame.

Open questions I'd like input on: whether frame belongs in the payload at all (the library needs it for SafeAreaFrameContext, but it is derivable with measureInWindow), and whether blocking the UI thread on every inset change is acceptable or should be opt-in per view.

Stacked on #58108, which makes the synchronous dispatch land in the same frame on iOS. Without it this still works, the event just arrives a frame late there. This PR's diff includes that one until it merges — review the top commit.

Changelog:

[GENERAL] [ADDED] - Add an experimental_onSafeAreaInsetsChange view prop, reporting the part of a view that is covered by the system UI

Test Plan:

RNTester, new "Safe area insets" example, on an iPhone 17 Pro simulator and an Android 16 emulator. Screenshots of the readout, of a full screen view padding itself by its own insets in portrait and landscape on both platforms, and the synchronous-dispatch frame captures are all in #57967, the prototype this stack splits.

yarn fantom packages/react-native/Libraries/Components/View/__tests__/ViewSafeAreaInsets-itest.js   # 5 passed

Edge cases exercised, each with a test or a device check:

• View flattening — the prop marks the view as forming a stacking context so the host view the observer needs cannot be optimized away (Fantom test).
• View recycling — observation state is re-derived from the new props on both platforms rather than diffed against a recycled view's stale ones.
• Clipped Android views — rows scrolled out of a ScrollView emit nothing instead of garbage overlap values.
• Multi-scene iPad — two windows, two React instances, one shared key window: correct per-window insets across tiling, fullscreen, rotation and keyboard.

Known gaps, noted but not addressed here: FabricUIManager's per-frame synchronous-event dedupe can drop a second inset change for the same view within one frame (in practice insets don't change twice per frame); getGlobalVisibleRect mixes coordinate spaces for partially clipped views, inherited from the library's implementation; and Android rotation was not exercised because the RNTester activity kept its orientation on my emulator, though the same pre-draw listener drives it.

Also ran yarn flow-check, yarn build-types and the C++ API snapshot regeneration on this branch.

---

Stack — split out of #57967, which stays open as the prototype and design discussion. GitHub will not take a fork branch as a pull request base, so each of these targets main and its diff contains the ones below it until they merge.

This PR's own change, without the ones below it: 30 files.

1. #58108 — Process synchronous event beats in the frame that requested them

👉 2. #58109 — Add an experimental_onSafeAreaInsetsChange view prop
3. #58110 — Report the window safe area insets through Dimensions
4. #58111 — Warn in development when a view reports its safe area insets in a loop
5. #58112 — Render the internal SafeAreaView from the safe area insets prop
6. #58113 — Remove the native SafeAreaView and the deprecated public export