@shortkitsdk/react-native 0.2.1 → 0.2.3

package/ShortKitReactNative.podspec

@@ -13,7 +13,14 @@ Pod::Spec.new do |s|
   s.source_files = "ios/*.{h,m,mm,cpp,swift}"
   s.requires_arc = true
 
-  s.dependency "ShortKit"
+  # When the vendored XCFramework is present (npm published package), use it.
+  # Otherwise fall back to the local ShortKit pod (development).
+  xcframework_path = File.join(__dir__, "ios", "ShortKitSDK.xcframework")
+  if File.exist?(xcframework_path)
+    s.vendored_frameworks = "ios/ShortKitSDK.xcframework"
+  else
+    s.dependency "ShortKit"
+  end
 
   install_modules_dependencies(s)
 end

package/android/src/main/java/com/shortkit/reactnative/ShortKitCarouselOverlayBridge.kt

@@ -0,0 +1,48 @@
+package com.shortkit.reactnative
+
+import android.content.Context
+import android.graphics.Color
+import android.widget.FrameLayout
+import com.facebook.react.bridge.Arguments
+import com.shortkit.sdk.model.ImageCarouselItem
+import com.shortkit.sdk.overlay.CarouselOverlay
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+
+/**
+ * A transparent [FrameLayout] that implements [CarouselOverlay] and bridges
+ * carousel overlay lifecycle calls to JS events via [ShortKitModule].
+ *
+ * The actual carousel overlay UI is rendered by React Native on the JS side
+ * through the `CarouselOverlayManager` component. This view simply relays
+ * the SDK lifecycle events so the JS carousel overlay knows when to
+ * configure, activate, reset, etc.
+ *
+ * Android equivalent of iOS `ShortKitCarouselOverlayBridge.swift`.
+ */
+class ShortKitCarouselOverlayBridge(context: Context) : FrameLayout(context), CarouselOverlay {
+
+    init {
+        setBackgroundColor(Color.TRANSPARENT)
+    }
+
+    override fun configure(item: ImageCarouselItem) {
+        val json = Json.encodeToString(item)
+        val params = Arguments.createMap().apply {
+            putString("item", json)
+        }
+        ShortKitModule.shared?.emitCarouselOverlayEvent("onCarouselOverlayConfigure", params)
+    }
+
+    override fun resetState() {
+        ShortKitModule.shared?.emitCarouselOverlayEvent("onCarouselOverlayReset", Arguments.createMap())
+    }
+
+    override fun fadeOutForTransition() {
+        ShortKitModule.shared?.emitCarouselOverlayEvent("onCarouselOverlayFadeOut", Arguments.createMap())
+    }
+
+    override fun restoreFromTransition() {
+        ShortKitModule.shared?.emitCarouselOverlayEvent("onCarouselOverlayRestore", Arguments.createMap())
+    }
+}

package/android/src/main/java/com/shortkit/reactnative/ShortKitFeedView.kt

