feat(iOS, Stack, Tabs): introduce Container & ContainerItem nesting

Port the container-nesting protocol from Android to iOS so nesting
information propagates between containers, and use it to resolve the
content scroll view for special effects (scroll-to-top) across a nesting
boundary.

`RNSStackHostComponentView` and `RNSTabsHostComponentView` adopt the new
`RNSContainer` protocol and register with the nearest parent
`RNSContainerItem` on attach/detach to the window. `RNSStackScreenComponentView`
and `RNSTabsScreenComponentView` adopt `RNSContainerItem`; content-scroll-view
resolution now follows cached -> nested container -> descendant-chain
heuristic.

Shared state/logic lives in two composition holders mirroring the Android
side: `RNSContainerItemSupport` (item side) and
`RNSParentContainerItemRegistry` (container side). The parent walk prefers
the React superview chain, matching the scroll-view marker ancestor lookup.
`RNSTabsScreenViewController.resolveContentScrollView` now delegates to the
screen's `findContentScrollView`, removing the duplicated edge/heuristic
lookup.

Author: kkafar

ios/gamma/stack/host/RNSStackHostComponentView.mm

@@ -7,8 +7,10 @@
 #import <react/renderer/components/rnscreens/EventEmitters.h>
 #import <react/renderer/components/rnscreens/Props.h>
 #import <react/renderer/components/rnscreens/RCTComponentViewHelpers.h>
+#import "RNSContainer.h"
 #import "RNSDefines.h"
 #import "RNSLog.h"
+#import "RNSParentContainerItemRegistry.h"
 
 #import "RNSStackNavigationController.h"
 #import "RNSStackOperationCoordinator.h"
@@ -17,13 +19,14 @@
 
 namespace react = facebook::react;
 
-@interface RNSStackHostComponentView () <RCTMountingTransactionObserving>
+@interface RNSStackHostComponentView () <RCTMountingTransactionObserving, RNSContainer>
 @end
 
 @implementation RNSStackHostComponentView {
   RNSStackNavigationController *_Nonnull _stackNavigationController;
   RNSStackOperationCoordinator *_Nonnull _stackOperationCoordinator;
   NSMutableArray<RNSStackScreenComponentView *> *_Nonnull _renderedScreens;
+  RNSParentContainerItemRegistry *_Nonnull _parentContainerRegistry;
 }
 
 - (instancetype)initWithFrame:(CGRect)frame
@@ -39,6 +42,7 @@ - (void)initState
   _stackNavigationController = [RNSStackNavigationController new];
   _stackOperationCoordinator = [RNSStackOperationCoordinator new];
   _renderedScreens = [NSMutableArray new];
+  _parentContainerRegistry = [RNSParentContainerItemRegistry new];
 }
 
 #pragma mark - UIKit Callbacks
@@ -48,6 +52,23 @@ - (void)didMoveToWindow
   RNSLog(@"[RNScreens] StackHost [%ld] attached to window", self.tag);
   [self reactAddControllerToClosestParent:_stackNavigationController];
   [self setupViewConstraintsForController:_stackNavigationController];
+
+  if (self.window != nil) {
+    [_parentContainerRegistry attachContainer:self];
+  } else {
+    [_parentContainerRegistry detachContainer:self];
+  }
+}
+
+#pragma mark - RNSContainer
+
+- (nullable UIScrollView *)resolveCurrentContentScrollView
+{
+  UIView *topScreenView = _stackNavigationController.topViewController.view;
+  if (![topScreenView isKindOfClass:RNSStackScreenComponentView.class]) {
+    return nil;
+  }
+  return [static_cast<RNSStackScreenComponentView *>(topScreenView) findContentScrollView];
 }
 
 #pragma mark - Communication with StackScreen

ios/gamma/stack/screen/RNSStackScreenComponentView.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#import "RNSContainerItem.h"
 #import "RNSReactBaseView.h"
 #import "RNSStackHeaderData.h"
 #import "RNSStackScreenComponentEventEmitter.h"
@@ -15,7 +16,7 @@ typedef NS_ENUM(int, RNSStackScreenActivityMode) {
   RNSStackScreenActivityModeAttached = 1,
 };
 
-@interface RNSStackScreenComponentView : RNSReactBaseView
+@interface RNSStackScreenComponentView : RNSReactBaseView <RNSContainerItem>
 
 @property (nonatomic, weak, readwrite, nullable) RNSStackHostComponentView *stackHost;
 @property (nonatomic, strong, readonly, nonnull) RNSStackScreenController *controller;

ios/gamma/stack/screen/RNSStackScreenComponentView.mm

@@ -7,7 +7,9 @@
 #import <react/renderer/components/rnscreens/RCTComponentViewHelpers.h>
 #import <rnscreens/RNSStackScreenComponentDescriptor.h>
 
