@shortkitsdk/react-native 0.2.6 → 0.2.12

package/ios/ShortKitFeedView.swift

@@ -4,46 +4,28 @@ import ShortKitSDK
 /// Fabric native view that embeds `ShortKitFeedViewController` using
 /// UIViewController containment. Props are set by the view manager via
 /// `@objc` setters.
-///
-/// Also tracks the feed's scroll offset via KVO and applies a native
-/// transform to the sibling RN overlay view so it moves with the active
-/// cell during swipe transitions.
 @objc public class ShortKitFeedView: UIView {
 
     // MARK: - Props (set by RCTViewManager)
 
     @objc public var config: String? {
-        didSet { /* reserved for future use */ }
+        didSet { /* config is read once at embed time; changes require remount */ }
     }
 
-    @objc public var overlayType: String? {
-        didSet { /* overlay mode is determined at ShortKit init time */ }
+    @objc public var startAtItemId: String? {
+        didSet { /* used at init time only */ }
     }
 
+    @objc public var preloadId: String? {
+        didSet { /* used at init time only */ }
+    }
+
+    @objc var feedId: String?
+
     // MARK: - Child VC
 
     private var feedViewController: ShortKitFeedViewController?
 
-    // MARK: - Scroll Tracking
-
-    private var scrollObservation: NSKeyValueObservation?
-    /// Video overlay for the currently active cell (nativeID="overlay-current").
-    private weak var currentOverlayView: UIView?
-    /// Video overlay for the upcoming cell (nativeID="overlay-next").
-    private weak var nextOverlayView: UIView?
-    /// Carousel overlay for the currently active cell (nativeID="carousel-overlay-current").
-    private weak var currentCarouselOverlayView: UIView?
-    /// Carousel overlay for the upcoming cell (nativeID="carousel-overlay-next").
-    private weak var nextCarouselOverlayView: UIView?
-    /// The page index used for overlay transform calculations.
-    private var currentPage: Int = 0
-    /// Closure to execute the pending overlay transform swap once JS signals ready.
-    private var pendingSwap: (() -> Void)?
-    /// Fallback timer in case JS never calls notifyOverlayReady.
-    private var swapFallbackWorkItem: DispatchWorkItem?
-    /// Observer for the overlay-ready notification from the JS bridge.
-    private var overlayReadyObserver: NSObjectProtocol?
-
     // MARK: - Lifecycle
 
     public override func didMoveToWindow() {
@@ -58,7 +40,7 @@ import ShortKitSDK
         super.willMove(toWindow: newWindow)
 
         if newWindow == nil {
-            removeFeedViewController()
+            suspendFeedViewController()
         }
     }
 
@@ -67,237 +49,109 @@ import ShortKitSDK
         feedViewController?.view.frame = bounds
     }
 
+    deinit {
+        destroyFeedViewController()
+    }
+
     // MARK: - VC Containment
 
     private func embedFeedViewControllerIfNeeded() {
-        // Already embedded
-        guard feedViewController == nil else { return }
-
-        guard let sdk = ShortKitBridge.shared?.sdk else {
-            NSLog("[ShortKitFeedView] ShortKit SDK not initialized. Call ShortKitModule.initialize() first.")
-            return
-        }
-
         guard let parentVC = findParentViewController() else {
-            NSLog("[ShortKitFeedView] Could not find parent UIViewController.")
             return
         }
 
-        let feedVC = ShortKitFeedViewController(shortKit: sdk)
-        self.feedViewController = feedVC
-
-        parentVC.addChild(feedVC)
-        feedVC.view.frame = bounds
-        feedVC.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
-        addSubview(feedVC.view)
-        feedVC.didMove(toParent: parentVC)
-
-        setupScrollTracking(feedVC)
-        setupOverlayReadyObserver()
-    }
-
-    private func removeFeedViewController() {
-        pendingSwap = nil
-        swapFallbackWorkItem?.cancel()
-        swapFallbackWorkItem = nil
-        if let observer = overlayReadyObserver {
-            NotificationCenter.default.removeObserver(observer)
-            overlayReadyObserver = nil
+        // Re-attach an existing suspended VC (e.g. after native stack pop)
+        if let feedVC = feedViewController {
+            parentVC.addChild(feedVC)
+            feedVC.view.frame = bounds
+            addSubview(feedVC.view)
+            feedVC.didMove(toParent: parentVC)
+            feedVC.activate()
+            if let feedId = self.feedId {
+                ShortKitBridge.shared?.registerFeed(id: feedId, viewController: feedVC)
+            }
+            return
         }
-        scrollObservation?.invalidate()
-        scrollObservation = nil
-        currentOverlayView?.transform = .identity
-        nextOverlayView?.transform = .identity
-        currentCarouselOverlayView?.transform = .identity
-        nextCarouselOverlayView?.transform = .identity
-        currentOverlayView = nil
-        nextOverlayView = nil
-        currentCarouselOverlayView = nil
-        nextCarouselOverlayView = nil
-
-        guard let feedVC = feedViewController else { return }
-
-        feedVC.willMove(toParent: nil)
-        feedVC.view.removeFromSuperview()
-        feedVC.removeFromParent()
-
-        self.feedViewController = nil
-    }
 
-    // MARK: - Scroll Tracking
-
-    private func setupScrollTracking(_ feedVC: ShortKitFeedViewController) {
-        guard let scrollView = findScrollView(in: feedVC.view) else {
+        guard let sdk = ShortKitBridge.shared?.sdk else {
             return
         }
 
-        scrollObservation = scrollView.observe(\.contentOffset, options: [.new]) { [weak self] sv, _ in
-            self?.handleScrollOffset(sv)
-        }
-    }
+        // Parse config from the Fabric view prop
+        var feedConfig = ShortKitBridge.parseFeedConfig(self.config ?? "{}")
 
-    private func handleScrollOffset(_ scrollView: UIScrollView) {
-        let cellHeight = scrollView.bounds.height
-        guard cellHeight > 0 else { return }
-
-        let offset = scrollView.contentOffset.y
-
-        // Detect page change, but DEFER updating currentPage until JS
-        // signals that overlay-current has been re-rendered with new content.
-        //
-        // Why: when the scroll settles on a new page, overlay-current still
-        // shows the OLD page's metadata. If we update currentPage immediately,
-        // delta snaps to 0 and overlay-current becomes visible with stale data.
-        //
-        // Instead, we store a pending swap closure. JS calls notifyOverlayReady()
-        // after processing OVERLAY_ACTIVATE and resetting overlay opacity, which
-        // executes the swap deterministically. A fallback timer catches edge cases.
-        let nearestPage = Int(round(offset / cellHeight))
-        if abs(offset - CGFloat(nearestPage) * cellHeight) < 1.0 {
-            if nearestPage != currentPage && pendingSwap == nil {
-                let targetPage = nearestPage
-                pendingSwap = { [weak self] in
-                    guard let self else { return }
-                    self.currentPage = targetPage
-                    self.pendingSwap = nil
-                    self.swapFallbackWorkItem?.cancel()
-                    self.swapFallbackWorkItem = nil
-                    // Reapply overlay transforms now that currentPage is updated.
-                    let h = self.bounds.height
-                    self.currentOverlayView?.transform = .identity
-                    self.nextOverlayView?.transform = CGAffineTransform(translationX: 0, y: h)
-                    self.currentCarouselOverlayView?.transform = .identity
-                    self.nextCarouselOverlayView?.transform = CGAffineTransform(translationX: 0, y: h)
-                }
-                // Fallback: if JS never signals (e.g. overlay config is 'none'),
-                // execute after 500ms to avoid getting stuck.
-                let fallback = DispatchWorkItem { [weak self] in
-                    self?.pendingSwap?()
-                }
-                swapFallbackWorkItem = fallback
-                DispatchQueue.main.asyncAfter(deadline: .now() + 0.5, execute: fallback)
+        // Consume preload handle if available
+        if let preloadId = self.preloadId {
+            NSLog("[ShortKit FeedView] preloadId prop: %@", preloadId)
+            if let preload = ShortKitBridge.shared?.consumePreload(id: preloadId) {
+                feedConfig.preload = preload
+                NSLog("[ShortKit FeedView] ✅ Preload handle consumed for feedId: %@", preloadId)
+            } else {
+                NSLog("[ShortKit FeedView] ❌ No preload handle found for feedId: %@", preloadId)
+                NSLog("[ShortKit FeedView] Available preload handles: %@", ShortKitBridge.shared?.preloadHandles.keys.joined(separator: ", ") ?? "none")
             }
-        } else if pendingSwap != nil {
-            // User is scrolling again — execute pending swap immediately
-            // so transforms stay aligned for the new gesture.
-            pendingSwap?()
+        } else {
+            NSLog("[ShortKit FeedView] No preloadId prop set")
         }
 
-        let delta = offset - CGFloat(currentPage) * cellHeight
+        NSLog("[ShortKit FeedView] feedConfig.preload is %@", feedConfig.preload != nil ? "SET" : "NIL")
+        NSLog("[ShortKit FeedView] feedConfig.feedSource: %@", feedConfig.feedSource == .custom ? "custom" : "algorithmic")
 
-        // Find the overlay views if not cached
-        if currentOverlayView == nil || nextOverlayView == nil {
-            findOverlayViews()
-        }
-        if currentCarouselOverlayView == nil || nextCarouselOverlayView == nil {
-            findCarouselOverlayViews()
-        }
+        NSLog("[ShortKit FeedView] Creating ShortKitFeedViewController with config.preload=%@, config.feedSource=%@",
+              feedConfig.preload != nil ? "SET" : "NIL",
+              feedConfig.feedSource == .custom ? "custom" : "algorithmic")
 
-        let translateY = CGAffineTransform(translationX: 0, y: -delta)
+        let feedVC = ShortKitFeedViewController(shortKit: sdk, config: feedConfig, startAtItemId: startAtItemId)
+        feedVC.setBridgeManaged()
 
-        // Current overlays follow the active cell
-        currentOverlayView?.transform = translateY
-        currentCarouselOverlayView?.transform = translateY
+        NSLog("[ShortKit FeedView] VC created successfully (bridge-managed)")
 
-        // Next overlays: positioned one page ahead in the scroll direction
-        if delta >= 0 {
-            // Forward scroll (or idle): next cell is below
-            let nextTransform = CGAffineTransform(translationX: 0, y: cellHeight - delta)
-            nextOverlayView?.transform = nextTransform
-            nextCarouselOverlayView?.transform = nextTransform
-        } else {
-            // Backward scroll: next cell is above
-            let nextTransform = CGAffineTransform(translationX: 0, y: -cellHeight - delta)
-            nextOverlayView?.transform = nextTransform
-            nextCarouselOverlayView?.transform = nextTransform
+        feedVC.onDismiss = {
+            ShortKitBridge.shared?.emitDismiss()
         }
-    }
 
-    // MARK: - Overlay Ready Handshake
-
-    private func setupOverlayReadyObserver() {
-        overlayReadyObserver = NotificationCenter.default.addObserver(
-            forName: .shortKitOverlayReady,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
-            self?.pendingSwap?()
+        self.feedViewController = feedVC
+        if let feedId = self.feedId {
+            ShortKitBridge.shared?.registerFeed(id: feedId, viewController: feedVC)
         }
-    }
 
-    /// Find the sibling RN overlay views by nativeID.
-    ///
-    /// In Fabric interop, `ShortKitFeedView` (a Paper-style `RCTViewManager`
-    /// view) is wrapped in an intermediate `RCTViewComponentView`. So
-    /// `self.superview` is that wrapper — not the React `<View>` container
-    /// rendered by ShortKitFeed.tsx. We walk up the ancestor chain until we
-    /// find the overlays.
-    private func findOverlayViews() {
-        var ancestor: UIView? = superview
-        while let container = ancestor {
-            for child in container.subviews {
-                // Skip subtrees that contain ourselves
-                guard !self.isDescendant(of: child) else { continue }
-
-                if currentOverlayView == nil {
-                    currentOverlayView = findView(withNativeID: "overlay-current", in: child)
-                }
-                if nextOverlayView == nil {
-                    nextOverlayView = findView(withNativeID: "overlay-next", in: child)
-                }
-            }
-            if currentOverlayView != nil && nextOverlayView != nil { return }
-            ancestor = container.superview
-        }
+        parentVC.addChild(feedVC)
+        feedVC.view.frame = bounds
+        feedVC.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        addSubview(feedVC.view)
+        feedVC.didMove(toParent: parentVC)
     }
 
-    /// Find the sibling RN carousel overlay views by nativeID.
-    private func findCarouselOverlayViews() {
-        var ancestor: UIView? = superview
-        while let container = ancestor {
-            for child in container.subviews {
-                guard !self.isDescendant(of: child) else { continue }
-
-                if currentCarouselOverlayView == nil {
-                    currentCarouselOverlayView = findView(withNativeID: "carousel-overlay-current", in: child)
-                }
-                if nextCarouselOverlayView == nil {
-                    nextCarouselOverlayView = findView(withNativeID: "carousel-overlay-next", in: child)
-                }
-            }
-            if currentCarouselOverlayView != nil && nextCarouselOverlayView != nil { return }
-            ancestor = container.superview
+    /// Detach the feedVC from the parent VC hierarchy without destroying it.
+    /// Called when the native stack temporarily removes this view from the window
+    /// (e.g. pushing a new screen on top). The feedVC and its state are preserved
+    /// so they can be re-attached when the view returns to the window.
+    private func suspendFeedViewController() {
+        if let feedId = self.feedId {
+            ShortKitBridge.shared?.unregisterFeed(id: feedId)
         }
-    }
+        guard let feedVC = feedViewController else { return }
 
-    /// Recursively find a view by its React Native `nativeID` prop.
-    /// In Fabric, this is stored on `RCTViewComponentView.nativeId`,
-    /// not `accessibilityIdentifier`.
-    private func findView(withNativeID nativeID: String, in view: UIView) -> UIView? {
-        if view.responds(to: Selector(("nativeId"))),
-           let rnNativeId = view.value(forKey: "nativeId") as? String,
-           rnNativeId == nativeID {
-            return view
-        }
-        for subview in view.subviews {
-            if let found = findView(withNativeID: nativeID, in: subview) {
-                return found
-            }
-        }
-        return nil
+        feedVC.deactivate()
+        feedVC.willMove(toParent: nil)
+        feedVC.view.removeFromSuperview()
+        feedVC.removeFromParent()
+        // Keep feedViewController reference — re-attached in embedFeedViewControllerIfNeeded
     }
 
-    /// Recursively find the first UIScrollView in a view hierarchy.
-    private func findScrollView(in view: UIView) -> UIScrollView? {
-        if let sv = view as? UIScrollView {
-            return sv
-        }
-        for subview in view.subviews {
-            if let sv = findScrollView(in: subview) {
-                return sv
-            }
+    /// Full teardown — called from deinit when React unmounts the native view.
+    private func destroyFeedViewController() {
+        if let feedId = self.feedId {
+            ShortKitBridge.shared?.unregisterFeed(id: feedId)
         }
-        return nil
+        guard let feedVC = feedViewController else { return }
+
+        feedVC.deactivate()
+        feedVC.willMove(toParent: nil)
+        feedVC.view.removeFromSuperview()
+        feedVC.removeFromParent()
+
+        self.feedViewController = nil
     }
 
     // MARK: - Helpers

package/ios/ShortKitFeedViewManager.mm

@@ -23,7 +23,8 @@ RCT_EXPORT_MODULE(ShortKitFeedView)
 }
 
 RCT_EXPORT_VIEW_PROPERTY(config, NSString)
-RCT_EXPORT_VIEW_PROPERTY(overlayType, NSString)
-RCT_EXPORT_VIEW_PROPERTY(templateName, NSString)
+RCT_EXPORT_VIEW_PROPERTY(startAtItemId, NSString)
+RCT_EXPORT_VIEW_PROPERTY(preloadId, NSString)
+RCT_EXPORT_VIEW_PROPERTY(feedId, NSString)
 
 @end

package/ios/ShortKitModule.mm

@@ -11,8 +11,11 @@
 @implementation ShortKitModule {
   ShortKitBridge *_shortKitBridge;
   BOOL _hasListeners;
-  NSString *_pendingFeedItems;
-  NSString *_pendingAppendItems;
+  id _surfacePresenter;
+  // Buffer feed ops that arrive before the bridge is initialized.
+  // React fires child effects (MainScreen) before parent effects (ShortKitProvider),
+  // so setFeedItems can be called before initialize completes.
+  NSMutableArray<void(^)(void)> *_pendingBridgeOps;
 }
 
 RCT_EXPORT_MODULE(ShortKitModule)
@@ -33,6 +36,13 @@ RCT_EXPORT_MODULE(ShortKitModule)
   return self;
 }
 
+/// Called automatically by RCTInstance for modules that respond to this selector.
+/// This is the recommended way to receive the surface presenter in the new architecture.
+- (void)setSurfacePresenter:(id)surfacePresenter {
+  _surfacePresenter = surfacePresenter;
+  [_shortKitBridge updateSurfacePresenter:surfacePresenter];
+}
+
 /// Called when the RN bridge tears down (hot reload, app shutdown).
 - (void)invalidate {
   [_shortKitBridge teardown];
@@ -58,19 +68,21 @@ RCT_EXPORT_MODULE(ShortKitModule)
     @"onFormatChange",
     @"onPrefetchedAheadCountChanged",
     @"onRemainingContentCountChanged",
-    @"onError",
-    @"onShareTapped",
     @"onSurveyResponse",
-    @"onOverlayConfigure",
-    @"onOverlayActivate",
-    @"onOverlayReset",
-    @"onOverlayTap",
-    @"onOverlayDoubleTap",
     @"onContentTapped",
-    @"onCarouselOverlayConfigure",
-    @"onCarouselOverlayActivate",
-    @"onCarouselOverlayReset",
-    @"onCarouselPageChanged",
+    @"onDismiss",
+    @"onFeedReady",
+    @"onRefreshRequested",
+    @"onDidFetchContentItems",
+    @"onOverlayActiveChanged",
+    @"onOverlayPlayerStateChanged",
+    @"onOverlayMutedChanged",
+    @"onOverlayPlaybackRateChanged",
+    @"onOverlayCaptionsEnabledChanged",
+    @"onOverlayActiveCueChanged",
+    @"onOverlayFeedScrollPhaseChanged",
+    @"onOverlayTimeUpdate",
+    @"onOverlayFullState",
   ];
 }
 
@@ -108,7 +120,7 @@ RCT_EXPORT_MODULE(ShortKitModule)
 // MARK: - Lifecycle
 
 RCT_EXPORT_METHOD(initialize:(NSString *)apiKey
-                  config:(NSString *)config
+                  hasLoadingView:(BOOL)hasLoadingView
                   clientAppName:(NSString *)clientAppName
                   clientAppVersion:(NSString *)clientAppVersion
                   customDimensions:(NSString *)customDimensions) {
@@ -116,20 +128,19 @@ RCT_EXPORT_METHOD(initialize:(NSString *)apiKey
   [_shortKitBridge teardown];
 
   _shortKitBridge = [[ShortKitBridge alloc] initWithApiKey:apiKey
-                                                   config:config
+                                            hasLoadingView:hasLoadingView
                                             clientAppName:clientAppName
                                          clientAppVersion:clientAppVersion
                                          customDimensions:customDimensions
-                                                 delegate:self];
+                                                 delegate:self
+                                         surfacePresenter:_surfacePresenter];
 
-  // Replay any feed items that arrived before initialization
-  if (_pendingFeedItems) {
-    [_shortKitBridge setFeedItems:_pendingFeedItems];
-    _pendingFeedItems = nil;
-  }
-  if (_pendingAppendItems) {
-    [_shortKitBridge appendFeedItems:_pendingAppendItems];
-    _pendingAppendItems = nil;
+  // Replay any feed ops that arrived before the bridge was ready
+  if (_pendingBridgeOps) {
+    for (void(^op)(void) in _pendingBridgeOps) {
+      op();
+    }
+    _pendingBridgeOps = nil;
   }
 }
 
@@ -206,30 +217,57 @@ RCT_EXPORT_METHOD(setMaxBitrate:(double)bitrate) {
 
 // MARK: - Custom Feed
 
-RCT_EXPORT_METHOD(setFeedItems:(NSString *)items) {
+RCT_EXPORT_METHOD(setFeedItems:(NSString *)feedId items:(NSString *)items) {
   if (_shortKitBridge) {
-    [_shortKitBridge setFeedItems:items];
+    [_shortKitBridge setFeedItems:feedId items:items];
   } else {
-    _pendingFeedItems = items;
+    if (!_pendingBridgeOps) _pendingBridgeOps = [NSMutableArray new];
+    [_pendingBridgeOps addObject:^{
+      [self->_shortKitBridge setFeedItems:feedId items:items];
+    }];
   }
 }
 
-RCT_EXPORT_METHOD(appendFeedItems:(NSString *)items) {
+RCT_EXPORT_METHOD(appendFeedItems:(NSString *)feedId items:(NSString *)items) {
   if (_shortKitBridge) {
-    [_shortKitBridge appendFeedItems:items];
+    [_shortKitBridge appendFeedItems:feedId items:items];
   } else {
-    _pendingAppendItems = items;
+    if (!_pendingBridgeOps) _pendingBridgeOps = [NSMutableArray new];
+    [_pendingBridgeOps addObject:^{
+      [self->_shortKitBridge appendFeedItems:feedId items:items];
+    }];
   }
 }
 
 RCT_EXPORT_METHOD(fetchContent:(NSInteger)limit
+                  filterJSON:(NSString *)filterJSON
                   resolve:(RCTPromiseResolveBlock)resolve
                   reject:(RCTPromiseRejectBlock)reject) {
-  [_shortKitBridge fetchContent:limit completion:^(NSString *json) {
+  [_shortKitBridge fetchContent:limit filterJSON:filterJSON completion:^(NSString *json) {
     resolve(json);
   }];
 }
 
+RCT_EXPORT_METHOD(applyFilter:(NSString *)feedId filterJSON:(NSString *)filterJSON) {
+  if (_shortKitBridge) {
+    [_shortKitBridge applyFilter:feedId filterJSON:filterJSON];
+  } else {
+    if (!_pendingBridgeOps) _pendingBridgeOps = [NSMutableArray new];
+    [_pendingBridgeOps addObject:^{
+      [self->_shortKitBridge applyFilter:feedId filterJSON:filterJSON];
+    }];
+  }
+}
+
+RCT_EXPORT_METHOD(preloadFeed:(NSString *)configJSON
+                  itemsJSON:(NSString *)itemsJSON
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject) {
+  [_shortKitBridge preloadFeed:configJSON itemsJSON:itemsJSON completion:^(NSString *uuid) {
+    resolve(uuid);
+  }];
+}
+
 // MARK: - Storyboard / Seek Thumbnails
 
 RCT_EXPORT_METHOD(prefetchStoryboard:(NSString *)playbackId) {
@@ -248,12 +286,6 @@ RCT_EXPORT_METHOD(getStoryboardData:(NSString *)playbackId
   }];
 }
 
-// MARK: - Overlay Lifecycle
-
-RCT_EXPORT_METHOD(notifyOverlayReady) {
-  [_shortKitBridge notifyOverlayReady];
-}
-
 // MARK: - New Architecture (TurboModule)
 
 #ifdef RCT_NEW_ARCH_ENABLED

package/ios/ShortKitPlayerNativeView.swift

@@ -49,7 +49,7 @@ import ShortKitSDK
     public override func willMove(toWindow newWindow: UIWindow?) {
         super.willMove(toWindow: newWindow)
         if newWindow == nil {
-            removePlayerVC()
+            suspendPlayerVC()
         }
     }
 
@@ -58,13 +58,30 @@ import ShortKitSDK
         playerVC?.view.frame = bounds
     }
 
+    deinit {
+        destroyPlayerVC()
+    }
+
     // MARK: - VC Containment
 
     private func embedPlayerVCIfNeeded() {
-        guard playerVC == nil else { return }
-        guard let sdk = ShortKitBridge.shared?.sdk else { return }
         guard let parentVC = findParentViewController() else { return }
 
+        // Re-attach a suspended VC (e.g. after native stack pop)
+        if let vc = playerVC {
+            parentVC.addChild(vc)
+            vc.view.frame = bounds
+            addSubview(vc.view)
+            vc.didMove(toParent: parentVC)
+            if active {
+                vc.activate()
+            }
+            return
+        }
+
+        // First mount — create a new VC
+        guard let sdk = ShortKitBridge.shared?.sdk else { return }
+
         let playerConfig = parsedConfig ?? PlayerConfig()
 
         let vc = ShortKitPlayerViewController(shortKit: sdk, config: playerConfig)
@@ -88,7 +105,21 @@ import ShortKitSDK
         }
     }
 
-    private func removePlayerVC() {
+    /// Detach the playerVC from the parent VC hierarchy without destroying it.
+    /// Called when the native stack temporarily removes this view from the window
+    /// (e.g. pushing a new screen on top). The playerVC and its thumbnail are
+    /// preserved so they can be re-attached instantly when the view returns.
+    private func suspendPlayerVC() {
+        guard let vc = playerVC else { return }
+        vc.deactivate()
+        vc.willMove(toParent: nil)
+        vc.view.removeFromSuperview()
+        vc.removeFromParent()
+        // Keep playerVC reference — re-attached in embedPlayerVCIfNeeded
+    }
+
+    /// Full teardown — called from deinit when React unmounts the native view.
+    private func destroyPlayerVC() {
         guard let vc = playerVC else { return }
         vc.deactivate()
         vc.willMove(toParent: nil)
@@ -104,7 +135,7 @@ import ShortKitSDK
         parsedConfig = Self.parsePlayerConfig(json)
         // Config changes require re-embedding
         if playerVC != nil {
-            removePlayerVC()
+            destroyPlayerVC()
             embedPlayerVCIfNeeded()
         }
     }
@@ -148,9 +179,9 @@ import ShortKitSDK
         if let overlayObj = obj["overlay"] as? [String: Any],
            overlayObj["type"] as? String == "custom" {
             overlayMode = .custom { @Sendable in
-                let overlay = ShortKitOverlayBridge()
-                overlay.bridge = ShortKitBridge.shared
-                return overlay
+                let host = ReactOverlayHost()
+                host.surfacePresenter = ShortKitBridge.shared?.surfacePresenter
+                return host
             }
         } else {
             overlayMode = .none

package/ios/ShortKitReactNative-Bridging-Header.h

@@ -1,3 +1,5 @@
 #import <React/RCTBridgeModule.h>
 #import <React/RCTEventEmitter.h>
+#import <React-RCTFabric/React/RCTFabricSurface.h>
+#import <React-RCTFabric/React/RCTSurfacePresenter.h>
 #import "ShortKitModule.h"

package/ios/ShortKitSDK.xcframework/ios-arm64/ShortKitSDK.framework/Headers/ShortKitSDK-Swift.h

@@ -365,7 +365,7 @@ SWIFT_CLASS("_TtC11ShortKitSDK26ShortKitFeedViewController")
 
 /// Public single-video player view controller.
 /// Starts in thumbnail-only mode and borrows an AVPlayer from the shared
-/// <code>TilePlayerPool</code> when activated. Call <code>activate()</code> when the tile becomes
+/// <code>PlayerPool</code> tile slots when activated. Call <code>activate()</code> when the tile becomes
 /// visible and <code>deactivate()</code> when it scrolls offscreen.
 SWIFT_CLASS("_TtC11ShortKitSDK28ShortKitPlayerViewController")
 @interface ShortKitPlayerViewController : UIViewController