@@ -51,12 +51,18 @@ class ShortKitFeedView(context: Context) : FrameLayout(context) {
     private var viewPager: ViewPager2? = null
     private var pageChangeCallback: ViewPager2.OnPageChangeCallback? = null
 
-    /** Overlay for the currently active cell (nativeID="overlay-current"). */
+    /** Video overlay for the currently active cell (nativeID="overlay-current"). */
     private var currentOverlayView: View? = null
 
-    /** Overlay for the upcoming cell (nativeID="overlay-next"). */
+    /** Video overlay for the upcoming cell (nativeID="overlay-next"). */
     private var nextOverlayView: View? = null
 
+    /** Carousel overlay for the currently active cell (nativeID="carousel-overlay-current"). */
+    private var currentCarouselOverlayView: View? = null
+
+    /** Carousel overlay for the upcoming cell (nativeID="carousel-overlay-next"). */
+    private var nextCarouselOverlayView: View? = null
+
     /** The page index used for overlay transform calculations. */
     private var currentPage: Int = 0
 
@@ -158,8 +164,12 @@ class ShortKitFeedView(context: Context) : FrameLayout(context) {
         viewPager = null
         currentOverlayView?.translationY = 0f
         nextOverlayView?.translationY = 0f
+        currentCarouselOverlayView?.translationY = 0f
+        nextCarouselOverlayView?.translationY = 0f
         currentOverlayView = null
         nextOverlayView = null
+        currentCarouselOverlayView = null
+        nextCarouselOverlayView = null
     }
 
     private fun handleScrollOffset(
@@ -193,6 +203,8 @@ class ShortKitFeedView(context: Context) : FrameLayout(context) {
                     val h = height.toFloat()
                     currentOverlayView?.translationY = 0f
                     nextOverlayView?.translationY = h
+                    currentCarouselOverlayView?.translationY = 0f
+                    nextCarouselOverlayView?.translationY = h
                 }
                 pageUpdateRunnable = runnable
                 handler.postDelayed(runnable, 80)
@@ -219,17 +231,25 @@ class ShortKitFeedView(context: Context) : FrameLayout(context) {
         if (currentOverlayView == null || nextOverlayView == null) {
             findOverlayViews()
         }
+        if (currentCarouselOverlayView == null || nextCarouselOverlayView == null) {
+            findCarouselOverlayViews()
+        }
 
-        // Current overlay follows the active cell
+        // Current overlays follow the active cell
         currentOverlayView?.translationY = -delta
+        currentCarouselOverlayView?.translationY = -delta
 
-        // Next overlay: positioned one page ahead in the scroll direction
+        // Next overlays: positioned one page ahead in the scroll direction
         if (delta >= 0) {
             // Forward scroll (or idle): next cell is below
-            nextOverlayView?.translationY = cellHeight - delta
+            val nextY = cellHeight - delta
+            nextOverlayView?.translationY = nextY
+            nextCarouselOverlayView?.translationY = nextY
         } else {
             // Backward scroll: next cell is above
-            nextOverlayView?.translationY = -cellHeight - delta
+            val nextY = -cellHeight - delta
+            nextOverlayView?.translationY = nextY
+            nextCarouselOverlayView?.translationY = nextY
         }
     }
 
@@ -260,6 +280,28 @@ class ShortKitFeedView(context: Context) : FrameLayout(context) {
         }
     }
 
+    /**
+     * Find the sibling RN carousel overlay views by nativeID.
+     */
+    private fun findCarouselOverlayViews() {
+        var ancestor = parent as? ViewGroup ?: return
+        while (true) {
+            for (i in 0 until ancestor.childCount) {
+                val child = ancestor.getChildAt(i)
+                if (child === this || isOwnAncestor(child)) continue
+
+                if (currentCarouselOverlayView == null) {
+                    currentCarouselOverlayView = ReactFindViewUtil.findView(child, "carousel-overlay-current")
+                }
+                if (nextCarouselOverlayView == null) {
+                    nextCarouselOverlayView = ReactFindViewUtil.findView(child, "carousel-overlay-next")
+                }
+            }
+            if (currentCarouselOverlayView != null && nextCarouselOverlayView != null) return
+            ancestor = ancestor.parent as? ViewGroup ?: return
+        }
+    }
+
     /** Check if the given view is an ancestor of this view. */
     private fun isOwnAncestor(view: View): Boolean {
         var current: ViewParent? = parent

package/android/src/main/java/com/shortkit/reactnative/ShortKitModule.kt

@@ -50,6 +50,8 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
     private var listenerCount = 0
     @Volatile
     private var hasListeners = false
+    private var pendingFeedItems: String? = null
+    private var pendingAppendItems: String? = null
 
     /** Expose the underlying SDK for the Fabric feed view manager. */
     val sdk: ShortKit? get() = shortKit
@@ -120,6 +122,16 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
         this.shortKit = sdk
         shared = this
 
+        // Replay any feed items that arrived before initialization
+        pendingFeedItems?.let { json ->
+            parseCustomFeedItems(json)?.let { sdk.setFeedItems(it) }
+            pendingFeedItems = null
+        }
+        pendingAppendItems?.let { json ->
+            parseCustomFeedItems(json)?.let { sdk.appendFeedItems(it) }
+            pendingAppendItems = null
+        }
+
         subscribeToFlows(sdk.player)
 
         sdk.delegate = object : com.shortkit.ShortKitDelegate {
@@ -233,14 +245,24 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
 
     @ReactMethod
     override fun setFeedItems(items: String) {
-        val parsed = parseCustomFeedItems(items) ?: return
-        shortKit?.setFeedItems(parsed)
+        val sdk = shortKit
+        if (sdk != null) {
+            val parsed = parseCustomFeedItems(items) ?: return
+            sdk.setFeedItems(parsed)
+        } else {
+            pendingFeedItems = items
+        }
     }
 
     @ReactMethod
     override fun appendFeedItems(items: String) {
-        val parsed = parseCustomFeedItems(items) ?: return
-        shortKit?.appendFeedItems(parsed)
+        val sdk = shortKit
+        if (sdk != null) {
+            val parsed = parseCustomFeedItems(items) ?: return
+            sdk.appendFeedItems(parsed)
+        } else {
+            pendingAppendItems = items
+        }
     }
 
     @ReactMethod
@@ -279,6 +301,14 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
         sendEvent(name, params)
     }
 
+    // -----------------------------------------------------------------------
+    // Carousel overlay lifecycle events
+    // -----------------------------------------------------------------------
+
+    fun emitCarouselOverlayEvent(name: String, params: WritableMap) {
+        sendEvent(name, params)
+    }
+
     // -----------------------------------------------------------------------
     // Flow subscriptions
     // -----------------------------------------------------------------------
@@ -642,10 +672,12 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
             val feedSourceStr = obj.optString("feedSource", "algorithmic")
             val feedSource = if (feedSourceStr == "custom") FeedSource.CUSTOM else FeedSource.ALGORITHMIC
 
+            val carouselOverlay = parseCarouselOverlay(obj.optString("carouselOverlay", null))
+
             FeedConfig(
                 feedHeight = feedHeight,
                 videoOverlay = videoOverlay,
-                carouselOverlay = CarouselOverlayMode.None,
+                carouselOverlay = carouselOverlay,
                 surveyOverlay = SurveyOverlayMode.None,
                 adOverlay = AdOverlayMode.None,
                 muteOnStart = muteOnStart,
@@ -712,6 +744,36 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
         }
     }
 
+    /**
+     * Parse a double-stringified carousel overlay JSON.
+     * - `"\"none\""` -> None
+     * - `"{\"type\":\"custom\"}"` -> Custom with bridge overlay factory
+     */
+    private fun parseCarouselOverlay(json: String?): CarouselOverlayMode {
+        if (json.isNullOrEmpty()) return CarouselOverlayMode.None
+        return try {
+            val parsed = json.trim()
+
+            if (parsed == "\"none\"" || parsed == "none") {
+                return CarouselOverlayMode.None
+            }
+
+            val inner = if (parsed.startsWith("\"") && parsed.endsWith("\"")) {
+                JSONObject(parsed.substring(1, parsed.length - 1).replace("\\\"", "\""))
+            } else {
+                JSONObject(parsed)
+            }
+
+            if (inner.optString("type") == "custom") {
+                CarouselOverlayMode.Custom { ShortKitCarouselOverlayBridge(reactApplicationContext) }
+            } else {
+                CarouselOverlayMode.None
+            }
+        } catch (_: Exception) {
+            CarouselOverlayMode.None
+        }
+    }
+
     private fun parseCustomFeedItems(json: String): List<CustomFeedItem>? {
         return try {
             val arr = JSONArray(json)

package/android/src/main/java/com/shortkit/reactnative/ShortKitOverlayBridge.kt

@@ -2,6 +2,8 @@ package com.shortkit.reactnative
 
 import android.content.Context
 import android.graphics.Color
+import android.os.Handler
+import android.os.Looper
 import android.view.GestureDetector
 import android.view.MotionEvent
 import android.widget.FrameLayout
@@ -32,6 +34,15 @@ class ShortKitOverlayBridge(context: Context) : FrameLayout(context), FeedOverla
      */
     private var currentItem: ContentItem? = null
 
+    /**
+     * Deferred configure emission — cancelled if [activatePlayback] fires
+     * on the same message-queue iteration (handleSwipe re-configure of the
+     * active cell, not a prefetch for the next cell).
+     */
+    private var pendingConfigureRunnable: Runnable? = null
+
+    private val handler = Handler(Looper.getMainLooper())
+
     // -----------------------------------------------------------------------
     // Gestures
     // -----------------------------------------------------------------------
@@ -76,7 +87,18 @@ class ShortKitOverlayBridge(context: Context) : FrameLayout(context), FeedOverla
 
     override fun configure(item: ContentItem) {
         currentItem = item
-        ShortKitModule.shared?.emitOverlayEvent("onOverlayConfigure", item)
+
+        // Defer the configure event by one message-queue tick. If activatePlayback()
+        // fires before then (handleSwipe sequence: configure → reset → activate),
+        // the event is cancelled — preventing nextItem from being overwritten
+        // with the current cell's data.
+        pendingConfigureRunnable?.let { handler.removeCallbacks(it) }
+        val runnable = Runnable {
+            currentItem?.let { ShortKitModule.shared?.emitOverlayEvent("onOverlayConfigure", it) }
+            pendingConfigureRunnable = null
+        }
+        pendingConfigureRunnable = runnable
+        handler.post(runnable)
     }
 
     override fun resetPlaybackProgress() {
@@ -85,6 +107,11 @@ class ShortKitOverlayBridge(context: Context) : FrameLayout(context), FeedOverla
     }
 
     override fun activatePlayback() {
+        // Cancel the pending configure — it was for the current cell (part of
+        // handleSwipe), not a prefetch for the next cell.
+        pendingConfigureRunnable?.let { handler.removeCallbacks(it) }
+        pendingConfigureRunnable = null
+
         val item = currentItem ?: return
         ShortKitModule.shared?.emitOverlayEvent("onOverlayActivate", item)
     }

package/ios/ShortKitBridge.swift

@@ -1,6 +1,6 @@
 import Foundation
 import Combine
-import ShortKit
+import ShortKitSDK
 
 /// Swift bridge between the ShortKit SDK and the Obj-C++ TurboModule.
 ///
@@ -347,6 +347,20 @@ import ShortKit
         emitOnMain(name, body: body)
     }
 
+    // MARK: - Carousel Overlay Lifecycle Events
+
+    /// Emit carousel overlay lifecycle events with an ImageCarouselItem.
+    public func emitCarouselOverlayEvent(_ name: String, item: ImageCarouselItem) {
+        guard let data = try? JSONEncoder().encode(item),
+              let json = String(data: data, encoding: .utf8) else { return }
+        emitOnMain(name, body: ["item": json])
+    }
+
+    /// Emit a raw carousel overlay event with an arbitrary body.
+    public func emitCarouselOverlayEvent(_ name: String, body: [String: Any]) {
+        emitOnMain(name, body: body)
+    }
+
     // MARK: - Content Item Serialization
 
     /// Serialize a ContentItem to a JSON string for bridge transport.
@@ -457,10 +471,12 @@ import ShortKit
         let feedSourceStr = obj["feedSource"] as? String ?? "algorithmic"
         let feedSource: FeedSource = feedSourceStr == "custom" ? .custom : .algorithmic
 
+        let carouselOverlay = parseCarouselOverlay(obj["carouselOverlay"] as? String)
+
         return FeedConfig(
             feedHeight: feedHeight,
             videoOverlay: videoOverlay,
-            carouselOverlay: .none,
+            carouselOverlay: carouselOverlay,
             surveyOverlay: .none,
             adOverlay: .none,
             muteOnStart: muteOnStart,
@@ -499,6 +515,35 @@ import ShortKit
         return .none
     }
 
+    /// Parse a double-stringified carousel overlay JSON into a `CarouselOverlayMode`.
+    ///
+    /// Examples:
+    /// - `"\"none\""` → `.none`
+    /// - `"{\"type\":\"custom\"}"` → `.custom { ShortKitCarouselOverlayBridge() }`
+    private static func parseCarouselOverlay(_ json: String?) -> CarouselOverlayMode {
+        guard let json,
+              let data = json.data(using: .utf8),
+              let parsed = try? JSONSerialization.jsonObject(with: data) else {
+            return .none
+        }
+
+        if let str = parsed as? String, str == "none" {
+            return .none
+        }
+
+        if let obj = parsed as? [String: Any],
+           let type = obj["type"] as? String,
+           type == "custom" {
+            return .custom { @Sendable in
+                let overlay = ShortKitCarouselOverlayBridge()
+                overlay.bridge = ShortKitBridge.shared
+                return overlay
+            }
+        }
+
+        return .none
+    }
+
     /// Parse a double-stringified feedHeight JSON.
     /// e.g. `"{\"type\":\"fullscreen\"}"` or `"{\"type\":\"percentage\",\"value\":0.8}"`
     private static func parseFeedHeight(_ json: String?) -> FeedHeight {

package/ios/ShortKitCarouselOverlayBridge.swift

@@ -0,0 +1,54 @@
+import UIKit
+import ShortKitSDK
+
+/// A transparent UIView that conforms to `CarouselOverlay` and bridges
+/// carousel overlay lifecycle calls to JS events via `ShortKitBridge`.
+///
+/// The actual carousel overlay UI is rendered by React Native on the JS side
+/// through the `CarouselOverlayManager` component. This view simply relays
+/// the SDK lifecycle events so the JS carousel overlay knows when to
+/// configure, activate, reset, etc.
+@objc public class ShortKitCarouselOverlayBridge: UIView, @unchecked Sendable, CarouselOverlay {
+
+    // MARK: - Bridge Reference
+
+    /// Weak reference to the bridge, set by the factory closure in `parseFeedConfig`.
+    weak var bridge: ShortKitBridge?
+
+    // MARK: - State
+
+    /// Stores the last configured ImageCarouselItem so we can pass it with
+    /// lifecycle events that don't receive the item as a parameter.
+    private var currentItem: ImageCarouselItem?
+
+    // MARK: - Init
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        backgroundColor = .clear
+        isUserInteractionEnabled = true
+    }
+
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) is not supported")
+    }
+
+    // MARK: - CarouselOverlay
+
+    public func configure(with item: ImageCarouselItem) {
+        currentItem = item
+        bridge?.emitCarouselOverlayEvent("onCarouselOverlayConfigure", item: item)
+    }
+
+    public func resetState() {
+        bridge?.emitCarouselOverlayEvent("onCarouselOverlayReset", body: [:])
+    }
+
+    public func fadeOutForTransition() {
+        bridge?.emitCarouselOverlayEvent("onCarouselOverlayFadeOut", body: [:])
+    }
+
+    public func restoreFromTransition() {
+        bridge?.emitCarouselOverlayEvent("onCarouselOverlayRestore", body: [:])
+    }
+}

