feat(iOS, Stack v5): Align Stack implementation with RFC 753 by kmichalikk · Pull Request #3774 · software-mansion/react-native-screens

kmichalikk · 2026-03-18T12:10:25Z

Closes https://github.com/software-mansion/react-native-screens-labs/issues/1050
Closes https://github.com/software-mansion/react-native-screens-labs/issues/864
Closes https://github.com/software-mansion/react-native-screens-labs/issues/816

Description

This PR aligns the current Stack implementation with RFC 753 by adding an operations queue that enables us to defer the application of JS differences in a batch that moves the stack from one consistent state to another. The implementation has been adapted from Android implementation, with key difference being the absence of FragmentManager along with its FragmentOperations. These are handled within RNSStackNavigationController.

Changes

Introduced pendingPopOperations and pendingPushOperations that form a queue and need not be applied immediately.
Replaced swift controllers with objective-c to remove the need of interoperability: given the amount of props, enums, customizations that will be present in the future, I think it's better to avoid the interop entirely

Before & after - visual documentation

no visual changes

Test plan

Use Tests.Issue.TestScreenStack to test various scenarios, verify the state in the logs. Run Tests.Issue.Test3576 to check a specific scenario that caused problems on the android.

Checklist

Ensured that CI passes

Copilot

Pull request overview

This PR migrates the iOS “gamma/stack” implementation to an Objective-C(/ObjC++) navigation-controller–based stack and introduces an operation queue/coordinator to batch apply push/pop changes in a consistent way (per RFC 753).

Changes:

Replaces Swift RNSStackController / RNSStackScreenController with Objective-C equivalents.
Adds RNSStackOperationCoordinator + operation objects to queue and order push/pop updates.
Updates RNSStackHostComponentView / RNSStackScreenComponentView to use the new coordinator and track native dismissals.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
ios/gamma/stack/screen/RNSStackScreenController.swift	Removes Swift screen controller implementation.
ios/gamma/stack/screen/RNSStackScreenController.h	Adds ObjC header for the new screen controller.
ios/gamma/stack/screen/RNSStackScreenController.mm	Adds ObjC implementation for lifecycle + dismiss event emission.
ios/gamma/stack/screen/RNSStackScreenComponentView.mm	Initializes `isNativelyDismissed` and updates default props type for the stack screen component.
ios/gamma/stack/screen/RNSStackScreenComponentView.h	Adds `isNativelyDismissed` property to support native-dismiss handling.
ios/gamma/stack/host/RNSStackOperationCoordinator.h	Declares coordinator interface for pending operations.
ios/gamma/stack/host/RNSStackOperationCoordinator.mm	Implements ordering/execution of queued push/pop operations.
ios/gamma/stack/host/RNSStackOperation.h	Defines push/pop operation types and shared protocol.
ios/gamma/stack/host/RNSStackOperation.mm	Implements push/pop operation initializers.
ios/gamma/stack/host/RNSStackNavigationController.h	Declares navigation controller API for enqueuing operations and applying updates.
ios/gamma/stack/host/RNSStackNavigationController.mm	Implements queued push/pop application and stack model logging.
ios/gamma/stack/host/RNSStackHostComponentView.mm	Replaces old controller usage with navigation controller + coordinator and wires operation enqueueing to Fabric lifecycle.
ios/gamma/stack/host/RNSStackHostComponentView.h	Removes old Swift controller exposure from the host view public interface.
ios/gamma/stack/host/RNSStackController.swift	Removes Swift stack controller implementation.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

ios/gamma/stack/host/RNSStackHostComponentView.mm

ios/gamma/stack/screen/RNSStackScreenController.mm

kmichalikk · 2026-03-18T12:33:11Z

ios/gamma/stack/host/RNSStackHostComponentView.h

-@property (nonatomic, nonnull, strong, readonly) RNSStackController *stackController;
-
- (nonnull NSMutableArray<RNSStackScreenComponentView *> *)reactSubviews;
-


These weren't used outside the implementation or anywhere

kmichalikk · 2026-03-18T12:37:30Z

