@shortkitsdk/react-native 0.2.12 → 0.2.15

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

@@ -17,6 +17,7 @@ import com.shortkit.sdk.model.FeedInput
 import com.shortkit.sdk.model.FeedScrollPhase
 import com.shortkit.sdk.model.FeedTransitionPhase
 import com.shortkit.sdk.model.ImageCarouselItem
+import com.shortkit.sdk.model.VideoCarouselItem
 import com.shortkit.sdk.model.JsonValue
 import com.shortkit.sdk.model.PlayerState
 import com.shortkit.sdk.config.AdOverlayMode
@@ -26,6 +27,8 @@ import com.shortkit.sdk.config.FeedHeight
 import com.shortkit.sdk.config.FeedSource
 import com.shortkit.sdk.config.ScrollAxis
 import com.shortkit.sdk.config.SurveyOverlayMode
+import com.shortkit.sdk.config.VideoCarouselOverlayMode
+import com.shortkit.sdk.feed.ShortKitRefreshState
 import com.shortkit.sdk.config.VideoOverlayMode
 import com.shortkit.sdk.feed.FeedPreload
 import com.shortkit.sdk.feed.ShortKitFeedFragment
@@ -152,16 +155,21 @@ class ShortKitBridge(
 
                 val carouselOverlayRaw = obj.optString("carouselOverlay", null)
                 val carouselOverlay = parseCarouselOverlay(carouselOverlayRaw, context)
+                val videoCarouselOverlayRaw = obj.optString("videoCarouselOverlay", null)
+                val videoCarouselOverlay = parseVideoCarouselOverlay(videoCarouselOverlayRaw, context)
                 val autoplay = obj.optBoolean("autoplay", true)
                 val filter = obj.optJSONObject("filter")?.let { parseFeedFilterToModel(it.toString()) }
 
                 val scrollAxisStr = obj.optString("scrollAxis", "vertical")
                 val scrollAxis = if (scrollAxisStr == "horizontal") ScrollAxis.Horizontal else ScrollAxis.Vertical
 
+                val pullToRefreshEnabled = obj.optBoolean("pullToRefreshEnabled", true)
+
                 FeedConfig(
                     feedHeight = feedHeight,
                     videoOverlay = videoOverlay,
                     carouselOverlay = carouselOverlay,
+                    videoCarouselOverlay = videoCarouselOverlay,
                     surveyOverlay = SurveyOverlayMode.None,
                     adOverlay = AdOverlayMode.None,
                     muteOnStart = muteOnStart,
@@ -169,6 +177,7 @@ class ShortKitBridge(
                     feedSource = feedSource,
                     filter = filter,
                     scrollAxis = scrollAxis,
+                    pullToRefreshEnabled = pullToRefreshEnabled,
                 )
             } catch (e: Exception) {
                 android.util.Log.e("SK:Bridge", "parseFeedConfig: EXCEPTION parsing config, returning default. json=${json.take(300)}", e)
@@ -273,6 +282,43 @@ class ShortKitBridge(
             }
         }
 
+        /**
+         * Parse a double-stringified video carousel overlay JSON.
+         * - `"\"none\""` -> None
+         * - `"{\"type\":\"custom\"}"` -> Custom with ReactVideoCarouselOverlayHost factory
+         */
+        private fun parseVideoCarouselOverlay(json: String?, context: android.content.Context?): VideoCarouselOverlayMode {
+            if (json.isNullOrEmpty()) return VideoCarouselOverlayMode.None
+            return try {
+                val parsed = json.trim()
+
+                if (parsed == "\"none\"" || parsed == "none") {
+                    return VideoCarouselOverlayMode.None
+                }
+
+                val inner = if (parsed.startsWith("\"") && parsed.endsWith("\"")) {
+                    JSONObject(parsed.substring(1, parsed.length - 1).replace("\\\"", "\""))
+                } else {
+                    JSONObject(parsed)
+                }
+
+                if (inner.optString("type") == "custom" && context != null) {
+                    val name = inner.optString("name", "Default")
+                    val ctx = context.applicationContext
+                    VideoCarouselOverlayMode.Custom {
+                        ReactVideoCarouselOverlayHost(ctx).apply {
+                            videoCarouselOverlayName = name
+                            prepareSurface()
+                        }
+                    }
+                } else {
+                    VideoCarouselOverlayMode.None
+                }
+            } catch (_: Exception) {
+                VideoCarouselOverlayMode.None
+            }
+        }
+
         private fun parseFeedFilter(json: String?): String? {
             // On Android, the SDK accepts the raw JSON string for filtering.
             // Return as-is if non-null/non-empty.
@@ -316,6 +362,26 @@ class ShortKitBridge(
                             val carouselItem = parseImageCarouselItem(itemObj) ?: continue
                             result.add(FeedInput.ImageCarousel(carouselItem))
                         }
+                        "videoCarousel" -> {
+                            val itemObj = obj.optJSONObject("item") ?: continue
+                            val videosArr = itemObj.optJSONArray("videos") ?: continue
+                            val videos = mutableListOf<ContentItem>()
+                            for (i in 0 until videosArr.length()) {
+                                val videoObj = videosArr.getJSONObject(i)
+                                parseContentItem(videoObj)?.let { videos.add(it) }
+                            }
+                            if (videos.isEmpty()) continue
+                            val carouselItem = VideoCarouselItem(
+                                id = itemObj.getString("id"),
+                                videos = videos,
+                                title = itemObj.optString("title", null),
+                                description = itemObj.optString("description", null),
+                                author = itemObj.optString("author", null),
+                                section = itemObj.optString("section", null),
+                                articleUrl = itemObj.optString("articleUrl", null),
+                            )
+                            result.add(FeedInput.VideoCarousel(carouselItem))
+                        }
                     }
                 }
                 result.ifEmpty { null }