package/ios/ShortKitFeedView.swift

@@ -1,5 +1,5 @@
 import UIKit
-import ShortKit
+import ShortKitSDK
 
 /// Fabric native view that embeds `ShortKitFeedViewController` using
 /// UIViewController containment. Props are set by the view manager via
@@ -27,10 +27,14 @@ import ShortKit
     // MARK: - Scroll Tracking
 
     private var scrollObservation: NSKeyValueObservation?
-    /// Overlay for the currently active cell (nativeID="overlay-current").
+    /// Video overlay for the currently active cell (nativeID="overlay-current").
     private weak var currentOverlayView: UIView?
-    /// Overlay for the upcoming cell (nativeID="overlay-next").
+    /// 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
     /// Deferred page update to avoid flashing stale metadata.
@@ -94,8 +98,12 @@ import ShortKit
         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 }
 
@@ -150,6 +158,8 @@ import ShortKit
                     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)
                 }
                 pageUpdateWorkItem = workItem
                 DispatchQueue.main.asyncAfter(deadline: .now() + 0.08, execute: workItem)
@@ -168,17 +178,27 @@ import ShortKit
         if currentOverlayView == nil || nextOverlayView == nil {
             findOverlayViews()
         }
+        if currentCarouselOverlayView == nil || nextCarouselOverlayView == nil {
+            findCarouselOverlayViews()
+        }
+
+        let translateY = CGAffineTransform(translationX: 0, y: -delta)
 
