Alternative: schedule the display-phase event beat induce on the requesting surface

[janicduplessis]

Summary:

Alternative to #58108's display-phase scheduling, opened for comparison — one of the two should land, not both. The stack in #58108–#58113 works as-is on top of either.

Both PRs solve the same problem: a synchronous event beat requested while Core Animation is already laying out (an event emitted from layoutSubviews) is only processed on the next frame by the run loop observer. #58108 schedules an induce in the display phase of the current commit cycle by keeping a zero-sized flusher layer in every visible window of every foreground scene, since only a layer inside a committing tree is guaranteed a display phase, and the beat does not know which tree that is.

This PR gives it that knowledge instead. experimental_flushSync now carries the surface of the requesting emitter — every emitter is given its ShadowNodeFamily at creation, and the family knows its surface — through EventDispatcher and EventQueue to EventBeat::requestSynchronous(std::optional<SurfaceId>). AppleEventBeat resolves the surface to its root view's layer through a resolver injected by RCTSurfacePresenter from the surface registry, and attaches the single flusher layer there. A request made from layout runs inside the commit of exactly that tree, so the layer is guaranteed a display phase in the same cycle.

What this buys over #58108:

• No layers inserted into windows React Native does not own (keyboard and system windows of foreground scenes).
• No reliance on Core Animation committing all windows in one transaction — the multi-scene iPad caveat documented in Add an onSafeAreaInsetsChange view prop #57967 is structurally gone.
• One dirty layer per requesting surface per frame instead of one per visible window.
• VirtualView's synchronous flushes get the same targeting through their own emitter, with no change at the call site.

The cost is API: the experimental_flushSync chain changes signature across four core types (all experimental_, Android ignores the parameter), where #58108 is self-contained in AppleEventBeat. An absent surface — an emitter whose family is gone, or a future caller without one — falls back to the run loop observer's ordinary schedule.

Known rough edges, flagged for review: requestSynchronous's defaulted std::optional argument on a virtual should likely become an overload, and the C++ API snapshots are not regenerated for the new signatures yet.

Changelog:

[INTERNAL] - Schedule the synchronous event beat induce on the requesting surface's root view

Test Plan:

Same marker methodology as #58108 (any presented frame of the yellow observing-without-insets marker means the dispatch was not synchronous), re-run on this implementation with RNTester on an iPhone 17 Pro simulator: the full apply → landscape → portrait capture below was decomposed with ffmpeg into 950 frames and every frame scanned for the marker color — zero marker frames. Mid-rotation frames already show the incoming orientation's insets (top: 62, bottom: 34 while the rotation animation is still in flight), so the padding animates with the transition.

ViewSafeAreaInsets-itest passes 4/4 with the prop stack merged on top; EventBeatTest covers the unchanged beat semantics through the base-class default.

proto-capture.mp4

[janicduplessis]

Closing in favor of #58108 — the exploration answered the question, against this approach.

The disqualifying finding: surface identity does not identify the committing layer tree for content inside a non-transparent <Modal>. RCTModalHostViewComponentView presents UIModalPresentationFullScreen, and UIKit detaches the presenting hierarchy — which contains the surface's root view — once the presentation settles. A sync flush from modal content therefore dirties a layer in a tree Core Animation never commits, and the same-frame induce silently degrades to run-loop-observer timing. Modals are a primary case for synchronous safe-area events, and #58108's per-window layers handle them by construction. Repairing this here would mean resolving the emitting view's tree (much deeper plumbing than a surface id) or falling back to per-window scanning when the root is detached — at which point both mechanisms coexist on top of a four-type experimental_flushSync signature change, and the remaining benefit is only fewer dirty layers per frame.

Two implementation issues found in review, recorded for any future revival:

• The resolver's surfaceForRootTag:...view.layer is not read-only: RCTFabricSurface.view lazily creates an RCTSurfaceView and attaches a touch handler when the surface is registered but not started (or mid-reload), so the resolver could allocate an orphan view inside a CA layout phase. It must gate on the surface's stage or use a non-creating accessor.
• EventEmitter::getSurfaceId should not take DispatchMutex (held by the JS thread across whole-tree updateMountedFlag walks during commits — a main-thread stall hazard on the flush path, and the set-once family needs no lock). The better source is the emitter's existing EventTarget, which carries an immutable surfaceId_ behind a lock-free getter.

Scope correction on the test plan above: the capture proves no regression of the marker test, but it does not prove same-frame delivery for the modal case — the first inset event after Apply insets is processed at the call site (no flusher involved), and a one-frame lag during a rotation animation is not distinguishable in the frame scan. #58108's captures don't carry this caveat because its mechanism doesn't depend on identifying the committing tree.

The branch stays up for reference.

[janicduplessis]

Addendum — a variant that resolves the disqualifying finding, recorded here in case targeting is ever wanted: pass the emitting view's tag instead of its surface. EventTarget::getTag() gives the emitter the tag through the same immutable, lock-free path as getSurfaceId(), and on iOS RCTComponentViewRegistry.findComponentViewWithTag: is a nullable, non-creating, main-thread lookup already reachable from RCTSurfacePresenter. The resolver becomes tag → view → view.window.layer: the emitting view's window is by definition the root of the tree whose layout is running, so full-screen <Modal> content targets the modal's own window, and all three review findings above disappear by construction (no view-creating getter, no DispatchMutex, correct tree everywhere). The remaining cost is the same four-type experimental_flushSync signature change, which is why #58108's self-contained per-window approach still lands the stack; this is the shape a targeted follow-up should take.

[janicduplessis]

The view-tag variant from the addendum above is now implemented and opened as #58530, verified with the marker methodology inside the full screen modal (982 frames, zero marker frames).