@shortkitsdk/react-native 0.2.6 → 0.2.12

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

@@ -0,0 +1,1029 @@
+package com.shortkit.reactnative
+
+import android.os.Handler
+import android.os.Looper
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.shortkit.sdk.ShortKit
+import com.shortkit.sdk.ShortKitDelegate
+import com.shortkit.sdk.ShortKitPlayer
+import com.shortkit.sdk.model.CaptionTrack
+import com.shortkit.sdk.model.CarouselImage
+import com.shortkit.sdk.model.ContentItem
+import com.shortkit.sdk.model.ContentSignal
+import com.shortkit.sdk.model.FeedDirection
+import com.shortkit.sdk.model.FeedFilter
+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.JsonValue
+import com.shortkit.sdk.model.PlayerState
+import com.shortkit.sdk.config.AdOverlayMode
+import com.shortkit.sdk.config.CarouselOverlayMode
+import com.shortkit.sdk.config.FeedConfig
+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.VideoOverlayMode
+import com.shortkit.sdk.feed.FeedPreload
+import com.shortkit.sdk.feed.ShortKitFeedFragment
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+import org.json.JSONArray
+import org.json.JSONObject
+import java.lang.ref.WeakReference
+
+/**
+ * Android bridge between the ShortKit SDK and the thin TurboModule.
+ *
+ * Holds the [ShortKit] instance, subscribes to all Kotlin Flows on
+ * [ShortKitPlayer], and forwards events to JS via the [emitEvent] lambda.
+ *
+ * Android equivalent of `react_native_sdk/ios/ShortKitBridge.swift`.
+ */
+class ShortKitBridge(
+    apiKey: String,
+    context: android.content.Context,
+    hasLoadingView: Boolean,
+    clientAppName: String?,
+    clientAppVersion: String?,
+    customDimensionsJSON: String?,
+    private val emitEvent: (String, WritableMap) -> Unit
+) {
+
+    companion object {
+        @Volatile
+        var shared: ShortKitBridge? = null
+            private set
+
+        /** Feed views waiting for the SDK to be initialized. */
+        internal val staticPendingFeedViews = mutableListOf<ShortKitFeedView>()
+
+        // ------------------------------------------------------------------
+        // Static serialization helpers (called by overlay hosts)
+        // ------------------------------------------------------------------
+
+        /**
+         * Serialize a [ContentItem] to a JSON string for bridge transport.
+         */
+        fun serializeContentItemToJSON(item: ContentItem): String {
+            return try {
+                val obj = JSONObject().apply {
+                    put("id", item.id)
+                    item.playbackId?.let { put("playbackId", it) }
+                    put("title", item.title)
+                    item.description?.let { put("description", it) }
+                    put("duration", item.duration)
+                    put("streamingUrl", item.streamingUrl)
+                    put("thumbnailUrl", item.thumbnailUrl)
+                    put("captionTracks", buildCaptionTracksJSONArray(item.captionTracks))
+                    item.customMetadata?.let { put("customMetadata", buildCustomMetadataJSONObject(it)) }
+                    item.author?.let { put("author", it) }
+                    item.articleUrl?.let { put("articleUrl", it) }
+                    item.commentCount?.let { put("commentCount", it) }
+                    item.fallbackUrl?.let { put("fallbackUrl", it) }
+                }
+                obj.toString()
+            } catch (_: Exception) {
+                "{}"
+            }
+        }
+
+        /**
+         * Convert a [PlayerState] sealed class to its string representation.
+         */
+        fun playerStateString(state: PlayerState): String {
+            return when (state) {
+                is PlayerState.Idle -> "idle"
+                is PlayerState.Loading -> "loading"
+                is PlayerState.Ready -> "ready"
+                is PlayerState.Playing -> "playing"
+                is PlayerState.Paused -> "paused"
+                is PlayerState.Seeking -> "seeking"
+                is PlayerState.Buffering -> "buffering"
+                is PlayerState.Ended -> "ended"
+                is PlayerState.Error -> "error"
+            }
+        }
+
+        /**
+         * Parse optional custom dimensions JSON string into a map.
+         */
+        fun parseCustomDimensions(json: String?): Map<String, String>? {
+            if (json.isNullOrEmpty()) return null
+            return try {
+                val obj = JSONObject(json)
+                val map = mutableMapOf<String, String>()
+                val keys = obj.keys()
+                while (keys.hasNext()) {
+                    val key = keys.next()
+                    map[key] = obj.getString(key)
+                }
+                map
+            } catch (_: Exception) {
+                null
+            }
+        }
+
+        /**
+         * Parse the JSON config string from JS into a [FeedConfig].
+         *
+         * @param json The JSON config string from JS.
+         * @param context Android context needed to instantiate overlay views.
+         */
+        fun parseFeedConfig(json: String, context: android.content.Context? = null): FeedConfig {
+            return try {
+                val obj = JSONObject(json)
+
+                val overlayRaw = obj.optString("overlay", null)
+
+                val feedHeight = parseFeedHeight(obj.optString("feedHeight", null))
+                val muteOnStart = obj.optBoolean("muteOnStart", true)
+                val videoOverlay = parseVideoOverlay(overlayRaw, context)
+
+                val feedSourceStr = obj.optString("feedSource", "algorithmic")
+                val feedSource = if (feedSourceStr == "custom") FeedSource.CUSTOM else FeedSource.ALGORITHMIC
+
+                val carouselOverlayRaw = obj.optString("carouselOverlay", null)
+                val carouselOverlay = parseCarouselOverlay(carouselOverlayRaw, 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
+
+                FeedConfig(
+                    feedHeight = feedHeight,
+                    videoOverlay = videoOverlay,
+                    carouselOverlay = carouselOverlay,
+                    surveyOverlay = SurveyOverlayMode.None,
+                    adOverlay = AdOverlayMode.None,
+                    muteOnStart = muteOnStart,
+                    autoplay = autoplay,
+                    feedSource = feedSource,
+                    filter = filter,
+                    scrollAxis = scrollAxis,
+                )
+            } catch (e: Exception) {
+                android.util.Log.e("SK:Bridge", "parseFeedConfig: EXCEPTION parsing config, returning default. json=${json.take(300)}", e)
+                FeedConfig()
+            }
+        }
+
+        // ------------------------------------------------------------------
+        // Private static parsing helpers
+        // ------------------------------------------------------------------
+
+        private fun parseFeedHeight(json: String?): FeedHeight {
+            if (json.isNullOrEmpty()) return FeedHeight.Fullscreen
+            return try {
+                val obj = JSONObject(json)
+                when (obj.optString("type")) {
+                    "percentage" -> {
+                        val value = obj.optDouble("value", 1.0)
+                        FeedHeight.Percentage(value.toFloat())
+                    }
+                    else -> FeedHeight.Fullscreen
+                }
+            } catch (_: Exception) {
+                FeedHeight.Fullscreen
+            }
+        }
+
+        /**
+         * Parse a double-stringified overlay JSON.
+         * - `"\"none\""` -> None
+         * - `"{\"type\":\"custom\"}"` -> Custom with ReactOverlayHost factory
+         */
+        private fun parseVideoOverlay(json: String?, context: android.content.Context?): VideoOverlayMode {
+            if (json.isNullOrEmpty()) {
+                return VideoOverlayMode.None
+            }
+            return try {
+                val parsed = json.trim()
+
+                if (parsed == "\"none\"" || parsed == "none") {
+                    return VideoOverlayMode.None
+                }
+
+                val inner = if (parsed.startsWith("\"") && parsed.endsWith("\"")) {
+                    JSONObject(parsed.substring(1, parsed.length - 1).replace("\\\"", "\""))
+                } else {
+                    JSONObject(parsed)
+                }
+
+                val type = inner.optString("type")
+                val name = inner.optString("name", "Default")
+
+                if (type == "custom" && context != null) {
+                    val ctx = context.applicationContext
+                    VideoOverlayMode.Custom { ReactOverlayHost(ctx).apply { overlayName = name } }
+                } else {
+                    android.util.Log.w("SK:Bridge", "parseVideoOverlay: → None (type='$type' context=${if (context != null) "OK" else "NULL"})")
+                    VideoOverlayMode.None
+                }
+            } catch (e: Exception) {
+                android.util.Log.e("SK:Bridge", "parseVideoOverlay: EXCEPTION → None. json=${json.take(200)}", e)
+                VideoOverlayMode.None
+            }
+        }
+
+        /**
+         * Parse a double-stringified carousel overlay JSON.
+         * - `"\"none\""` -> None
+         * - `"{\"type\":\"custom\"}"` -> Custom with ReactCarouselOverlayHost factory
+         */
+        private fun parseCarouselOverlay(json: String?, context: android.content.Context?): 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" && context != null) {
+                    val name = inner.optString("name", "Default")
+                    val ctx = context.applicationContext
+                    CarouselOverlayMode.Custom {
+                        ReactCarouselOverlayHost(ctx).apply {
+                            carouselOverlayName = name
+                            // Eagerly create the RN surface so it's mounted and ready
+                            // before the cell scrolls into view, matching iOS behaviour.
+                            prepareSurface()
+                        }
+                    }
+                } else {
+                    CarouselOverlayMode.None
+                }
+            } catch (_: Exception) {
+                CarouselOverlayMode.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.
+            if (json.isNullOrEmpty()) return null
+            return json
+        }
+
+        /** Parse a JSON filter string into a FeedFilter model for SDK methods that accept it. */
+        fun parseFeedFilterToModel(json: String): FeedFilter? {
+            if (json.isBlank()) return null
+            return try {
+                val obj = JSONObject(json)
+                FeedFilter(
+                    tags = obj.optJSONArray("tags")?.let { arr ->
+                        (0 until arr.length()).map { arr.getString(it) }
+                    },
+                    section = obj.optString("section").ifBlank { null },
+                    author = obj.optString("author").ifBlank { null },
+                    contentType = obj.optString("contentType").ifBlank { null },
+                    metadata = obj.optJSONObject("metadata")?.let { m ->
+                        m.keys().asSequence().associateWith { m.getString(it) }
+                    }
+                )
+            } catch (_: Exception) { null }
+        }
+
+        private fun parseFeedInputs(json: String): List<FeedInput>? {
+            return try {
+                val arr = JSONArray(json)
+                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
+                            val fallbackUrl = obj.optString("fallbackUrl", null)
+                            result.add(FeedInput.Video(playbackId, fallbackUrl))
+                        }
+                        "imageCarousel" -> {
+                            val itemObj = obj.optJSONObject("item") ?: continue
+                            val carouselItem = parseImageCarouselItem(itemObj) ?: continue
+                            result.add(FeedInput.ImageCarousel(carouselItem))
+                        }
+                    }
+                }
+                result.ifEmpty { null }
+            } catch (_: Exception) {
+                null
+            }
+        }
+
+        private fun parseImageCarouselItem(obj: JSONObject): ImageCarouselItem? {
+            val id = obj.optString("id", null) ?: return null
+            val imagesArr = obj.optJSONArray("images") ?: return null
+            val images = mutableListOf<CarouselImage>()
+            for (i in 0 until imagesArr.length()) {
+                val imgObj = imagesArr.getJSONObject(i)
+                images.add(
+                    CarouselImage(
+                        url = imgObj.getString("url"),
+                        alt = imgObj.optString("alt", null)
+                    )
+                )
+            }
+            return ImageCarouselItem(
+                id = id,
+                images = images,
+                caption = obj.optString("caption", null),
+                title = obj.optString("title", null),
+                description = obj.optString("description", null),
+                author = obj.optString("author", null),
+                section = obj.optString("section", null),
+                articleUrl = obj.optString("articleUrl", null)
+            )
+        }
+
+        private fun buildCaptionTracksJSONArray(tracks: List<CaptionTrack>): JSONArray {
+            val arr = JSONArray()
+            for (track in tracks) {
+                val obj = JSONObject().apply {
+                    put("language", track.language)
+                    put("label", track.label)
+                    put("sourceUrl", track.url ?: "")
+                }
+                arr.put(obj)
+            }
+            return arr
+        }
+
+        private fun buildCustomMetadataJSONObject(meta: Map<String, JsonValue>): JSONObject {
+            val obj = JSONObject()
+            for ((key, value) in meta) {
+                obj.put(key, jsonValueToAny(value))
+            }
+            return obj
+        }
+
+        private fun jsonValueToAny(value: JsonValue): Any {
+            return when (value) {
+                is JsonValue.StringValue -> value.value
+                is JsonValue.NumberValue -> value.value
+                is JsonValue.BoolValue -> value.value
+                is JsonValue.ObjectValue -> {
+                    val obj = JSONObject()
+                    for ((k, v) in value.value) {
+                        obj.put(k, jsonValueToAny(v))
+                    }
+                    obj
+                }
+                is JsonValue.NullValue -> JSONObject.NULL
+            }
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // State
+    // ------------------------------------------------------------------
+
+    private var shortKit: ShortKit? = null
+    private var scope: CoroutineScope? = null
+
+    /** Preload handles keyed by UUID, consumed by feed views via preloadId prop. */
+    var preloadHandles = mutableMapOf<String, FeedPreload>()
+        private set
+
+    // ------------------------------------------------------------------
+    // Feed instance registry
+    // ------------------------------------------------------------------
+
+    private val feedRegistry = mutableMapOf<String, WeakReference<ShortKitFeedFragment>>()
+    private val pendingOps = mutableMapOf<String, MutableList<(ShortKitFeedFragment) -> Unit>>()
+    private val pendingOpsLock = Any()
+
+    /** Expose the underlying SDK for the Fabric feed view manager. */
+    val sdk: ShortKit? get() = shortKit
+
+    // ------------------------------------------------------------------
+    // Init
+    // ------------------------------------------------------------------
+
+    init {
+        val dims = parseCustomDimensions(customDimensionsJSON)
+
+        val sdk = ShortKit(
+            context = context,
+            apiKey = apiKey,
+            userId = null,
+            adProvider = null,
+            clientAppName = clientAppName,
+            clientAppVersion = clientAppVersion,
+            customDimensions = dims
+        )
+        this.shortKit = sdk
+        shared = this
+
+        // Wire custom loading view provider
+        if (hasLoadingView) {
+            sdk.loadingViewProvider = { ctx -> ReactLoadingHost(ctx) }
+        }
+
+        subscribeToFlows(sdk.player)
+
+        // Wire delegate
+        sdk.delegate = object : ShortKitDelegate {
+            override fun onContentTapped(contentId: String, index: Int) {
+                val params = Arguments.createMap().apply {
+                    putString("contentId", contentId)
+                    putInt("index", index)
+                }
+                emitEventOnMain("onContentTapped", params)
+            }
+
+            override fun onRefreshRequested() {
+                emitEventOnMain("onRefreshRequested", Arguments.createMap())
+            }
+
+            override fun onFeedContentFetched(items: List<ContentItem>) {
+                val arr = org.json.JSONArray()
+                for (item in items) {
+                    arr.put(org.json.JSONObject(serializeContentItemToJSON(item)))
+                }
+                val params = Arguments.createMap().apply {
+                    putString("items", arr.toString())
+                }
+                emitEventOnMain("onDidFetchContentItems", params)
+            }
+        }
+
+        // Drain any feed views that were waiting for the SDK to be ready
+        val pending: List<ShortKitFeedView>
+        synchronized(staticPendingFeedViews) {
+            pending = staticPendingFeedViews.toList()
+            staticPendingFeedViews.clear()
+        }
+        val mainHandler = Handler(Looper.getMainLooper())
+        for (view in pending) {
+            mainHandler.post {
+                if (view.isAttachedToWindow) view.embedFeedFragmentIfNeeded()
+            }
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // Teardown
+    // ------------------------------------------------------------------
+
+    fun teardown() {
+        scope?.cancel()
+        scope = null
+        preloadHandles.clear()
+        feedRegistry.clear()
+        // Note: pendingOps are NOT cleared — they survive re-init
+        shortKit?.release()
+        shortKit = null
+        if (shared === this) {
+            shared = null
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // Feed registry
+    // ------------------------------------------------------------------
+
+    fun registerFeedFragment(id: String, fragment: ShortKitFeedFragment) {
+        feedRegistry[id] = WeakReference(fragment)
+
+        // Wire per-feed callbacks
+        fragment.onDismiss = {
+            emitEventOnMain("onDismiss", Arguments.createMap())
+        }
+        fragment.onRemainingContentCountChange = { count ->
+            val params = Arguments.createMap().apply {
+                putString("feedId", id)
+                putInt("count", count)
+            }
+            emitEventOnMain("onRemainingContentCountChanged", params)
+        }
+        fragment.onFeedReady = {
+            val params = Arguments.createMap().apply {
+                putString("feedId", id)
+            }
+            emitEventOnMain("onFeedReady", params)
+        }
+
+        // Replay buffered operations after the fragment's view is created.
+        // commitNowAllowingStateLoss triggers onCreate but onViewCreated
+        // (which sets up customFeedController) runs on a later main-thread
+        // tick. A single post isn't enough — use postDelayed to ensure the
+        // fragment's view lifecycle has completed.
+        val ops: List<(ShortKitFeedFragment) -> Unit>?
+        synchronized(pendingOpsLock) {
+            ops = pendingOps.remove(id)?.toList()
+        }
+        if (ops != null) {
+            Handler(Looper.getMainLooper()).postDelayed({
+                val frag = feedRegistry[id]?.get() ?: return@postDelayed
+                for (op in ops) {
+                    op(frag)
+                }
+            }, 100)
+        }
+    }
+
+    fun unregisterFeedFragment(id: String) {
+        feedRegistry.remove(id)
+        // pendingOps preserved for detach/reattach cycles
+    }
+
+    private fun feedFragment(id: String): ShortKitFeedFragment? {
+        return feedRegistry[id]?.get()
+    }
+
+    fun registerFeed(id: String) {
+        // No-op — registerFeedFragment handles drain
+    }
+
+    fun unregisterFeed(id: String) {
+        // pendingOps preserved for detach/reattach cycles
+    }
+
+    /** Register a feed view that is waiting for the SDK to be initialized. */
+    fun registerPendingFeedView(view: ShortKitFeedView) {
+        if (shortKit != null) {
+            view.embedFeedFragmentIfNeeded()
+        } else {
+            synchronized(staticPendingFeedViews) {
+                staticPendingFeedViews.add(view)
+            }
+        }
+    }
+
+    fun unregisterPendingFeedView(view: ShortKitFeedView) {
+        synchronized(staticPendingFeedViews) {
+            staticPendingFeedViews.remove(view)
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // Preload handle management
+    // ------------------------------------------------------------------
+
+    fun consumePreload(id: String): FeedPreload? {
+        return preloadHandles.remove(id)
+    }
+
+    // ------------------------------------------------------------------
+    // Event emission helpers (public for overlay hosts)
+    // ------------------------------------------------------------------
+
+    fun emitEvent(name: String, params: WritableMap) {
+        emitEvent.invoke(name, params)
+    }
+
+    fun emitEventOnMain(name: String, params: WritableMap) {
+        if (Looper.myLooper() == Looper.getMainLooper()) {
+            emitEvent.invoke(name, params)
+        } else {
+            Handler(Looper.getMainLooper()).post {
+                emitEvent.invoke(name, params)
+            }
+        }
+    }
+
+    fun emitOverlayEvent(name: String, item: ContentItem) {
+        val params = Arguments.createMap().apply {
+            putString("item", serializeContentItemToJSON(item))
+        }
+        emitEvent.invoke(name, params)
+    }
+
+    fun emitOverlayEvent(name: String, params: WritableMap) {
+        emitEvent.invoke(name, params)
+    }
+
+    fun emitCarouselOverlayEvent(name: String, params: WritableMap) {
+        emitEvent.invoke(name, params)
+    }
+
+    // ------------------------------------------------------------------
+    // Player commands
+    // ------------------------------------------------------------------
+
+    // All player commands dispatch to main thread — ExoPlayer is bound to
+    // the main looper but @ReactMethod calls arrive on the NativeModules thread.
+
+    private fun runOnMain(block: () -> Unit) {
+        Handler(Looper.getMainLooper()).post(block)
+    }
+
+    fun play() { runOnMain { shortKit?.player?.play() } }
+    fun pause() { runOnMain { shortKit?.player?.pause() } }
+    fun seek(seconds: Double) { runOnMain { shortKit?.player?.seek(seconds) } }
+    fun seekAndPlay(seconds: Double) { runOnMain { shortKit?.player?.seekAndPlay(seconds) } }
+    fun skipToNext() { runOnMain { shortKit?.player?.skipToNext() } }
+    fun skipToPrevious() { runOnMain { shortKit?.player?.skipToPrevious() } }
+    fun setMuted(muted: Boolean) { runOnMain { shortKit?.player?.setMuted(muted) } }
+    fun setPlaybackRate(rate: Double) { runOnMain { shortKit?.player?.setPlaybackRate(rate.toFloat()) } }
+    fun setCaptionsEnabled(enabled: Boolean) { runOnMain { shortKit?.player?.setCaptionsEnabled(enabled) } }
+    fun selectCaptionTrack(language: String) { runOnMain { shortKit?.player?.selectCaptionTrack(language) } }
+    fun sendContentSignal(signal: String) {
+        val contentSignal = if (signal == "positive") ContentSignal.POSITIVE else ContentSignal.NEGATIVE
+        runOnMain { shortKit?.player?.sendContentSignal(contentSignal) }
+    }
+    fun setMaxBitrate(bitrate: Double) { runOnMain { shortKit?.player?.setMaxBitrate(bitrate.toInt()) } }
+
+    fun setUserId(userId: String) {
+        shortKit?.setUserId(userId)
+    }
+
+    fun clearUserId() {
+        shortKit?.clearUserId()
+    }
+
+    fun onPause() {
+        Handler(Looper.getMainLooper()).post { shortKit?.pause() }
+    }
+
+    fun onResume() {
+        // No-op: let the SDK's internal lifecycle handle resume
+    }
+
+    // ------------------------------------------------------------------
+    // Custom feed operations
+    // ------------------------------------------------------------------
+
+    fun setFeedItems(feedId: String, itemsJSON: String) {
+        val fragment = feedFragment(feedId)
+        if (fragment != null) {
+            val parsed = parseFeedInputs(itemsJSON) ?: return
+            Handler(Looper.getMainLooper()).post {
+                fragment.setFeedItems(parsed)
+            }
+        } else {
+            synchronized(pendingOpsLock) {
+                pendingOps.getOrPut(feedId) { mutableListOf() }.add { frag ->
+                    val parsed = parseFeedInputs(itemsJSON) ?: return@add
+                    if (Looper.myLooper() == Looper.getMainLooper()) {
+                        frag.setFeedItems(parsed)
+                    } else {
+                        Handler(Looper.getMainLooper()).post {
+                            frag.setFeedItems(parsed)
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    fun appendFeedItems(feedId: String, itemsJSON: String) {
+        val fragment = feedFragment(feedId)
+        if (fragment != null) {
+            val parsed = parseFeedInputs(itemsJSON) ?: return
+            Handler(Looper.getMainLooper()).post {
+                fragment.appendFeedItems(parsed)
+            }
+        } else {
+            synchronized(pendingOpsLock) {
+                pendingOps.getOrPut(feedId) { mutableListOf() }.add { frag ->
+                    val parsed = parseFeedInputs(itemsJSON) ?: return@add
+                    Handler(Looper.getMainLooper()).post {
+                        frag.appendFeedItems(parsed)
+                    }
+                }
+            }
+        }
+    }
+
+    fun applyFilter(feedId: String, filterJSON: String?) {
+        val fragment = feedRegistry[feedId]?.get()
+        if (fragment != null) {
+            val filter = filterJSON?.let { parseFeedFilterToModel(it) }
+            Handler(Looper.getMainLooper()).post { fragment.applyFilter(filter) }
+        } else {
+            synchronized(pendingOpsLock) {
+                pendingOps.getOrPut(feedId) { mutableListOf() }.add { frag ->
+                    val filter = filterJSON?.let { parseFeedFilterToModel(it) }
+                    Handler(Looper.getMainLooper()).post { frag.applyFilter(filter) }
+                }
+            }
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // Fetch content
+    // ------------------------------------------------------------------
+
+    fun fetchContent(limit: Int, filterJSON: String?, callback: (String) -> Unit) {
+        val sdk = shortKit
+        if (sdk == null) {
+            callback("[]")
+            return
+        }
+        scope?.launch {
+            try {
+                val filter = filterJSON?.let { parseFeedFilterToModel(it) }
+                val items = sdk.fetchContent(limit, filter)
+                val arr = JSONArray()
+                for (item in items) {
+                    arr.put(JSONObject(serializeContentItemToJSON(item)))
+                }
+                callback(arr.toString())
+            } catch (_: Exception) {
+                callback("[]")
+            }
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // Preload feed
+    // ------------------------------------------------------------------
+
+    fun preloadFeed(configJSON: String, itemsJSON: String?, callback: (String) -> Unit) {
+        val sdk = shortKit
+        if (sdk == null) {
+            callback("")
+            return
+        }
+        val config = parseFeedConfig(configJSON)
+        if (config.feedSource == FeedSource.CUSTOM) {
+            if (itemsJSON == null) {
+                android.util.Log.w("ShortKit", "preloadFeed called with feedSource=CUSTOM but no items")
+                callback("")
+                return
+            }
+            val items = parseFeedInputs(itemsJSON)
+            if (items == null) {
+                callback("")
+                return
+            }
+            val preload = sdk.preloadFeed(items = items)
+            val uuid = java.util.UUID.randomUUID().toString()
+            preloadHandles[uuid] = preload
+            callback(uuid)
+            return
+        }
+        val filterJSON = config.filter?.let { org.json.JSONObject().apply {
+            it.tags?.let { tags -> put("tags", org.json.JSONArray(tags)) }
+            it.section?.let { s -> put("section", s) }
+            it.author?.let { a -> put("author", a) }
+            it.contentType?.let { ct -> put("contentType", ct) }
+        }.toString() }
+        val preload = sdk.preloadFeed(filter = filterJSON)
+        val uuid = java.util.UUID.randomUUID().toString()
+        preloadHandles[uuid] = preload
+        callback(uuid)
+    }
+
+    // ------------------------------------------------------------------
+    // Storyboard / Seek Thumbnails
+    // ------------------------------------------------------------------
+
+    fun prefetchStoryboard(playbackId: String) {
+        shortKit?.player?.prefetchStoryboard(playbackId)
+    }
+
+    fun getStoryboardData(playbackId: String, callback: (String?) -> Unit) {
+        val player = shortKit?.player
+        if (player == null) {
+            callback(null)
+            return
+        }
+        // Try cached data first
+        val json = player.getStoryboardData(playbackId)
+        if (json != null) {
+            callback(json)
+            return
+        }
+        // Trigger prefetch and retry with coroutine delay (not Thread.sleep)
+        player.prefetchStoryboard(playbackId)
+        scope?.launch {
+            var retries = 0
+            while (retries < 30) { // 3 seconds max
+                delay(100)
+                val data = player.getStoryboardData(playbackId)
+                if (data != null) {
+                    callback(data)
+                    return@launch
+                }
+                retries++
+            }
+            callback(null)
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // Content item map (for onCurrentItemChanged)
+    // ------------------------------------------------------------------
+
+    private fun contentItemMap(item: ContentItem): WritableMap {
+        return Arguments.createMap().apply {
+            putString("id", item.id)
+            item.playbackId?.let { putString("playbackId", it) }
+            putString("title", item.title)
+            item.description?.let { putString("description", it) }
+            putDouble("duration", item.duration)
+            putString("streamingUrl", item.streamingUrl)
+            putString("thumbnailUrl", item.thumbnailUrl)
+
+            // Caption tracks as JSON string
+            putString("captionTracks", buildCaptionTracksJSONArray(item.captionTracks).toString())
+
+            // Custom metadata as JSON string
+            item.customMetadata?.let { meta ->
+                putString("customMetadata", buildCustomMetadataJSONObject(meta).toString())
+            }
+
+            item.author?.let { putString("author", it) }
+            item.articleUrl?.let { putString("articleUrl", it) }
+            item.commentCount?.let { putInt("commentCount", it) }
+            item.fallbackUrl?.let { putString("fallbackUrl", it) }
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // Flow subscriptions
+    // ------------------------------------------------------------------
+
+    private fun subscribeToFlows(player: ShortKitPlayer) {
+        scope?.cancel()
+        val newScope = CoroutineScope(Dispatchers.Main + SupervisorJob())
+        scope = newScope
+
+        // Player state
+        newScope.launch {
+            player.playerState.collect { state ->
+                val params = Arguments.createMap().apply {
+                    putString("state", playerStateString(state))
+                    if (state is PlayerState.Error) {
+                        putString("errorMessage", state.message)
+                    }
+                }
+                emitEvent.invoke("onPlayerStateChanged", params)
+            }
+        }
+
+        // Current item
+        newScope.launch {
+            player.currentItem.collect { item ->
+                if (item != null) {
+                    emitEvent.invoke("onCurrentItemChanged", contentItemMap(item))
+                }
+            }
+        }
+
+        // Time updates (ms -> seconds)
+        newScope.launch {
+            player.time.collect { time ->
+                val params = Arguments.createMap().apply {
+                    putDouble("current", time.currentMs / 1000.0)
+                    putDouble("duration", time.durationMs / 1000.0)
+                    putDouble("buffered", time.bufferedMs / 1000.0)
+                }
+                emitEvent.invoke("onTimeUpdate", params)
+            }
+        }
+
+        // Muted state
+        newScope.launch {
+            player.isMuted.collect { muted ->
+                val params = Arguments.createMap().apply {
+                    putBoolean("isMuted", muted)
+                }
+                emitEvent.invoke("onMutedChanged", params)
+            }
+        }
+
+        // Playback rate
+        newScope.launch {
+            player.playbackRate.collect { rate ->
+                val params = Arguments.createMap().apply {
+                    putDouble("rate", rate.toDouble())
+                }
+                emitEvent.invoke("onPlaybackRateChanged", params)
+            }
+        }
+
+        // Captions enabled
+        newScope.launch {
+            player.captionsEnabled.collect { enabled ->
+                val params = Arguments.createMap().apply {
+                    putBoolean("enabled", enabled)
+                }
+                emitEvent.invoke("onCaptionsEnabledChanged", params)
+            }
+        }
+
+        // Active caption track
+        newScope.launch {
+            player.activeCaptionTrack.collect { track ->
+                if (track != null) {
+                    val params = Arguments.createMap().apply {
+                        putString("language", track.language)
+                        putString("label", track.label)
+                        putString("sourceUrl", track.url ?: "")
+                    }
+                    emitEvent.invoke("onActiveCaptionTrackChanged", params)
+                }
+            }
+        }
+
+        // Active cue (ms -> seconds)
+        newScope.launch {
+            player.activeCue.collect { cue ->
+                if (cue != null) {
+                    val params = Arguments.createMap().apply {
+                        putString("text", cue.text)
+                        putDouble("startTime", cue.startMs / 1000.0)
+                        putDouble("endTime", cue.endMs / 1000.0)
+                    }
+                    emitEvent.invoke("onActiveCueChanged", params)
+                }
+            }
+        }
+
+        // Did loop
+        newScope.launch {
+            player.didLoop.collect { event ->
+                val params = Arguments.createMap().apply {
+                    putString("contentId", event.contentId)
+                    putInt("loopCount", event.loopCount)
+                }
+                emitEvent.invoke("onDidLoop", params)
+            }
+        }
+
+        // Feed transition
+        newScope.launch {
+            player.feedTransition.collect { event ->
+                val params = Arguments.createMap().apply {
+                    putString("phase", when (event.phase) {
+                        FeedTransitionPhase.BEGAN -> "began"
+                        FeedTransitionPhase.ENDED -> "ended"
+                    })
+                    putString("direction", when (event.direction) {
+                        FeedDirection.FORWARD -> "forward"
+                        FeedDirection.BACKWARD -> "backward"
+                        else -> "forward"
+                    })
+                    if (event.from != null) {
+                        putString("fromItem", serializeContentItemToJSON(event.from!!))
+                    }
+                    if (event.to != null) {
+                        putString("toItem", serializeContentItemToJSON(event.to!!))
+                    }
+                }
+                emitEvent.invoke("onFeedTransition", params)
+            }
+        }
+
+        // Format change
+        newScope.launch {
+            player.formatChange.collect { event ->
+                val params = Arguments.createMap().apply {
+                    putString("contentId", event.contentId)
+                    putDouble("fromBitrate", event.fromBitrate.toDouble())
+                    putDouble("toBitrate", event.toBitrate.toDouble())
+                    putString("fromResolution", event.fromResolution ?: "")
+                    putString("toResolution", event.toResolution ?: "")
+                }
+                emitEvent.invoke("onFormatChange", params)
+            }
+        }
+
+        // Prefetched ahead count
+        newScope.launch {
+            player.prefetchedAheadCount.collect { count ->
+                val params = Arguments.createMap().apply {
+                    putInt("count", count)
+                }
+                emitEvent.invoke("onPrefetchedAheadCountChanged", params)
+            }
+        }
+
+        // Remaining content count — handled per-feed via fragment.onRemainingContentCountChange callback
+
+        // Feed scroll phase
+        newScope.launch {
+            player.feedScrollPhase.collect { phase ->
+                val params = Arguments.createMap().apply {
+                    when (phase) {
+                        is FeedScrollPhase.Dragging -> {
+                            putString("phase", "dragging")
+                            putString("fromId", phase.fromId)
+                        }
+                        is FeedScrollPhase.Settled -> {
+                            putString("phase", "settled")
+                        }
+                    }
+                }
+                emitEvent.invoke("onFeedScrollPhase", params)
+            }
+        }
+    }
+}