+#import "RNSContainerItemSupport.h"
 #import "RNSConversions-Stack.h"
+#import "RNSScrollViewSeeking.h"
 #import "RNSStackHeaderConfigComponentView.h"
 #import "RNSStackHostComponentView.h"
 #import "RNSStackNavigationController.h"
@@ -18,14 +20,15 @@
 
 namespace react = facebook::react;
 
-@interface RNSStackScreenComponentView () <RCTMountingTransactionObserving>
+@interface RNSStackScreenComponentView () <RCTMountingTransactionObserving, RNSScrollViewSeeking>
 @end
 
 #pragma mark - View implementation
 
 @implementation RNSStackScreenComponentView {
   RNSStackScreenController *_Nonnull _controller;
   RNSStackScreenComponentEventEmitter *_Nonnull _reactEventEmitter;
+  RNSContainerItemSupport *_Nonnull _containerItemSupport;
 
   // Flags
   BOOL _hasUpdatedActivityMode;
@@ -46,6 +49,7 @@ - (void)initState
   [self setupController];
 
   _reactEventEmitter = [RNSStackScreenComponentEventEmitter new];
+  _containerItemSupport = [RNSContainerItemSupport new];
 
   _hasUpdatedActivityMode = NO;
   _isNativelyDismissed = NO;
@@ -87,6 +91,35 @@ - (nonnull RNSStackScreenComponentEventEmitter *)reactEventEmitter
   return _reactEventEmitter;
 }
 
+#pragma mark - RNSScrollViewSeeking
+
+- (void)registerDescendantScrollView:(UIScrollView *)scrollView fromMarker:(RNSScrollViewMarkerComponentView *)marker
+{
+  [_containerItemSupport registerScrollView:scrollView];
+}
+
+#pragma mark - RNSContainerItem
+
+- (void)registerNestedContainer:(id<RNSContainer>)container
+{
+  [_containerItemSupport registerNestedContainer:container];
+}
+
+- (void)unregisterNestedContainer:(id<RNSContainer>)container
+{
+  [_containerItemSupport unregisterNestedContainer:container];
+}
+
+- (nullable id<RNSContainer>)resolveNestedContainer
+{
+  return [_containerItemSupport resolveNestedContainer];
+}
+
+- (nullable UIScrollView *)findContentScrollView
+{
+  return [_containerItemSupport findContentScrollViewForOwner:self];
+}
+
 #pragma mark - RCTComponentViewProtocol
 
 - (void)updateProps:(const facebook::react::Props::Shared &)props

ios/helpers/container/RNSContainer.h

@@ -0,0 +1,14 @@
+#pragma once
+
+#import <UIKit/UIKit.h>
+
+@protocol RNSContainer <NSObject>
+
+/**
+ * A container can host multiple items, and each item can have its own content scroll view. It is
+ * down to the implementer to decide which scroll view to return here (if any) for the item that is
+ * currently presented.
+ */
+- (nullable UIScrollView *)resolveCurrentContentScrollView;
+
+@end

ios/helpers/container/RNSContainerItem.h

@@ -0,0 +1,28 @@
+#pragma once
+
+#import <UIKit/UIKit.h>
+
+#import "RNSContentScrollViewProviding.h"
+
+@protocol RNSContainer;
+
+@protocol RNSContainerItem <RNSContentScrollViewProviding>
+
+#pragma mark - Nested Container handling
+
+/**
+ * A `RNSContainerItem` supports at most a single nested `RNSContainer`. Registering a second
+ * container while one is already registered overwrites the previous one. This is an intentional
+ * design invariant: a single item is expected to host at most one nested container.
+ */
+- (void)registerNestedContainer:(nonnull id<RNSContainer>)container;
+
+- (void)unregisterNestedContainer:(nonnull id<RNSContainer>)container;
+
+- (nullable id<RNSContainer>)resolveNestedContainer;
+
+#pragma mark - Content Scroll View support
+
+// `findContentScrollView` is inherited from `RNSContentScrollViewProviding`.
+
+@end

ios/helpers/container/RNSContainerItemSupport.h