@@ -349,6 +415,27 @@ class ShortKitBridge(
             )
         }
 
+        private fun parseContentItem(obj: JSONObject): ContentItem? {
+            val id = obj.optString("id", null) ?: return null
+            val title = obj.optString("title", null) ?: return null
+            val duration = obj.optDouble("duration", -1.0).takeIf { it >= 0 } ?: return null
+            val streamingUrl = obj.optString("streamingUrl", null) ?: return null
+            val thumbnailUrl = obj.optString("thumbnailUrl", null) ?: return null
+            return ContentItem(
+                id = id,
+                playbackId = obj.optString("playbackId", null),
+                title = title,
+                description = obj.optString("description", null),
+                duration = duration,
+                streamingUrl = streamingUrl,
+                thumbnailUrl = thumbnailUrl,
+                captionTracks = emptyList(),
+                author = obj.optString("author", null),
+                articleUrl = obj.optString("articleUrl", null),
+                fallbackUrl = obj.optString("fallbackUrl", null),
+            )
+        }
+
         private fun buildCaptionTracksJSONArray(tracks: List<CaptionTrack>): JSONArray {
             val arr = JSONArray()
             for (track in tracks) {
@@ -405,6 +492,7 @@ class ShortKitBridge(
     private val feedRegistry = mutableMapOf<String, WeakReference<ShortKitFeedFragment>>()
     private val pendingOps = mutableMapOf<String, MutableList<(ShortKitFeedFragment) -> Unit>>()
     private val pendingOpsLock = Any()
+    private var lastProgressEmitTime = 0L
 
     /** Expose the underlying SDK for the Fabric feed view manager. */
     val sdk: ShortKit? get() = shortKit
@@ -445,8 +533,35 @@ class ShortKitBridge(
                 emitEventOnMain("onContentTapped", params)
             }
 
-            override fun onRefreshRequested() {
-                emitEventOnMain("onRefreshRequested", Arguments.createMap())
+            override fun onRefreshStateChanged(state: ShortKitRefreshState) {
+                // Throttle pulling events to max 1 per 16ms to avoid bridge saturation
+                if (state is ShortKitRefreshState.Pulling) {
+                    val now = android.os.SystemClock.uptimeMillis()
+                    if (now - lastProgressEmitTime < 16L) return
+                    lastProgressEmitTime = now
+                }
+
+                val params = Arguments.createMap().apply {
+                    when (state) {
+                        is ShortKitRefreshState.Idle -> {
+                            putString("status", "idle")
+                            putDouble("progress", 0.0)
+                        }
+                        is ShortKitRefreshState.Pulling -> {
+                            putString("status", "pulling")
+                            putDouble("progress", state.progress.toDouble())
+                        }
+                        is ShortKitRefreshState.Triggered -> {
+                            putString("status", "triggered")
+                            putDouble("progress", 0.0)
+                        }
+                        is ShortKitRefreshState.Refreshing -> {
+                            putString("status", "refreshing")
+                            putDouble("progress", 0.0)
+                        }
+                    }
+                }
+                emitEventOnMain("onRefreshStateChanged", params)
             }
 
             override fun onFeedContentFetched(items: List<ContentItem>) {

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

@@ -207,11 +207,11 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
     @ReactMethod
     override fun preloadFeed(configJSON: String, itemsJSON: String?, promise: Promise) {
         val b = bridge
-        if (b == null) {
-            promise.resolve("")
-            return
+        if (b != null) {
+            b.preloadFeed(configJSON, itemsJSON) { result -> promise.resolve(result) }
+        } else {
+            bufferOp { bridge?.preloadFeed(configJSON, itemsJSON) { result -> promise.resolve(result) } }
         }
-        b.preloadFeed(configJSON, itemsJSON) { result -> promise.resolve(result) }
     }
 
     // -----------------------------------------------------------------
@@ -261,7 +261,7 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
                 "onSurveyResponse" -> emitOnSurveyResponse(params)
                 "onContentTapped" -> emitOnContentTapped(params)
                 "onDismiss" -> emitOnDismiss(params)
-                "onRefreshRequested" -> emitOnRefreshRequested(params)
+                "onRefreshStateChanged" -> emitOnRefreshStateChanged(params)
                 "onDidFetchContentItems" -> emitOnDidFetchContentItems(params)
                 "onFeedReady" -> emitOnFeedReady(params)
                 "onOverlayActiveChanged" -> emitOnOverlayActiveChanged(params)
@@ -273,6 +273,8 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
                 "onOverlayFeedScrollPhaseChanged" -> emitOnOverlayFeedScrollPhaseChanged(params)
                 "onOverlayTimeUpdate" -> emitOnOverlayTimeUpdate(params)
                 "onOverlayFullState" -> emitOnOverlayFullState(params)
+                "onCarouselActiveImageChanged" -> emitOnCarouselActiveImageChanged(params)
+                "onVideoCarouselActiveVideoChanged" -> emitOnVideoCarouselActiveVideoChanged(params)
                 else -> {
                     android.util.Log.w("SK:Module", "sendEvent: unknown event name '$name', using legacy emitter")
                     reactApplicationContext

package/ios/ReactCarouselOverlayHost.swift

@@ -5,8 +5,8 @@ import ShortKitSDK
 /// for rendering the developer's React carousel overlay component inside a feed cell.
 ///
 /// Unlike ReactOverlayHost, this does not subscribe to player state (carousels
-/// are image-based). It emits image URLs to JS for Image.prefetch() and pushes
-/// ImageCarouselItem data as appProperties.
+/// are image-based). It delivers `isActive` and `activeImageIndex` via bridge
+/// events (routed by surfaceId) to avoid Fabric remounts.
 @objc public class ReactCarouselOverlayHost: UIView, @unchecked Sendable, CarouselOverlay {
 
     // MARK: - Configuration
@@ -20,9 +20,6 @@ import ShortKitSDK
 
     // MARK: - Eager Surface Creation
 
-    /// Eagerly create the RN surface so it's ready before the first configure().
-    /// Called by the overlay factory right after setting surfacePresenter and moduleName.
-    /// Mirrors ReactOverlayHost.attach(player:) which does the same for video overlays.
     func prepareSurface() {
         createSurfaceIfNeeded()
     }
@@ -37,6 +34,14 @@ import ShortKitSDK
     private var surface: SKFabricSurfaceWrapper?
     private var surfaceView: UIView?
     private var pendingProps: [String: Any]?
+    private var isActive = false
+    private var activeImageIndex = 0
+
+    /// Serial queue for JPEG encoding + temp file writes (off main thread).
+    private static let imageWriteQueue = DispatchQueue(label: "com.shortkit.carousel-image-write", qos: .userInitiated)
+
+    /// Unique identifier for this overlay instance, used for event routing.
+    let surfaceId = UUID().uuidString
 
     // MARK: - Init
 
@@ -57,19 +62,32 @@ import ShortKitSDK
     // MARK: - CarouselOverlay
 
     public func configure(with item: ImageCarouselItem) {
+        isActive = false
+        activeImageIndex = 0
         createSurfaceIfNeeded()
 
-        // Replace remote URLs with local file URLs for any natively-cached images.
-        // The SDK's PrefetchManager downloads images into NSCache<NSString, UIImage>
-        // which RN can't access. Writing to temp files lets RN load instantly from disk.
+        // Replace remote URLs with local file URLs for any natively-cached images
+        // that already have a temp file on disk (fast path: FileManager.fileExists).
+        // If the native cache has the image but no temp file exists yet, use the
+        // remote URL immediately and schedule a background write so the file://
+        // URL is available on the next configure() for this image.
         var modifiedItem = item
         if let cachedImage {
             var localImages: [CarouselImage] = []
             for image in item.images {
-                if let uiImage = cachedImage(image.url),
-                   let localURL = writeTempImage(uiImage, for: image.url) {
-                    localImages.append(CarouselImage(url: localURL, alt: image.alt))
+                let tempURL = Self.tempFileURL(for: image.url)
+                if FileManager.default.fileExists(atPath: tempURL.path) {
+                    // Fast path: temp file already written — use file:// URL
+                    localImages.append(CarouselImage(url: tempURL.absoluteString, alt: image.alt))
+                } else if let uiImage = cachedImage(image.url) {
+                    // Native cache hit but no temp file yet — use remote URL now,
+                    // write temp file in background for next time.
+                    localImages.append(image)
+                    Self.imageWriteQueue.async {
+                        Self.writeTempImage(uiImage, to: tempURL)
+                    }
                 } else {
+                    // Not cached — use remote URL
                     localImages.append(image)
                 }
             }
@@ -85,10 +103,12 @@ import ShortKitSDK
             )
         }
 
-        // Build props — push now if surface exists, otherwise store for later
         if let data = try? JSONEncoder().encode(modifiedItem),
            let json = String(data: data, encoding: .utf8) {
-            let props: [String: Any] = ["item": json]
+            let props: [String: Any] = [
+                "surfaceId": surfaceId,
+                "item": json,
+            ]
             if let surface {
                 surface.setProperties(props)
             } else {
@@ -97,32 +117,46 @@ import ShortKitSDK
         }
     }
 
-    /// Write a UIImage to the temp directory, returning a file:// URL string.
-    /// Uses a hash of the remote URL as the filename to avoid duplicates.
-    private func writeTempImage(_ image: UIImage, for remoteURL: String) -> String? {
+    public func activatePlayback() {
+        isActive = true
+        bridge?.emit("onOverlayFullState", body: [
+            "surfaceId": surfaceId,
+            "isActive": true,
+            // Include required fields for the full state event
+            "playerState": "idle",
+            "isMuted": true,
+            "playbackRate": 1.0,
+            "captionsEnabled": false,
+            "activeCue": NSNull(),
+            "feedScrollPhase": NSNull(),
+        ])
+    }
+
+    public func updateActiveImage(index: Int) {
+        activeImageIndex = index
+        bridge?.emit("onCarouselActiveImageChanged", body: [
+            "surfaceId": surfaceId,
+            "activeImageIndex": index,
+        ])
+    }
+
+    /// Deterministic temp file URL for a given remote image URL.
+    private static func tempFileURL(for remoteURL: String) -> URL {
         let hash = remoteURL.hash
         let fileName = "sk-carousel-\(abs(hash)).jpg"
-        let fileURL = URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent(fileName)
-
-        // Skip if already written
-        if FileManager.default.fileExists(atPath: fileURL.path) {
-            return fileURL.absoluteString
-        }
+        return URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent(fileName)
+    }
 
-        guard let data = image.jpegData(compressionQuality: 0.9) else { return nil }
-        do {
-            try data.write(to: fileURL, options: .atomic)
-            return fileURL.absoluteString
-        } catch {
-            return nil
-        }
+    /// JPEG-encode a UIImage and write to the given file URL.
+    /// Safe to call from any queue — no UIKit main-thread requirements.
+    private static func writeTempImage(_ image: UIImage, to fileURL: URL) {
+        guard !FileManager.default.fileExists(atPath: fileURL.path),
+              let data = image.jpegData(compressionQuality: 0.9) else { return }
+        try? data.write(to: fileURL, options: .atomic)
     }
 
     public func resetState() {
-        // Don't clear surface props — matches video overlay (ReactOverlayHost) pattern.
-        // configure() will overwrite with new props directly, letting React do an
-        // in-place re-render (old→new) instead of an unmount+remount (old→empty→new).
-        // The overlay's synchronous reset pattern handles state transitions.
+        // Don't clear surface props — configure() will overwrite.
     }
 
     // MARK: - Surface Creation
@@ -130,7 +164,6 @@ import ShortKitSDK
     private func createSurfaceIfNeeded() {
         guard surface == nil, let presenter = surfacePresenter else { return }
 
-        // Must always dispatch to main queue — see ReactOverlayHost for details.
         DispatchQueue.main.async { [weak self] in
             guard let self, self.surface == nil else { return }
             self.installSurface(presenter: presenter)
@@ -157,7 +190,6 @@ import ShortKitSDK
         surfaceView = view
         surface = surf
 
-        // Flush any props that arrived before surface was ready
         if let pending = pendingProps {
             surf.setProperties(pending)
             pendingProps = nil