@shortkitsdk/react-native 0.2.1 → 0.2.2

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

@@ -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 ShortKit
+
+/// 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

@@ -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

@@ -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)
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shortkitsdk/react-native",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "ShortKit React Native SDK — short-form video feed",
   "react-native": "src/index",
   "source": "src/index",

package/src/CarouselOverlayManager.tsx

@@ -0,0 +1,71 @@
+import React, { useContext, useMemo } from 'react';
+import { View, StyleSheet } from 'react-native';
+import type { CarouselOverlayConfig } from './types';
+import { ShortKitContext } from './ShortKitContext';
+import type { ShortKitContextValue } from './ShortKitContext';
+
+interface CarouselOverlayManagerProps {
+  carouselOverlay: CarouselOverlayConfig;
+}
+
+/**
+ * Internal component that renders TWO instances of the developer's custom
+ * carousel overlay component — one for the current cell and one for the next.
+ *
+ * Works identically to `OverlayManager` but for image carousel cells.
+ * The native side finds these views by their `nativeID` and applies
+ * scroll-tracking transforms so each overlay moves with its respective
+ * carousel cell during swipe transitions.
+ */
+export function CarouselOverlayManager({ carouselOverlay }: CarouselOverlayManagerProps) {
+  if (
+    carouselOverlay === 'none' ||
+    typeof carouselOverlay === 'string' ||
+    carouselOverlay.type !== 'custom' ||
+    !('component' in carouselOverlay)
+  ) {
+    return null;
+  }
+
+  const CarouselComponent = carouselOverlay.component;
+
+  return (
+    <>
+      <View style={StyleSheet.absoluteFill} nativeID="carousel-overlay-current" pointerEvents="box-none">
+        <CarouselComponent />
+      </View>
+      <View style={StyleSheet.absoluteFill} nativeID="carousel-overlay-next" pointerEvents="box-none">
+        <NextCarouselOverlayProvider>
+          <CarouselComponent />
+        </NextCarouselOverlayProvider>
+      </View>
+    </>
+  );
+}
+
+/**
+ * Wraps children with a modified ShortKitContext where `currentCarouselItem`
+ * is set to the provider's `nextCarouselItem`.
+ */
+function NextCarouselOverlayProvider({ children }: { children: React.ReactNode }) {
+  const context = useContext(ShortKitContext);
+
+  const nextValue: ShortKitContextValue | null = useMemo(() => {
+    if (!context) return null;
+
+    return {
+      ...context,
+      currentCarouselItem: context.nextCarouselItem,
+      isCarouselActive: context.nextCarouselItem != null,
+      isCarouselTransitioning: false,
+    };
+  }, [context]);
+
+  if (!nextValue) return <>{children}</>;
+
+  return (
+    <ShortKitContext.Provider value={nextValue}>
+      {children}
+    </ShortKitContext.Provider>
+  );
+}

package/src/ShortKitContext.ts

@@ -1,12 +1,14 @@
 import { createContext } from 'react';
 import type {
   ContentItem,
+  ImageCarouselItem,
   CustomFeedItem,
   PlayerTime,
   PlayerState,
   CaptionTrack,
   ContentSignal,
   OverlayConfig,
+  CarouselOverlayConfig,
 } from './types';
 
 export interface ShortKitContextValue {
@@ -48,9 +50,20 @@ export interface ShortKitContextValue {
   appendFeedItems: (items: CustomFeedItem[]) => void;
   fetchContent: (limit?: number) => Promise<ContentItem[]>;
 
+  // Carousel overlay state
+  currentCarouselItem: ImageCarouselItem | null;
+  nextCarouselItem: ImageCarouselItem | null;
+  isCarouselActive: boolean;
+  isCarouselTransitioning: boolean;
+
+  // Active cell type — used by overlay managers to show/hide
+  activeCellType: 'video' | 'carousel' | null;
+
   // Internal — used by ShortKitFeed to render custom overlays
   /** @internal */
   _overlayConfig: OverlayConfig;
+  /** @internal */
+  _carouselOverlayConfig: CarouselOverlayConfig;
 }
 
 export const ShortKitContext = createContext<ShortKitContextValue | null>(null);

package/src/ShortKitFeed.tsx

@@ -4,6 +4,7 @@ import type { ShortKitFeedProps } from './types';
 import ShortKitFeedView from './specs/ShortKitFeedViewNativeComponent';
 import NativeShortKitModule from './specs/NativeShortKitModule';
 import { OverlayManager } from './OverlayManager';
+import { CarouselOverlayManager } from './CarouselOverlayManager';
 import { ShortKitContext } from './ShortKitContext';
 import { deserializeContentItem } from './serialization';
 
@@ -38,6 +39,7 @@ export function ShortKitFeed(props: ShortKitFeedProps) {
   }
 
   const overlayConfig = context._overlayConfig;
+  const carouselOverlayConfig = context._carouselOverlayConfig;
 
   // ---------------------------------------------------------------------------
   // Subscribe to feed-level events and forward to callback props
@@ -143,6 +145,7 @@ export function ShortKitFeed(props: ShortKitFeedProps) {
         config="{}"
       />
       <OverlayManager overlay={overlayConfig} />
+      <CarouselOverlayManager carouselOverlay={carouselOverlayConfig} />
     </View>
   );
 }