-        // Current overlay follows the active cell
-        currentOverlayView?.transform = CGAffineTransform(translationX: 0, y: -delta)
+        // Current overlays follow the active cell
+        currentOverlayView?.transform = translateY
+        currentCarouselOverlayView?.transform = translateY
 
-        // Next overlay: positioned one page ahead in the scroll direction
+        // Next overlays: positioned one page ahead in the scroll direction
         if delta >= 0 {
             // Forward scroll (or idle): next cell is below
-            nextOverlayView?.transform = CGAffineTransform(translationX: 0, y: cellHeight - delta)
+            let nextTransform = CGAffineTransform(translationX: 0, y: cellHeight - delta)
+            nextOverlayView?.transform = nextTransform
+            nextCarouselOverlayView?.transform = nextTransform
         } else {
             // Backward scroll: next cell is above
-            nextOverlayView?.transform = CGAffineTransform(translationX: 0, y: -cellHeight - delta)
+            let nextTransform = CGAffineTransform(translationX: 0, y: -cellHeight - delta)
+            nextOverlayView?.transform = nextTransform
+            nextCarouselOverlayView?.transform = nextTransform
         }
     }
 
@@ -208,6 +228,25 @@ import ShortKit
         }
     }
 
+    /// 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
+        }
+    }
+
     /// Recursively find a view by its React Native `nativeID` prop.
     /// In Fabric, this is stored on `RCTViewComponentView.nativeId`,
     /// not `accessibilityIdentifier`.

