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

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?

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.

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

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

ios/gamma/stack/host/RNSStackOperation.mm

+
+@implementation RNSPopOperation
+
+- (instancetype)initWithScreen:(nonnull RNSStackScreenComponentView *)stackScreen


The implementation is duplicated with RNSPushOperation, I'd consider creating a base class and moving the logic there

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.

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

ios/gamma/stack/screen/RNSStackScreenComponentView.mm

  _reactEventEmitter = [RNSStackScreenComponentEventEmitter new];

  _hasUpdatedActivityMode = NO;
+  self.isNativelyDismissed = NO;


Suggested change

self.isNativelyDismissed = NO;

_isNativelyDismissed = NO;

nit: I think that in the implementation we're usually using backing variable directly.

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.

kligarski · 2026-04-01T14:36:49Z

ios/gamma/stack/screen/RNSStackScreenController.h

+NS_ASSUME_NONNULL_BEGIN
+
+@class RNSStackScreenComponentView;
+@class RNSStackController;


Suggested change

@class RNSStackController;

kligarski · 2026-04-01T14:38:30Z

ios/gamma/stack/screen/RNSStackScreenController.mm

+- (instancetype)initWithCoder:(NSCoder *)aDecoder
+{
+  return nil;
+}


Not sure if we really need this.

kligarski · 2026-04-01T14:49:25Z

ios/gamma/stack/host/RNSStackHostComponentView.mm

-  RCTAssert(_controller != nil, @"[RNScreens] Controller must not be nil while attaching to window");
-
-  [self reactAddControllerToClosestParent:_controller];
+  RNSLog(@"[RNScreens] StackHost [%pv] attached to window", self);


[RNScreens] StackHost [0x1033e7b80v] attached to window

I don't think that this is what we want, especially the random v at the end of the address. Let's use %@. Applies also to RNSStackNavigationController.mm (dumpStackModel).

kligarski · 2026-04-01T14:53:48Z

ios/gamma/stack/host/RNSStackHostComponentView.mm

+        @"[RNScreens] ignoring pop operation of %s, already not attached or natively dismissed",
+        [stackScreen.screenKey cStringUsingEncoding:NSUTF8StringEncoding]);


Suggested change

@"[RNScreens] ignoring pop operation of %s, already not attached or natively dismissed",

[stackScreen.screenKey cStringUsingEncoding:NSUTF8StringEncoding]);

@"[RNScreens] ignoring pop operation of %@, already not attached or natively dismissed",

stackScreen.screenKey);

Applies to other places as well.

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 added 17 commits April 8, 2026 11:32

Create a separate folder for new implementation

9cc66e4

Add RNSStackOperation

18f4f6e

Simplify StackHost & add operation coordinator

358089c

Use operation coordinator in host

cfe9831

Execute stack operations on navigation controller

fd4a750

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

0a95ece

move stack-queue to stack

c087dd7

Make queue operations work

1cc9dba

refactor

863f126

add logs & refactor

ab5861b

Move isNativelyDismissed, refactor log

6c58f04

Revert App.tsx

3bf8c72

Add asserts for correct screen type

a11b361

Move RNSStackOperation implementation to correct dir

9fb4c7a

Fix Copilot catches

7b0c9ab

simplify sorting

2e04cc5

fix nonull, noop and RNSLog

425972c

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

Change logged tags, remove unnecessary code

d8a04d2

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

		- (nonnull NSMutableArray<RNSStackScreenComponentView > )reactSubviews;


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

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


		@implementation RNSPopOperation

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

		@"[RNScreens] ignoring pop operation of %s, already not attached or natively dismissed",
		[stackScreen.screenKey cStringUsingEncoding:NSUTF8StringEncoding]);


		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!

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!

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

kmichalikk commented Mar 18, 2026 •

edited

Loading