package/src/ShortKitProvider.tsx

@@ -6,6 +6,7 @@ import type { ShortKitContextValue } from './ShortKitContext';
 import type {
   ShortKitProviderProps,
   ContentItem,
+  ImageCarouselItem,
   CustomFeedItem,
   PlayerTime,
   PlayerState,
@@ -41,6 +42,11 @@ interface State {
   isTransitioning: boolean;
   lastOverlayTap: number;
   lastOverlayDoubleTap: { x: number; y: number; id: number } | null;
+  currentCarouselItem: ImageCarouselItem | null;
+  nextCarouselItem: ImageCarouselItem | null;
+  isCarouselActive: boolean;
+  isCarouselTransitioning: boolean;
+  activeCellType: 'video' | 'carousel' | null;
 }
 
 const initialState: State = {
@@ -59,6 +65,11 @@ const initialState: State = {
   isTransitioning: false,
   lastOverlayTap: 0,
   lastOverlayDoubleTap: null,
+  currentCarouselItem: null,
+  nextCarouselItem: null,
+  isCarouselActive: false,
+  isCarouselTransitioning: false,
+  activeCellType: null,
 };
 
 type Action =
@@ -78,7 +89,13 @@ type Action =
   | { type: 'OVERLAY_FADE_OUT' }
   | { type: 'OVERLAY_RESTORE' }
   | { type: 'OVERLAY_TAP' }
-  | { type: 'OVERLAY_DOUBLE_TAP'; payload: { x: number; y: number } };
+  | { type: 'OVERLAY_DOUBLE_TAP'; payload: { x: number; y: number } }
+  | { type: 'ACTIVE_CELL_TYPE'; payload: 'video' | 'carousel' }
+  | { type: 'CAROUSEL_OVERLAY_CONFIGURE'; payload: ImageCarouselItem }
+  | { type: 'CAROUSEL_OVERLAY_ACTIVATE'; payload: ImageCarouselItem }
+  | { type: 'CAROUSEL_OVERLAY_RESET' }
+  | { type: 'CAROUSEL_OVERLAY_FADE_OUT' }
+  | { type: 'CAROUSEL_OVERLAY_RESTORE' };
 
 function reducer(state: State, action: Action): State {
   switch (action.type) {
@@ -91,10 +108,13 @@ function reducer(state: State, action: Action): State {
         action.payload === 'paused' ||
         action.payload === 'buffering' ||
         action.payload === 'seeking';
+      const becameActive = !state.isActive && isPlaybackActive;
       return {
         ...state,
         playerState: action.payload,
         isActive: state.isActive || isPlaybackActive,
+        // First playback means a video cell is active (initial load)
+        activeCellType: becameActive ? 'video' : state.activeCellType,
       };
     }
     case 'CURRENT_ITEM':
@@ -118,7 +138,20 @@ function reducer(state: State, action: Action): State {
     case 'OVERLAY_CONFIGURE':
       return { ...state, nextItem: action.payload };
     case 'OVERLAY_ACTIVATE':
-      return { ...state, currentItem: action.payload, isActive: true };
+      // Reset time/cue/transition state to prevent stale playback data from
+      // the previous cell flashing on the new cell's overlay.
+      // Note: nextItem is NOT cleared here — the native-side deferred-configure
+      // (ShortKitOverlayBridge) already prevents handleSwipe from polluting it.
+      // Clearing it would cause overlay-next to unmount its content ~80ms before
+      // the page settle swaps overlays, creating a visible dim-layer gap.
+      return {
+        ...state,
+        currentItem: action.payload,
+        isActive: true,
+        time: { current: 0, duration: action.payload.duration, buffered: 0 },
+        activeCue: null,
+        isTransitioning: false,
+      };
     case 'OVERLAY_RESET':
       // Don't set isActive = false — the overlay stays mounted during
       // transitions. In the native SDK each cell has its own overlay
@@ -140,6 +173,18 @@ function reducer(state: State, action: Action): State {
           id: (state.lastOverlayDoubleTap?.id ?? 0) + 1,
         },
       };
+    case 'ACTIVE_CELL_TYPE':
+      return { ...state, activeCellType: action.payload };
+    case 'CAROUSEL_OVERLAY_CONFIGURE':
+      return { ...state, nextCarouselItem: action.payload };
+    case 'CAROUSEL_OVERLAY_ACTIVATE':
+      return { ...state, currentCarouselItem: action.payload, isCarouselActive: true };
+    case 'CAROUSEL_OVERLAY_RESET':
+      return { ...state, isCarouselTransitioning: false };
+    case 'CAROUSEL_OVERLAY_FADE_OUT':
+      return { ...state, isCarouselTransitioning: true };
+    case 'CAROUSEL_OVERLAY_RESTORE':
+      return { ...state, isCarouselTransitioning: false };
     default:
       return state;
   }
@@ -397,6 +442,61 @@ export function ShortKitProvider({
       }),
     );
 
+    // Feed transition — track active cell type
+    subscriptions.push(
+      NativeShortKitModule.onFeedTransition((event) => {
+        if (event.phase === 'ended') {
+          // toItem is null when the destination cell is non-video (carousel, survey, ad)
+          const isVideo = event.toItem != null;
+          dispatch({
+            type: 'ACTIVE_CELL_TYPE',
+            payload: isVideo ? 'video' : 'carousel',
+          });
+        }
+      }),
+    );
+
+    // Carousel overlay lifecycle events
+    subscriptions.push(
+      NativeShortKitModule.onCarouselOverlayConfigure((event) => {
+        try {
+          const item = JSON.parse(event.item) as ImageCarouselItem;
+          dispatch({ type: 'CAROUSEL_OVERLAY_CONFIGURE', payload: item });
+        } catch {
+          // Ignore malformed JSON
+        }
+      }),
+    );
+
+    subscriptions.push(
+      NativeShortKitModule.onCarouselOverlayActivate((event) => {
+        try {
+          const item = JSON.parse(event.item) as ImageCarouselItem;
+          dispatch({ type: 'CAROUSEL_OVERLAY_ACTIVATE', payload: item });
+        } catch {
+          // Ignore malformed JSON
+        }
+      }),
+    );
+
+    subscriptions.push(
+      NativeShortKitModule.onCarouselOverlayReset((_event) => {
+        dispatch({ type: 'CAROUSEL_OVERLAY_RESET' });
+      }),
+    );
+
+    subscriptions.push(
+      NativeShortKitModule.onCarouselOverlayFadeOut((_event) => {
+        dispatch({ type: 'CAROUSEL_OVERLAY_FADE_OUT' });
+      }),
+    );
+
+    subscriptions.push(
+      NativeShortKitModule.onCarouselOverlayRestore((_event) => {
+        dispatch({ type: 'CAROUSEL_OVERLAY_RESTORE' });
+      }),
+    );
+
     // Note: Feed-level callback events (onDidLoop, onFeedTransition,
     // onShareTapped, etc.) are subscribed by the ShortKitFeed component
     // (Task 11), not here. The provider only manages state-driving events.
@@ -526,8 +626,18 @@ export function ShortKitProvider({
       appendFeedItems: appendFeedItemsCmd,
       fetchContent: fetchContentCmd,
 
+      // Active cell type
+      activeCellType: state.activeCellType,
+
+      // Carousel overlay state
+      currentCarouselItem: state.currentCarouselItem,
+      nextCarouselItem: state.nextCarouselItem,
+      isCarouselActive: state.isCarouselActive,
+      isCarouselTransitioning: state.isCarouselTransitioning,
+
       // Internal — consumed by ShortKitFeed to pass to OverlayManager
       _overlayConfig: config.overlay ?? 'none',
+      _carouselOverlayConfig: config.carouselOverlay ?? 'none',
     }),
     [
       state.playerState,
@@ -545,6 +655,11 @@ export function ShortKitProvider({
       state.isTransitioning,
       state.lastOverlayTap,
       state.lastOverlayDoubleTap,
+      state.activeCellType,
+      state.currentCarouselItem,
+      state.nextCarouselItem,
+      state.isCarouselActive,
+      state.isCarouselTransitioning,
       play,
       pause,
       seek,
@@ -563,6 +678,7 @@ export function ShortKitProvider({
       appendFeedItemsCmd,
       fetchContentCmd,
       config.overlay,
+      config.carouselOverlay,
     ],
   );
 

package/src/index.ts

@@ -4,12 +4,13 @@ export { ShortKitPlayer } from './ShortKitPlayer';
 export { ShortKitWidget } from './ShortKitWidget';
 export { useShortKitPlayer } from './useShortKitPlayer';
 export { useShortKit } from './useShortKit';
+export { useShortKitCarousel } from './useShortKitCarousel';
 export type {
   FeedConfig,
   FeedHeight,
   FeedSource,
   OverlayConfig,
-  CarouselMode,
+  CarouselOverlayConfig,
   SurveyMode,
 
   PlayerConfig,
@@ -36,3 +37,4 @@ export type {
   ShortKitWidgetProps,
   ShortKitPlayerState,
 } from './types';
+export type { ShortKitCarouselState } from './useShortKitCarousel';

package/src/serialization.ts

@@ -13,7 +13,7 @@ import type {
 export interface SerializedFeedConfig {
   feedHeight: string;
   overlay: string;
-  carouselMode: string;
+  carouselOverlay: string;
   surveyMode: string;
   muteOnStart: boolean;
   feedSource: string;
@@ -37,7 +37,11 @@ export function serializeFeedConfig(config: FeedConfig): SerializedFeedConfig {
   return {
     feedHeight: JSON.stringify(config.feedHeight ?? { type: 'fullscreen' }),
     overlay,
-    carouselMode: JSON.stringify(config.carouselMode ?? 'none'),
+    carouselOverlay: (() => {
+      const raw = config.carouselOverlay ?? 'none';
+      if (typeof raw === 'string') return JSON.stringify(raw);
+      return JSON.stringify({ type: 'custom' });
+    })(),
     surveyMode: JSON.stringify(config.surveyMode ?? 'none'),
     muteOnStart: config.muteOnStart ?? true,
     feedSource: config.feedSource ?? 'algorithmic',

package/src/specs/NativeShortKitModule.ts

@@ -122,6 +122,20 @@ type ContentTappedEvent = Readonly<{
   index: Int32;
 }>;
 
+type CarouselOverlayConfigureEvent = Readonly<{
+  item: string; // JSON-serialized ImageCarouselItem
+}>;
+
+type CarouselOverlayActivateEvent = Readonly<{
+  item: string; // JSON-serialized ImageCarouselItem
+}>;
+
+type CarouselOverlayResetEvent = Readonly<{}>;
+
+type CarouselOverlayFadeOutEvent = Readonly<{}>;
+
+type CarouselOverlayRestoreEvent = Readonly<{}>;
+
 type OverlayTapEvent = Readonly<{}>;
 
 type OverlayDoubleTapEvent = Readonly<{
@@ -189,6 +203,11 @@ export interface Spec extends TurboModule {
   readonly onOverlayTap: EventEmitter<OverlayTapEvent>;
   readonly onOverlayDoubleTap: EventEmitter<OverlayDoubleTapEvent>;
   readonly onContentTapped: EventEmitter<ContentTappedEvent>;
+  readonly onCarouselOverlayConfigure: EventEmitter<CarouselOverlayConfigureEvent>;
+  readonly onCarouselOverlayActivate: EventEmitter<CarouselOverlayActivateEvent>;
+  readonly onCarouselOverlayReset: EventEmitter<CarouselOverlayResetEvent>;
+  readonly onCarouselOverlayFadeOut: EventEmitter<CarouselOverlayFadeOutEvent>;
+  readonly onCarouselOverlayRestore: EventEmitter<CarouselOverlayRestoreEvent>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>('ShortKitModule');

package/src/types.ts

@@ -7,7 +7,7 @@ export type FeedSource = 'algorithmic' | 'custom';
 export interface FeedConfig {
   feedHeight?: FeedHeight;
   overlay?: OverlayConfig;
-  carouselMode?: CarouselMode;
+  carouselOverlay?: CarouselOverlayConfig;
   surveyMode?: SurveyMode;
   muteOnStart?: boolean;
   feedSource?: FeedSource;
@@ -21,9 +21,9 @@ export type OverlayConfig =
   | 'none'
   | { type: 'custom'; component: React.ComponentType };
 
-export type CarouselMode =
+export type CarouselOverlayConfig =
   | 'none'
-  | { type: 'template'; name: 'default' };
+  | { type: 'custom'; component: React.ComponentType };
 
 export type SurveyMode =
   | 'none'
@@ -212,6 +212,7 @@ export interface ShortKitPlayerState {
   playerState: PlayerState;
   currentItem: ContentItem | null;
   nextItem: ContentItem | null;
+  activeCellType: 'video' | 'carousel' | null;
   time: PlayerTime;
   isMuted: boolean;
   playbackRate: number;

package/src/useShortKitCarousel.ts

@@ -0,0 +1,29 @@
+import { useContext } from 'react';
+import { ShortKitContext } from './ShortKitContext';
+import type { ImageCarouselItem } from './types';
+
+export interface ShortKitCarouselState {
+  currentCarouselItem: ImageCarouselItem | null;
+  isCarouselActive: boolean;
+  isCarouselTransitioning: boolean;
+}
+
+/**
+ * Hook to access carousel overlay state from the nearest ShortKitProvider.
+ *
+ * Use this inside a custom carousel overlay component to get the current
+ * `ImageCarouselItem` data (images, title, description, etc.).
+ *
+ * Must be used within a `<ShortKitProvider>`.
+ */
+export function useShortKitCarousel(): ShortKitCarouselState {
+  const context = useContext(ShortKitContext);
+  if (!context) {
+    throw new Error('useShortKitCarousel must be used within a ShortKitProvider');
+  }
+  return {
+    currentCarouselItem: context.currentCarouselItem,
+    isCarouselActive: context.isCarouselActive,
+    isCarouselTransitioning: context.isCarouselTransitioning,
+  };
+}

package/src/useShortKitPlayer.ts

@@ -16,12 +16,20 @@ export function useShortKitPlayer(): ShortKitPlayerState {
     throw new Error('useShortKitPlayer must be used within a ShortKitProvider');
   }
 
-  // Return only player-related state and commands (exclude SDK operations
-  // and internal fields)
+  // Return only player-related state and commands (exclude SDK operations,
+  // carousel state, and internal fields)
   const {
     setUserId: _setUserId,
     clearUserId: _clearUserId,
+    setFeedItems: _setFeedItems,
+    appendFeedItems: _appendFeedItems,
+    fetchContent: _fetchContent,
+    currentCarouselItem: _currentCarouselItem,
+    nextCarouselItem: _nextCarouselItem,
+    isCarouselActive: _isCarouselActive,
+    isCarouselTransitioning: _isCarouselTransitioning,
     _overlayConfig: _overlay,
+    _carouselOverlayConfig: _carouselOverlay,
     ...playerState
   } = context;