@shortkitsdk/react-native 0.2.4 → 0.2.6

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

@@ -8,7 +8,7 @@ import com.facebook.react.modules.core.DeviceEventManagerModule
 import com.shortkit.CarouselImage
 import com.shortkit.ContentItem
 import com.shortkit.ContentSignal
-import com.shortkit.CustomFeedItem
+import com.shortkit.FeedInput
 import com.shortkit.ImageCarouselItem
 import com.shortkit.FeedConfig
 import com.shortkit.FeedHeight
@@ -95,7 +95,6 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
     override fun initialize(
         apiKey: String,
         config: String,
-        embedId: String?,
         clientAppName: String?,
         clientAppVersion: String?,
         customDimensions: String?
@@ -112,7 +111,6 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
             context = context,
             apiKey = apiKey,
             config = feedConfig,
-            embedId = embedId,
             userId = null,
             adProvider = null,
             clientAppName = clientAppName,
@@ -124,11 +122,11 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
 
         // Replay any feed items that arrived before initialization
         pendingFeedItems?.let { json ->
-            parseCustomFeedItems(json)?.let { sdk.setFeedItems(it) }
+            parseFeedInputs(json)?.let { sdk.setFeedItems(it) }
             pendingFeedItems = null
         }
         pendingAppendItems?.let { json ->
-            parseCustomFeedItems(json)?.let { sdk.appendFeedItems(it) }
+            parseFeedInputs(json)?.let { sdk.appendFeedItems(it) }
             pendingAppendItems = null
         }
 
@@ -247,7 +245,7 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
     override fun setFeedItems(items: String) {
         val sdk = shortKit
         if (sdk != null) {
-            val parsed = parseCustomFeedItems(items) ?: return
+            val parsed = parseFeedInputs(items) ?: return
             sdk.setFeedItems(parsed)
         } else {
             pendingFeedItems = items
@@ -258,7 +256,7 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
     override fun appendFeedItems(items: String) {
         val sdk = shortKit
         if (sdk != null) {
-            val parsed = parseCustomFeedItems(items) ?: return
+            val parsed = parseFeedInputs(items) ?: return
             sdk.appendFeedItems(parsed)
         } else {
             pendingAppendItems = items
@@ -286,6 +284,46 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
         }
     }
 
+    // -----------------------------------------------------------------------
+    // Storyboard / Seek Thumbnails
+    // -----------------------------------------------------------------------
+
+    @ReactMethod
+    override fun prefetchStoryboard(playbackId: String) {
+        shortKit?.player?.prefetchStoryboard(playbackId)
+    }
+
+    @ReactMethod
+    override fun getStoryboardData(playbackId: String, promise: com.facebook.react.bridge.Promise) {
+        val player = shortKit?.player
+        if (player == null) {
+            promise.resolve(null)
+            return
+        }
+        // Try cached data first
+        val json = player.getStoryboardData(playbackId)
+        if (json != null) {
+            promise.resolve(json)
+            return
+        }
+        // Trigger prefetch and retry after a short delay
+        player.prefetchStoryboard(playbackId)
+        scope?.launch {
+            // Wait for prefetch to complete (poll with timeout)
+            var retries = 0
+            while (retries < 30) { // 3 seconds max
+                kotlinx.coroutines.delay(100)
+                val data = player.getStoryboardData(playbackId)
+                if (data != null) {
+                    promise.resolve(data)
+                    return@launch
+                }
+                retries++
+            }
+            promise.resolve(null)
+        }
+    }
+
     // -----------------------------------------------------------------------
     // Overlay lifecycle events (called by Fabric view)
     // -----------------------------------------------------------------------
@@ -774,21 +812,21 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
         }
     }
 
-    private fun parseCustomFeedItems(json: String): List<CustomFeedItem>? {
+    private fun parseFeedInputs(json: String): List<FeedInput>? {
         return try {
             val arr = JSONArray(json)
-            val result = mutableListOf<CustomFeedItem>()
+            val result = mutableListOf<FeedInput>()
             for (i in 0 until arr.length()) {
                 val obj = arr.getJSONObject(i)
                 when (obj.optString("type")) {
                     "video" -> {
                         val playbackId = obj.optString("playbackId", null) ?: continue
-                        result.add(CustomFeedItem.Video(playbackId))
+                        result.add(FeedInput.Video(playbackId))
                     }
                     "imageCarousel" -> {
                         val itemObj = obj.optJSONObject("item") ?: continue
                         val carouselItem = parseImageCarouselItem(itemObj) ?: continue
-                        result.add(CustomFeedItem.ImageCarousel(carouselItem))
+                        result.add(FeedInput.ImageCarousel(carouselItem))
                     }
                 }
             }

package/ios/ShortKitBridge.swift

@@ -23,7 +23,6 @@ import ShortKitSDK
     @objc public init(
         apiKey: String,
         config configJSON: String,
-        embedId: String?,
         clientAppName: String?,
         clientAppVersion: String?,
         customDimensions customDimensionsJSON: String?,
@@ -38,7 +37,6 @@ import ShortKitSDK
         let sdk = ShortKit(
             apiKey: apiKey,
             config: feedConfig,
-            embedId: embedId,
             clientAppName: clientAppName,
             clientAppVersion: clientAppVersion,
             customDimensions: dimensions
@@ -146,19 +144,75 @@ import ShortKitSDK
     // MARK: - Custom Feed
 
     @objc public func setFeedItems(_ json: String) {
-        guard let items = Self.parseCustomFeedItems(json) else { return }
+        guard let items = Self.parseFeedInputs(json) else { return }
         Task { @MainActor in
             self.shortKit?.setFeedItems(items)
         }
     }
 
     @objc public func appendFeedItems(_ json: String) {
-        guard let items = Self.parseCustomFeedItems(json) else { return }
+        guard let items = Self.parseFeedInputs(json) else { return }
         Task { @MainActor in
             self.shortKit?.appendFeedItems(items)
         }
     }
 
+    // MARK: - Storyboard / Seek Thumbnails
+
+    @objc public func prefetchStoryboard(_ playbackId: String) {
+        Task {
+            _ = await StoryboardProvider.shared.fetch(playbackId: playbackId)
+        }
+    }
+
+    @objc public func getStoryboardData(_ playbackId: String, completion: @escaping (String?) -> Void) {
+        Task {
+            // Try cache first, otherwise fetch
+            let storyboard: CachedStoryboard?
+            if let cached = StoryboardProvider.shared.cached(for: playbackId) {
+                storyboard = cached
+            } else {
+                storyboard = await StoryboardProvider.shared.fetch(playbackId: playbackId)
+            }
+            guard let meta = storyboard?.metadata else {
+                completion(nil)
+                return
+            }
+            // Compute sprite sheet dimensions from tile positions
+            var maxX = 0, maxY = 0
+            for tile in meta.tiles {
+                if tile.x > maxX { maxX = tile.x }
+                if tile.y > maxY { maxY = tile.y }
+            }
+            let imageWidth = maxX + meta.tileWidth
+            let imageHeight = maxY + meta.tileHeight
+            // Build JSON matching the shape the JS side expects
+            var tilesArr: [[String: Any]] = []
+            for tile in meta.tiles {
+                tilesArr.append(["start": tile.start, "x": tile.x, "y": tile.y])
+            }
+            let result: [String: Any] = [
+                "url": meta.url,
+                "tileWidth": meta.tileWidth,
+                "tileHeight": meta.tileHeight,
+                "duration": meta.duration,
+                "imageWidth": imageWidth,
+                "imageHeight": imageHeight,
+                "tiles": tilesArr,
+            ]
+            if let data = try? JSONSerialization.data(withJSONObject: result),
+               let json = String(data: data, encoding: .utf8) {
+                completion(json)
+            } else {
+                completion(nil)
+            }
+        }
+    }
+
+    @objc public func notifyOverlayReady() {
+        NotificationCenter.default.post(name: .shortKitOverlayReady, object: nil)
+    }
+
     @objc public func fetchContent(_ limit: Int, completion: @escaping (String) -> Void) {
         Task {
             do {
@@ -288,6 +342,24 @@ import ShortKitSDK
             }
             .store(in: &cancellables)
 
+        // Feed scroll phase
+        player.feedScrollPhase
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] phase in
+                switch phase {
+                case .dragging(let fromId):
+                    self?.emit("onFeedScrollPhase", body: [
+                        "phase": "dragging",
+                        "fromId": fromId
+                    ])
+                case .settled:
+                    self?.emit("onFeedScrollPhase", body: [
+                        "phase": "settled"
+                    ])
+                }
+            }
+            .store(in: &cancellables)
+
         // Format change
         player.formatChange
             .receive(on: DispatchQueue.main)
@@ -565,14 +637,14 @@ import ShortKitSDK
         }
     }
 
-    /// Parse a JSON string of CustomFeedItem[] from the JS bridge.
-    private static func parseCustomFeedItems(_ json: String) -> [CustomFeedItem]? {
+    /// Parse a JSON string of FeedInput[] from the JS bridge.
+    private static func parseFeedInputs(_ json: String) -> [FeedInput]? {
         guard let data = json.data(using: .utf8),
               let arr = try? JSONSerialization.jsonObject(with: data) as? [[String: Any]] else {
             return nil
         }
 
-        var result: [CustomFeedItem] = []
+        var result: [FeedInput] = []
         for obj in arr {
             guard let type = obj["type"] as? String else { continue }
             switch type {
@@ -614,3 +686,9 @@ extension ShortKitBridge: ShortKitDelegate {
         ])
     }
 }
+
+// MARK: - Notification Names
+
+extension Notification.Name {
+    static let shortKitOverlayReady = Notification.Name("ShortKitOverlayReady")
+}

package/ios/ShortKitCarouselOverlayBridge.swift

@@ -1,54 +1,219 @@
 import UIKit
 import ShortKitSDK
 
-/// A transparent UIView that conforms to `CarouselOverlay` and bridges
-/// carousel overlay lifecycle calls to JS events via `ShortKitBridge`.
+/// A UIView that conforms to `CarouselOverlay` and renders carousel images
+/// natively inside the feed cell using a horizontal paging UIScrollView.
 ///
-/// 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.
+/// This matches the Swift SDK's `DefaultCarouselView` architecture: images
+/// are rendered INSIDE the cell (part of the feed scroll view), so vertical
+/// feed scrolling and horizontal image swiping work naturally through UIKit's
+/// gesture conflict resolution.
+///
+/// The RN side only renders metadata (title, description, page dots, buttons)
+/// on top via the `CarouselOverlayManager`.
 @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: - CarouselOverlay
+
+    public var cachedImage: ((String) -> UIImage?)?
+
     // 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?
+    private var loadTasks: [Task<Void, Never>] = []
+    private var currentPage: Int = 0
+    private var autoScrollTimer: Timer?
+
+    // MARK: - UI
+
+    private let scrollView = UIScrollView()
+    private let pageControl = UIPageControl()
+    private var imageViews: [UIImageView] = []
 
     // MARK: - Init
 
     override init(frame: CGRect) {
         super.init(frame: frame)
-        backgroundColor = .clear
+        backgroundColor = .black
         isUserInteractionEnabled = true
+        setupScrollView()
+        setupPageControl()
     }
 
     required init?(coder: NSCoder) {
         fatalError("init(coder:) is not supported")
     }
 
+    private func setupScrollView() {
+        scrollView.isPagingEnabled = true
+        scrollView.showsHorizontalScrollIndicator = false
+        scrollView.bounces = false
+        scrollView.delegate = self
+        scrollView.translatesAutoresizingMaskIntoConstraints = false
+        addSubview(scrollView)
+        NSLayoutConstraint.activate([
+            scrollView.topAnchor.constraint(equalTo: topAnchor),
+            scrollView.leadingAnchor.constraint(equalTo: leadingAnchor),
+            scrollView.trailingAnchor.constraint(equalTo: trailingAnchor),
+            scrollView.bottomAnchor.constraint(equalTo: bottomAnchor),
+        ])
+    }
+
+    private func setupPageControl() {
+        pageControl.isUserInteractionEnabled = false
+        pageControl.translatesAutoresizingMaskIntoConstraints = false
+        addSubview(pageControl)
+        NSLayoutConstraint.activate([
+            pageControl.centerXAnchor.constraint(equalTo: centerXAnchor),
+            pageControl.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -40),
+        ])
+    }
+
+    // MARK: - Layout
+
+    public override func layoutSubviews() {
+        super.layoutSubviews()
+        let w = bounds.width
+        let h = bounds.height
+        guard w > 0, h > 0 else { return }
+        scrollView.contentSize = CGSize(width: w * CGFloat(imageViews.count), height: h)
+        for (i, iv) in imageViews.enumerated() {
+            iv.frame = CGRect(x: w * CGFloat(i), y: 0, width: w, height: h)
+        }
+    }
+
     // MARK: - CarouselOverlay
 
     public func configure(with item: ImageCarouselItem) {
+        NSLog("[CarouselBridge] configure id=\(item.id) images=\(item.images.count)")
         currentItem = item
+
+        // Cancel previous loads & auto-scroll
+        cancelLoads()
+        autoScrollTimer?.invalidate()
+        autoScrollTimer = nil
+
+        // Remove old image views
+        for iv in imageViews { iv.removeFromSuperview() }
+        imageViews.removeAll()
+
+        // Create image views and load images
+        for image in item.images {
+            let iv = UIImageView()
+            iv.contentMode = .scaleAspectFill
+            iv.clipsToBounds = true
+            iv.backgroundColor = .black
+            scrollView.addSubview(iv)
+            imageViews.append(iv)
+
+            if let cached = cachedImage?(image.url) {
+                iv.image = cached
+            } else {
+                let task = Task { [weak iv] in
+                    guard let url = URL(string: image.url),
+                          let (data, _) = try? await URLSession.shared.data(from: url),
+                          !Task.isCancelled,
+                          let uiImage = UIImage(data: data) else { return }
+                    await MainActor.run { iv?.image = uiImage }
+                }
+                loadTasks.append(task)
+            }
+        }
+
+        // Reset scroll position and page
+        currentPage = 0
+        scrollView.contentOffset = .zero
+        setNeedsLayout()
+
+        // Update page control
+        pageControl.numberOfPages = item.images.count
+        pageControl.currentPage = 0
+        pageControl.isHidden = item.images.count <= 1
+
+        // Start auto-scroll if configured
+        let interval = item.autoScrollInterval ?? 0
+        if interval > 0 && item.images.count > 1 {
+            startAutoScroll(interval: interval)
+        }
+
+        // Emit configure to JS so the metadata overlay updates
         bridge?.emitCarouselOverlayEvent("onCarouselOverlayConfigure", item: item)
     }
 
     public func resetState() {
+        NSLog("[CarouselBridge] resetState")
+        cancelLoads()
+        autoScrollTimer?.invalidate()
+        autoScrollTimer = nil
+        for iv in imageViews { iv.removeFromSuperview() }
+        imageViews.removeAll()
+        scrollView.contentOffset = .zero
+        currentPage = 0
+        currentItem = nil
         bridge?.emitCarouselOverlayEvent("onCarouselOverlayReset", body: [:])
     }
 
     public func fadeOutForTransition() {
-        bridge?.emitCarouselOverlayEvent("onCarouselOverlayFadeOut", body: [:])
+        // No-op — native images are inside the cell, transitions are handled
+        // by the feed's collection view.
     }
 
     public func restoreFromTransition() {
-        bridge?.emitCarouselOverlayEvent("onCarouselOverlayRestore", body: [:])
+        // No-op
+    }
+
+    // MARK: - Auto-Scroll
+
+    private func startAutoScroll(interval: Double) {
+        autoScrollTimer = Timer.scheduledTimer(withTimeInterval: interval, repeats: true) { [weak self] _ in
+            guard let self, !self.imageViews.isEmpty else { return }
+            let nextPage = (self.currentPage + 1) % self.imageViews.count
+            let offset = CGFloat(nextPage) * self.scrollView.bounds.width
+            self.scrollView.setContentOffset(CGPoint(x: offset, y: 0), animated: true)
+            self.currentPage = nextPage
+            self.pageControl.currentPage = nextPage
+        }
+    }
+
+    // MARK: - Helpers
+
+    private func cancelLoads() {
+        for task in loadTasks { task.cancel() }
+        loadTasks.removeAll()
+    }
+
+}
+
+// MARK: - UIScrollViewDelegate
+
+extension ShortKitCarouselOverlayBridge: UIScrollViewDelegate {
+    public func scrollViewDidEndDecelerating(_ scrollView: UIScrollView) {
+        guard scrollView.bounds.width > 0 else { return }
+        let page = Int(round(scrollView.contentOffset.x / scrollView.bounds.width))
+        currentPage = page
+        pageControl.currentPage = page
+
+        // Restart auto-scroll after user interaction
+        if let interval = currentItem?.autoScrollInterval, interval > 0, imageViews.count > 1 {
+            autoScrollTimer?.invalidate()
+            startAutoScroll(interval: interval)
+        }
+    }
+
+    public func scrollViewDidEndScrollingAnimation(_ scrollView: UIScrollView) {
+        guard scrollView.bounds.width > 0 else { return }
+        let page = Int(round(scrollView.contentOffset.x / scrollView.bounds.width))
+        currentPage = page
+        pageControl.currentPage = page
+    }
+
+    public func scrollViewWillBeginDragging(_ scrollView: UIScrollView) {
+        // Pause auto-scroll during user interaction
+        autoScrollTimer?.invalidate()
+        autoScrollTimer = nil
     }
 }

package/ios/ShortKitFeedView.swift

@@ -37,8 +37,12 @@ import ShortKitSDK
     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.
-    private var pageUpdateWorkItem: DispatchWorkItem?
+    /// 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
 
@@ -89,11 +93,17 @@ import ShortKitSDK
         feedVC.didMove(toParent: parentVC)
 
         setupScrollTracking(feedVC)
+        setupOverlayReadyObserver()
     }
 
     private func removeFeedViewController() {
-        pageUpdateWorkItem?.cancel()
-        pageUpdateWorkItem = nil
+        pendingSwap = nil
+        swapFallbackWorkItem?.cancel()
+        swapFallbackWorkItem = nil
+        if let observer = overlayReadyObserver {
+            NotificationCenter.default.removeObserver(observer)
+            overlayReadyObserver = nil
+        }
         scrollObservation?.invalidate()
         scrollObservation = nil
         currentOverlayView?.transform = .identity
@@ -132,44 +142,45 @@ import ShortKitSDK
 
         let offset = scrollView.contentOffset.y
 
-        // Detect page change, but DEFER updating currentPage.
+        // 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 (React hasn't processed OVERLAY_ACTIVATE
-        // yet). If we update currentPage immediately, delta snaps to 0 and
-        // overlay-current becomes visible with stale data.
+        // shows the OLD page's metadata. If we update currentPage immediately,
+        // delta snaps to 0 and overlay-current becomes visible with stale data.
         //
-        // By deferring ~80ms, overlay-next (which already shows the correct
-        // data via NextOverlayProvider) stays visible at y=0 while React
-        // processes the state update. After the delay, overlay-current has
-        // been re-rendered with correct data and takes over seamlessly.
+        // 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 && pageUpdateWorkItem == nil {
+            if nearestPage != currentPage && pendingSwap == nil {
                 let targetPage = nearestPage
-                let workItem = DispatchWorkItem { [weak self] in
+                pendingSwap = { [weak self] in
                     guard let self else { return }
                     self.currentPage = targetPage
-                    self.pageUpdateWorkItem = nil
+                    self.pendingSwap = nil
+                    self.swapFallbackWorkItem?.cancel()
+                    self.swapFallbackWorkItem = nil
                     // Reapply overlay transforms now that currentPage is updated.
-                    // Without this, overlay-next (static NextOverlayProvider state)
-                    // stays visible at y=0 while overlay-current (live state) stays
-                    // hidden — no scroll event fires to trigger handleScrollOffset.
                     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)
+                // 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)
             }
-        } else if let workItem = pageUpdateWorkItem {
-            // User is scrolling again — apply pending update immediately
+        } else if pendingSwap != nil {
+            // User is scrolling again — execute pending swap immediately
             // so transforms stay aligned for the new gesture.
-            workItem.cancel()
-            pageUpdateWorkItem = nil
-            currentPage = nearestPage
+            pendingSwap?()
         }
 
         let delta = offset - CGFloat(currentPage) * cellHeight
@@ -202,6 +213,18 @@ import ShortKitSDK
         }
     }
 
+    // MARK: - Overlay Ready Handshake
+
+    private func setupOverlayReadyObserver() {
+        overlayReadyObserver = NotificationCenter.default.addObserver(
+            forName: .shortKitOverlayReady,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            self?.pendingSwap?()
+        }
+    }
+
     /// Find the sibling RN overlay views by nativeID.
     ///
     /// In Fabric interop, `ShortKitFeedView` (a Paper-style `RCTViewManager`