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.

Development warning for a view that reports its insets in a loop

The system UI does not move many times a second, so a sustained stream of inset events means the layout is feeding the insets back into the position of the observed view: it is offset by the insets it reports, which moves it out from under the system UI, which changes its insets. Every one of those events renders synchronously, so the loop is paid for in frames.

View wraps the handler in development builds and warns once per view above ten events in a second. The check lives in the handler View passes down rather than in either platform's observer, so one implementation covers iOS and Android and the warning surfaces in LogBox with a JavaScript stack instead of in logcat. That placement has one gap worth naming: the prop is on BaseViewProps, so Text, Image and ScrollView accept it too and are not checked. View is where it is used in practice.

The production branch is the identity function, so the module stays out of the bundle. The native prop is unaffected either way — function props are normalized to true before props are diffed (ReactNativeAttributePayload.js), so a fresh wrapper per render does not produce an update. Counts are kept per view in a WeakMap keyed by the event target, so views that do not loop pay nothing.

Also folded in from review: the prop is forwarded through BaseViewManagerDelegate for components with generated delegates (Switch, DrawerLayout, …), and topSafeAreaInsetsChange is exported from BaseViewManager's native view config so the event maps to the handler when native view configs are in use.

Changelog:

[GENERAL] [ADDED] - Add an experimental_onSafeAreaInsetsChange view prop, reporting the part of a view that is covered by the system UI, with a development warning for views that report their insets in a loop

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          # 4 passed
yarn fantom packages/react-native/Libraries/Components/View/__tests__/ViewSafeAreaInsetsWarning-itest.js   # 4 passed

The warning tests cover silence at a plausible rate (20 changes 200 ms apart), one warning per view under a loop, per-view counting, and that the handler still receives its event — all with a mocked clock. RNTester grows the mistake it warns about (a view positioned by the insets it reports) behind a button.

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. Each PR is one commit on top of the previous one.

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

1. #58530 — 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. #58112 — Render the internal SafeAreaView from the safe area insets prop
5. #58113 — Remove the native SafeAreaView and the deprecated public export