package/ios/ShortKitModule.mm

@@ -11,6 +11,8 @@
 @implementation ShortKitModule {
   ShortKitBridge *_shortKitBridge;
   BOOL _hasListeners;
+  NSString *_pendingFeedItems;
+  NSString *_pendingAppendItems;
 }
 
 RCT_EXPORT_MODULE(ShortKitModule)
@@ -118,6 +120,16 @@ RCT_EXPORT_METHOD(initialize:(NSString *)apiKey
                                          clientAppVersion:clientAppVersion
                                          customDimensions:customDimensions
                                                  delegate:self];
+
+  // Replay any feed items that arrived before initialization
+  if (_pendingFeedItems) {
+    [_shortKitBridge setFeedItems:_pendingFeedItems];
+    _pendingFeedItems = nil;
+  }
+  if (_pendingAppendItems) {
+    [_shortKitBridge appendFeedItems:_pendingAppendItems];
+    _pendingAppendItems = nil;
+  }
 }
 
 RCT_EXPORT_METHOD(destroy) {
@@ -194,11 +206,19 @@ RCT_EXPORT_METHOD(setMaxBitrate:(double)bitrate) {
 // MARK: - Custom Feed
 
 RCT_EXPORT_METHOD(setFeedItems:(NSString *)items) {
-  [_shortKitBridge setFeedItems:items];
+  if (_shortKitBridge) {
+    [_shortKitBridge setFeedItems:items];
+  } else {
+    _pendingFeedItems = items;
+  }
 }
 
 RCT_EXPORT_METHOD(appendFeedItems:(NSString *)items) {
-  [_shortKitBridge appendFeedItems:items];
+  if (_shortKitBridge) {
+    [_shortKitBridge appendFeedItems:items];
+  } else {
+    _pendingAppendItems = items;
+  }
 }
 
 RCT_EXPORT_METHOD(fetchContent:(NSInteger)limit

package/ios/ShortKitOverlayBridge.swift

@@ -1,5 +1,5 @@
 import UIKit
-import ShortKit
+import ShortKitSDK
 
 /// A transparent UIView that conforms to `FeedOverlay` and bridges overlay
 /// lifecycle calls to JS events via `ShortKitBridge`.
@@ -20,6 +20,11 @@ import ShortKit
     /// events that don't receive the item as a parameter.
     private var currentItem: ContentItem?
 
+    /// Deferred configure emission — cancelled if `activatePlayback()` fires
+    /// on the same run-loop iteration (meaning this was a handleSwipe
+    /// re-configure of the active cell, not a prefetch for the next cell).
+    private var pendingConfigureWorkItem: DispatchWorkItem?
+
     // MARK: - Init
 
     override init(frame: CGRect) {
@@ -66,7 +71,19 @@ import ShortKit
 
     public func configure(with item: ContentItem) {
         currentItem = item
-        bridge?.emitOverlayEvent("onOverlayConfigure", item: item)
+
+        // Defer the configure event by one run-loop tick. If activatePlayback()
+        // fires before then (handleSwipe sequence: configure → reset → activate),
+        // the event is cancelled — preventing nextItem from being overwritten
+        // with the current cell's data.
+        pendingConfigureWorkItem?.cancel()
+        let workItem = DispatchWorkItem { [weak self] in
+            guard let self, let item = self.currentItem else { return }
+            self.bridge?.emitOverlayEvent("onOverlayConfigure", item: item)
+            self.pendingConfigureWorkItem = nil
+        }
+        pendingConfigureWorkItem = workItem
+        DispatchQueue.main.async(execute: workItem)
     }
 
     public func resetPlaybackProgress() {
@@ -75,6 +92,11 @@ import ShortKit
     }
 
     public func activatePlayback() {
+        // Cancel the pending configure — it was for the current cell (part of
+        // handleSwipe), not a prefetch for the next cell.
+        pendingConfigureWorkItem?.cancel()
+        pendingConfigureWorkItem = nil
+
         guard let item = currentItem else { return }
         bridge?.emitOverlayEvent("onOverlayActivate", item: item)
     }