@@ -0,0 +1,36 @@
+#pragma once
+
+#import <UIKit/UIKit.h>
+
+#import "RNSContainer.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Shared state & logic backing a `RNSContainerItem`. Holds the (optional) nested `RNSContainer`
+ * and the cached content scroll view, and resolves the content scroll view on behalf of the
+ * owning item.
+ *
+ * A `RNSContainerItem` supports at most a single nested `RNSContainer`; see
+ * `RNSContainerItem.registerNestedContainer:`.
+ */
+@interface RNSContainerItemSupport : NSObject
+
+- (void)registerScrollView:(UIScrollView *)scrollView;
+
+- (void)registerNestedContainer:(id<RNSContainer>)container;
+
+- (void)unregisterNestedContainer:(id<RNSContainer>)container;
+
+- (nullable id<RNSContainer>)resolveNestedContainer;
+
+/**
+ * Resolves the content scroll view for the owning item: the cached one if present, otherwise the
+ * one provided by the nested container, otherwise a heuristic search through `owner`'s first
+ * descendant chain.
+ */
+- (nullable UIScrollView *)findContentScrollViewForOwner:(UIView *)owner;
+
+@end
+
+NS_ASSUME_NONNULL_END

ios/helpers/container/RNSContainerItemSupport.mm

@@ -0,0 +1,50 @@
+#import "RNSContainerItemSupport.h"
+
+#import "RNSScrollViewFinder.h"
+
+@implementation RNSContainerItemSupport {
+  __weak id<RNSContainer> _nestedContainer;
+  __weak UIScrollView *_contentScrollView;
+}
+
+- (void)registerScrollView:(UIScrollView *)scrollView
+{
+  _contentScrollView = scrollView;
+}
+
+- (void)registerNestedContainer:(id<RNSContainer>)container
+{
+  _nestedContainer = container;
+}
+
+- (void)unregisterNestedContainer:(id<RNSContainer>)container
+{
+  if (_nestedContainer == container) {
+    _nestedContainer = nil;
+  }
+}
+
+- (nullable id<RNSContainer>)resolveNestedContainer
+{
+  return _nestedContainer;
+}
+
+- (nullable UIScrollView *)findContentScrollViewForOwner:(UIView *)owner
+{
+  // Cached one
+  UIScrollView *cached = _contentScrollView;
+  if (cached != nil) {
+    return cached;
+  }
+
+  // Provided by nested container
+  UIScrollView *fromNestedContainer = [[self resolveNestedContainer] resolveCurrentContentScrollView];
+  if (fromNestedContainer != nil) {
+    return fromNestedContainer;
+  }
+
+  // Heuristic
+  return [RNSScrollViewFinder findScrollViewInFirstDescendantChainFrom:owner];
+}
+
+@end

ios/helpers/container/RNSParentContainerItemRegistry.h

@@ -0,0 +1,22 @@
+#pragma once
+
+#import <UIKit/UIKit.h>
+
+#import "RNSContainer.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Shared state & logic backing a `RNSContainer`'s registration with the nearest parent
+ * `RNSContainerItem` in the view hierarchy. Call `attachContainer:` when the container attaches to
+ * the window and `detachContainer:` when it detaches.
+ */
+@interface RNSParentContainerItemRegistry : NSObject
+
+- (void)attachContainer:(UIView<RNSContainer> *)container;
+
+- (void)detachContainer:(id<RNSContainer>)container;
+
+@end
+
+NS_ASSUME_NONNULL_END

ios/helpers/container/RNSParentContainerItemRegistry.mm

@@ -0,0 +1,47 @@
+#import "RNSParentContainerItemRegistry.h"
+
+#import <React/UIView+React.h>
+
+#import "RNSContainerItem.h"
+
+@implementation RNSParentContainerItemRegistry {
+  __weak id<RNSContainerItem> _parentContainerItem;
+}
+
+- (void)attachContainer:(UIView<RNSContainer> *)container
+{
+  id<RNSContainerItem> parentContainerItem = [self findParentContainerItemFrom:container];
+  if (parentContainerItem != nil) {
+    [parentContainerItem registerNestedContainer:container];
+  }
+  _parentContainerItem = parentContainerItem;
+}
+
+- (void)detachContainer:(id<RNSContainer>)container
+{
+  [_parentContainerItem unregisterNestedContainer:container];
+  _parentContainerItem = nil;
+}
+
+/**
+ * Walks up the view hierarchy starting above `view`, returning the nearest ancestor conforming to
+ * `RNSContainerItem`. Prefers the React superview chain, falling back to the UIKit one. Mirrors the
+ * ancestor walk in `RNSScrollViewMarkerComponentView.findFirstSeekingAncestor`.
+ */
+- (nullable id<RNSContainerItem>)findParentContainerItemFrom:(UIView *)view
+{
+  UIView *superview = view.superview;
+  while (superview != nil) {
+    if ([superview respondsToSelector:@selector(registerNestedContainer:)]) {
+      return static_cast<id<RNSContainerItem>>(superview);
+    }
+    if ([superview respondsToSelector:@selector(reactSuperview)]) {
+      superview = [superview reactSuperview];
+    } else {
+      superview = superview.superview;
+    }
+  }
+  return nil;
+}
+
+@end