Keep a system back that arrives while the next screen is mounting

[simonhamp]

Fixes #471

What was wrong

A #[Lazy] screen publishes its placeholder before mount() runs (NativeRouter::loop(), line 494), so native pushes the screen straight away. If the user pops it with the back chevron or an edge swipe while mount() is still busy, native sends a system back (type 8) and it waits in the event queue.

When mount() returns, the screen's first render calls flushDeferredTransition() (NativeComponent.php:2717), which calls nativephp_element_reset() (NativeRouter.php:133). The reset empties the whole event queue (event_queue_clear_locked() in the runtime's nphp_element.c), so the back is thrown away. The runtime even logs it: Element reset discarded 1 undelivered event(s).

PHP then publishes the screen the user already left. The coordinator sees a URI that isn't on its path and pushes it again (NavigationCoordinator.swift:126). PHP now sits on the chat while the user has tried to leave it, and nothing ever corrects that, because the back PHP needed is gone. On the simulator the chat just slides back in. The device report (list under the chat's nav bar, dead taps) is most likely the same thing with the re-push landing mid-animation. I couldn't get that exact picture on the simulator.

What changed

• flushDeferredTransition() now drains the queue just before the reset and keeps events that aren't bound to the outgoing screen: system back, native events, hot reload and shutdown. Taps and other callback events are still dropped, as before, so a tap meant for the old screen can't hit a callback on the new one.
• The runloop takes held events before it waits for new ones.
• When a system back is held, the screen doesn't publish its first frame, and publishFinalState() skips the farewell frame. Either one would push the screen back on.

Android uses the same router, and its BackHandler pops the path before PHP answers, same as iOS. So Android had the same lost back and gets the same fix. I checked that by reading the code, not on a device. The Android symptom would be the chat coming back rather than a stuck screen.

Other open PRs

I applied each one to main and ran the same repro against it. None of them fix this.

• fix: skip the farewell frame when back() answers a system back #370 skips the farewell frame on a system back. Here the back never reaches PHP, so there's nothing for it to act on. 10 of 10 backs were still lost. It fits with this PR: a held back goes through the normal type-8 branch, so with fix: skip the farewell frame when back() answers a system back #370 merged it also goes through handleSystemBack(). fix: skip the farewell frame when back() answers a system back #370 already conflicts with main. Once that's resolved, this PR merges on top cleanly and the full suite passes.
• Reconcile native navigation by router stack depth; direction-aware Android stack transitions #439 reconciles by stack depth. It still pushes when PHP publishes a deeper level, so the lost back still re-pushes the chat. 7 of 10 lost (the other 3 backs landed after mount had finished). No conflicts.
• iOS: settle window between navigation transitions #449 only holds non-navigation publishes after a screen swap that isn't inside native chrome. Pushes inside a native stack don't open its window. 10 of 10 lost. No conflicts.
• Keep screens responsive while their requests are in flight: background work pumped by the runloop, rendered only when a request settles #455 helps when an app uses it. A chat that loads through background() returns from mount() straight away, and 0 of 10 backs were lost. A blocking mount() still lost 10 of 10. It already conflicts with main. Once that's resolved, this PR merges on top cleanly.

What to watch

• Native events that arrive during mount() are now delivered instead of dropped. That covers deep links, async task completions and #[On] events. I think that's what everyone expected already, but it is a behaviour change.
• The drain calls nativephp_element_wait_event(0) until it returns null. On device and under Jump that returns straight away when the queue is empty.
• There is still a window of a few milliseconds between the drain and the publish. A back that lands in it is still delivered, but the chat may flash back once before PHP handles it.

Testing

Test app: a list and a chat in one native stack, with the chat's mount() blocking for 1.2s. There are three variants: blocking, 0.3s, and #[Lazy] with 1.2s. iPhone 17 Pro simulator, iOS 26.2.

• On main, a back during a lazy chat's mount was lost 10 of 10 times. After each one the chat came back on its own a moment later, and the runtime logged the discarded event. Five-trip bursts that ended on a back left the chat on screen in 5 of 6 runs.
• With this branch, 0 of 10 were lost. Twelve-trip bursts with the chevron, the edge swipe and a mix of both, with gaps of 0ms, 150ms and 400ms, always ended on the list, and the list's tap counter went up after every run. Ten-trip bursts on the blocking and 0.3s chats behaved the same.
• Normal navigation still works: push and pop by chevron and swipe, a three-deep stack and back out, pull-to-refresh on the chat, switching between two tabs and leaving them.
• Pest: 1135 passed (4 new), 4 risky, 3 skipped, same as main apart from the new tests. Pint is clean. PHPStan reports the same 3 errors as main, all in RunsAndroid.php.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 28cf13c2-7b9d-4630-9abb-9f783b9651bf

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[simonhamp]

Closing as this is solving for problems with #[Lazy] that go away if we just encourage the use of AsyncTasks instead