ios/gamma/stack/host/RNSStackHostComponentView.mm

+- (void)addPopOperationIfNeeded:(nonnull RNSStackScreenComponentView *)stackScreen
+{
+  if (stackScreen.activityMode == RNSStackScreenActivityModeAttached && !stackScreen.isNativelyDismissed) {
+    // This shouldn't happen in typical scenarios but it can happen with fast-refresh.


Comment taken from Android, should still be relevant

kmichalikk · 2026-03-18T12:39:47Z

ios/gamma/stack/host/RNSStackOperation.h

+@protocol RNSStackOperation
+
+@property (nonatomic, strong, readonly, nonnull) RNSStackScreenComponentView *stackScreen;
+
+@end
+
+@interface RNSPushOperation : NSObject <RNSStackOperation>
+
+@property (nonatomic, strong, readonly, nonnull) RNSStackScreenComponentView *stackScreen;
+
+- (instancetype)initWithScreen:(nonnull RNSStackScreenComponentView *)stackScreen;
+
+@end
+
+@interface RNSPopOperation : NSObject <RNSStackOperation>
+
+@property (nonatomic, strong, readonly, nonnull) RNSStackScreenComponentView *stackScreen;
+
+- (instancetype)initWithScreen:(nonnull RNSStackScreenComponentView *)stackScreen;
+
+@end


Let me know if there's a better way to do this comparing to sealed class implementation in kotlin

kmichalikk · 2026-03-18T12:41:18Z

ios/gamma/stack/host/RNSStackOperationCoordinator.mm

+  NSMutableArray<NSDictionary *> *operationsWithIndices = [NSMutableArray array];
+  for (id<RNSStackOperation> operation in operations) {
+    NSInteger index = [stackScreens indexOfObject:operation.stackScreen];
+    [operationsWithIndices addObject:@{@"index" : @(index), @"operation" : operation}];
+  }
+
+  [operationsWithIndices sortUsingComparator:^NSComparisonResult(NSDictionary *obj1, NSDictionary *obj2) {
+    return [obj1[@"index"] compare:obj2[@"index"]];
+  }];
+
+  NSMutableArray<id<RNSStackOperation>> *orderedOperations = [NSMutableArray new];
+  for (NSDictionary *dict in operationsWithIndices) {
+    [orderedOperations addObject:dict[@"operation"]];
+  }
+
+  return orderedOperations;


In comparison to kotlin stream, this is 10x worse. Is there a better way to sort by indices from other array?

maybe you could try: https://developer.apple.com/documentation/foundation/nsarray/sortedarray(comparator:)?language=objc to avoid intermediate allocations in operationsWithIndices and compare indices inside comparator?

kmichalikk · 2026-03-18T12:41:58Z

ios/gamma/stack/screen/RNSStackScreenComponentView.mm

  _reactEventEmitter = [RNSStackScreenComponentEventEmitter new];

  _hasUpdatedActivityMode = NO;
+  self.isNativelyDismissed = NO;


Should this be reset somewhere? This is set to YES when native dismiss is triggered

I think that we currently assume that screens won't be re-used so I don't think that we need to reset it for now.

ios/gamma/stack/screen/RNSStackScreenController.mm

ios/gamma/stack/host/RNSStackHostComponentView.mm

ios/gamma/stack/screen/RNSStackScreenComponentView.mm

kmichalikk · 2026-03-19T16:32:41Z

There is another thing. For now, I didn't set up cancelTouches so if you try to pop a screen while touching pop action, it will result in app crashing.

t0maboro · 2026-03-23T15:24:09Z

ios/gamma/stack/host/RNSStackHostComponentView.mm

 - (void)stackScreenChangedActivityMode:(nonnull RNSStackScreenComponentView *)stackScreen
 {
-  [_controller setNeedsUpdateOfChildViewControllers];
+  switch (stackScreen.activityMode) {


should we add error handling?

What do you mean?

I've added an assertion to this method, to check that the argument is indeed nonnull as declared.

t0maboro · 2026-03-23T15:26:18Z

ios/gamma/stack/host/RNSStackHostComponentView.mm

 - (void)mountingTransactionWillMount:(const facebook::react::MountingTransaction &)transaction
                withSurfaceTelemetry:(const facebook::react::SurfaceTelemetry &)surfaceTelemetry
 {
-  _hasModifiedReactSubviewsInCurrentTransaction = false;
-  [_controller reactMountingTransactionWillMount];
+  // noop
 }


can we remove this method?

t0maboro · 2026-03-23T15:37:53Z

ios/gamma/stack/host/RNSStackOperation.h

+
+NS_ASSUME_NONNULL_BEGIN
+
+@protocol RNSStackOperation


you might consider a class here, which will allow to move up both stackScreen and initWithScreen to the base

I mean, they're both equally meh. I need some base for both i.e. in common sort function. If I had base class here, I would have two derived classes that don't change anything. It's few lines either way. I think we could leave it be.

I did that refactor. We could even consider removing RNSPushOperation and RNSPopOperation entirely. In lieu of them, we could simply add a type member to the RNSStackOperation. Might be even simpler.

t0maboro · 2026-03-23T15:38:14Z

ios/gamma/stack/host/RNSStackOperation.h

+
+@property (nonatomic, strong, readonly, nonnull) RNSStackScreenComponentView *stackScreen;
+
+- (instancetype)initWithScreen:(nonnull RNSStackScreenComponentView *)stackScreen;


nonnull seems to be redundant, as we have NS_ASSUME_NONNULL_BEGIN

ios/gamma/stack/host/RNSStackOperation.mm

t0maboro · 2026-03-23T15:50:55Z

ios/gamma/stack/host/RNSStackOperationCoordinator.mm

+  NSMutableArray<NSDictionary *> *operationsWithIndices = [NSMutableArray array];
+  for (id<RNSStackOperation> operation in operations) {
+    NSInteger index = [stackScreens indexOfObject:operation.stackScreen];
+    [operationsWithIndices addObject:@{@"index" : @(index), @"operation" : operation}];
+  }
+
+  [operationsWithIndices sortUsingComparator:^NSComparisonResult(NSDictionary *obj1, NSDictionary *obj2) {
+    return [obj1[@"index"] compare:obj2[@"index"]];
+  }];
+
+  NSMutableArray<id<RNSStackOperation>> *orderedOperations = [NSMutableArray new];
+  for (NSDictionary *dict in operationsWithIndices) {
+    [orderedOperations addObject:dict[@"operation"]];
+  }
+
+  return orderedOperations;


maybe you could try: https://developer.apple.com/documentation/foundation/nsarray/sortedarray(comparator:)?language=objc to avoid intermediate allocations in operationsWithIndices and compare indices inside comparator?

t0maboro · 2026-03-23T15:54:04Z

ios/gamma/stack/screen/RNSStackScreenController.mm

+
+- (void)didMoveToParentViewController:(UIViewController *)parent
+{
+  NSLog(@"[RNScreens] Screen view with tag=%ld didMoveToParentViewController %@", (long)_screenView.tag, parent);


nit: RNSLog

kligarski

Looks good, I left some minor suggestions.

ios/gamma/stack/screen/RNSStackScreenComponentView.mm

kligarski · 2026-04-01T14:34:58Z

ios/gamma/stack/screen/RNSStackScreenComponentView.mm

  _reactEventEmitter = [RNSStackScreenComponentEventEmitter new];

  _hasUpdatedActivityMode = NO;
+  self.isNativelyDismissed = NO;


I think that we currently assume that screens won't be re-used so I don't think that we need to reset it for now.

ios/gamma/stack/screen/RNSStackScreenController.h

ios/gamma/stack/screen/RNSStackScreenController.mm

ios/gamma/stack/host/RNSStackHostComponentView.mm

kkafar · 2026-04-14T10:20:31Z

During testing I've found a bug.

bug-1-quick-push-pop-seq.mov

My initial read is that it is related to how our StackContainer is currently implemented. I'll debug it and push out the changes here.

kkafar · 2026-04-14T10:49:08Z

Yeah, I've managed to fix this issue with a simple patch to StackContainer implementation.

I now simply prevent JS-push operation of a screen that is during a dismissal. See the video below

bug-1-quick-push-pop-seq-fixed.mov

Guards against unhandled activityMode values reaching the switch in didRemoveChild. Fails loudly in debug instead of falling through.

kkafar · 2026-04-14T13:37:06Z

I've found another problem, see the video:

bug-2-crash-when-popping-not-top-screen.mov

What happens here is on some point when pushing consecutive B screens, we push twice from a single one. E.g. from B-14, we push both B-15 and B-16. They're animated in sequentially => on the B-16 we can click pop (it'll try to pop B-15), when B-16 is already mounted on top of it, leading to crash.

I'm not sure yet how we might solve it.

One approach would be to reject (ignore) such operation and emit appropriate event.

kkafar · 2026-04-14T14:00:25Z

I've decided for now, to ignore such pop requests on StackContainer layer. Not in native implementation.

kkafar · 2026-04-14T14:42:14Z

There is yet another bug. See the video.

bug-3-crash-of-pop-conflict.mov

What happens here likely:

We pop a screen with gesture natively.
Before that information reaches JS, JS pops the same screen.
We get a crash attempting to dismiss already dismissed screen (topViewController != toBePoppedController).

I've managed to also reproduce it once on Android (but with much worse reproducibility rate).

Consolidate duplicated initializer logic from RNSPushOperation and RNSPopOperation into a shared RNSStackOperation base class. Adds a nonnull assertion on screen parameter. Also applies early return guard in navigation controller and fixes true -> YES for ObjC style.

Guard against popping a route when a higher-indexed attached route exists on the stack. Also replace magic -1 with NOT_FOUND_INDEX.

kkafar · 2026-04-14T15:28:33Z

I've created ticket for that last issue. It requires some additional handling.

Currently in stack v4, thanks to @t0maboro we handle similar interaction via early return. This is a heuristic, that works, unless somebody really intents to push / pop screen in quick succession. We should handle such cases robustly, maybe in similar manner that we've recently implemented for tabs.

kkafar

I've got some remarks regarding ownership model - but it is not a blocking problem. For context see the ticket: https://github.com/software-mansion/react-native-screens-labs/issues/1142.

I've pushed all desired changes, including patches for discovered problems.

Let's proceed here.

ios/gamma/stack/host/RNSStackHostComponentView.mm

kkafar · 2026-04-14T11:03:24Z

ios/gamma/stack/host/RNSStackHostComponentView.mm

 - (void)stackScreenChangedActivityMode:(nonnull RNSStackScreenComponentView *)stackScreen
 {
-  [_controller setNeedsUpdateOfChildViewControllers];
+  switch (stackScreen.activityMode) {


I've added an assertion to this method, to check that the argument is indeed nonnull as declared.

kkafar · 2026-04-14T15:42:41Z

ios/gamma/stack/host/RNSStackOperation.h

+
+NS_ASSUME_NONNULL_BEGIN
+
+@protocol RNSStackOperation


I did that refactor. We could even consider removing RNSPushOperation and RNSPopOperation entirely. In lieu of them, we could simply add a type member to the RNSStackOperation. Might be even simpler.

kkafar · 2026-04-14T15:44:31Z

ios/gamma/stack/host/RNSStackOperationCoordinator.mm

+  return [operations sortedArrayUsingComparator:^NSComparisonResult(RNSStackOperation *obj1, RNSStackOperation *obj2) {
+    return [@([stackScreens indexOfObject:obj1.stackScreen]) compare:@([stackScreens indexOfObject:obj2.stackScreen])];
+  }];


The complexity here is $O(n^2 \log n)$ I believe, however, we'll have like 10 items here at most. I won't refactor it right now.

kmichalikk marked this pull request as draft March 18, 2026 12:35

kmichalikk marked this pull request as ready for review March 18, 2026 12:55

kmichalikk requested a review from Copilot March 18, 2026 12:55

Copilot started reviewing on behalf of kmichalikk March 18, 2026 12:55 View session

kmichalikk requested review from kkafar, kligarski, sgaczol and t0maboro March 18, 2026 12:55

Copilot AI reviewed Mar 18, 2026

View reviewed changes

ios/gamma/stack/host/RNSStackHostComponentView.mm Outdated Show resolved Hide resolved

ios/gamma/stack/screen/RNSStackScreenController.mm Show resolved Hide resolved

kmichalikk commented Mar 18, 2026

View reviewed changes

t0maboro reviewed Mar 23, 2026

View reviewed changes

kligarski reviewed Apr 1, 2026

View reviewed changes

kmichalikk force-pushed the @kmichalikk/stack-v5-with-queue-ios branch from 34cb54d to 425972c Compare April 8, 2026 11:03

kmichalikk added 16 commits April 13, 2026 17:19

Create a separate folder for new implementation

bc2274d

Add RNSStackOperation

aa39e1f

Simplify StackHost & add operation coordinator

bf9b68f

Use operation coordinator in host

a765d55

Execute stack operations on navigation controller

8be5479

Rewrite screen controller to obj-c and integrate with new implementation

8ba3ed3

move stack-queue to stack

341be5f

Make queue operations work

37fe3c1

refactor

5997ca6

add logs & refactor

33951f7

Move isNativelyDismissed, refactor log

d8f1fb1

Revert App.tsx

83d0702

Add asserts for correct screen type

81446b4

Move RNSStackOperation implementation to correct dir

4f3ea97

Fix Copilot catches

e69ed78

simplify sorting

7f15694

kmichalikk added 2 commits April 13, 2026 17:19

fix nonull, noop and RNSLog

1e8d43e

Change logged tags, remove unnecessary code

2571b25

kmichalikk force-pushed the @kmichalikk/stack-v5-with-queue-ios branch from d8a04d2 to 2571b25 Compare April 13, 2026 15:34

kkafar added 5 commits April 14, 2026 12:58

Add assertion in reactAddControllerToClosestParent

83d747c

Fix for the issue with pushing screens that are mid-dismissal

afdfc5d

Add nonnill assertion

1b0a8db

fix(ios): add assertion for unexpected activityMode in stack host

86346d0

Guards against unhandled activityMode values reaching the switch in didRemoveChild. Fails loudly in debug instead of falling through.

refactor(ios): reorganize stack host methods into pragma sections

69e32cf

kkafar added 2 commits April 14, 2026 16:57

fix: prevent pop action on non-top attached screen

26d29e6

Guard against popping a route when a higher-indexed attached route exists on the stack. Also replace magic -1 with NOT_FOUND_INDEX.

Add simple navigation scenario to test the changes

ce86bd2

kkafar approved these changes Apr 14, 2026

View reviewed changes

refactor(ios): move isNativelyDismissed to public interface

433bab4

kkafar merged commit 33feebb into main Apr 14, 2026
6 checks passed

kkafar deleted the @kmichalikk/stack-v5-with-queue-ios branch April 14, 2026 16:05

		@property (nonatomic, nonnull, strong, readonly) RNSStackController *stackController;

		- (nonnull NSMutableArray<RNSStackScreenComponentView > )reactSubviews;


		@property (nonatomic, strong, readonly, nonnull) RNSStackScreenComponentView *stackScreen;

		- (instancetype)initWithScreen:(nonnull RNSStackScreenComponentView *)stackScreen;


		NS_ASSUME_NONNULL_BEGIN

		@protocol RNSStackOperation


		NS_ASSUME_NONNULL_BEGIN

		@protocol RNSStackOperation

Uh oh!

Conversation

kmichalikk commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Before & after - visual documentation

Test plan

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kmichalikk commented Mar 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kligarski left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kkafar commented Apr 14, 2026

Uh oh!

kkafar commented Apr 14, 2026

Uh oh!

kkafar commented Apr 14, 2026

kmichalikk commented Mar 18, 2026 •

edited

Loading

kkafar commented Apr 14, 2026 •

edited

Loading

kkafar commented Apr 14, 2026 •

edited

Loading