@shortkitsdk/react-native 0.2.35 → 0.2.37

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

@@ -76,6 +76,70 @@ class ShortKitBridge(
         // Static serialization helpers (called by overlay hosts)
         // ------------------------------------------------------------------
 
+        /**
+         * Serialize a [VideoCarouselItem] to a JSON string for bridge transport.
+         * SHO-15: used by ReactVideoCarouselOverlayHost when emitting
+         * onCarouselActiveVideoCompleted. Mirrors how
+         * ReactVideoCarouselOverlayHost.configure already serializes
+         * VideoCarouselItem via kotlinx.serialization.
+         */
+        fun serializeVideoCarouselItemToJSON(item: com.shortkit.sdk.model.VideoCarouselItem?): String {
+            if (item == null) return "null"
+            return try {
+                kotlinx.serialization.json.Json.encodeToString(
+                    com.shortkit.sdk.model.VideoCarouselItem.serializer(),
+                    item,
+                )
+            } catch (_: Exception) {
+                "null"
+            }
+        }
+
+        /**
+         * Serialize a [FeedItem] to a ContentItem-shaped JSON string for the
+         * `onFeedTransition` event. For [FeedItem.Content] cells this is the
+         * real ContentItem. For every other cell kind (AdSlotItem,
+         * ImageCarousel, Survey, VideoCarousel) there is no playable
+         * ContentItem, so we synthesize a minimal one whose ONLY meaningful
+         * field is `id`.
+         *
+         * Why: JS hosts use `event.to` as an identity cursor for resume-on-
+         * tab-return (`setFeedItems(startAt:)`). Before this synthesis, non-
+         * content cells came through as `to=null` and the host's stored
+         * resume id stayed pinned to the last regular video — causing the
+         * SDK to re-seed the feed at the wrong index on tab return.
+         *
+         * Scope: this is a bridge-only synthesis. It never flows back into
+         * the Android SDK (pool, cache, FeedDataSource, etc. all still see
+         * the real FeedItem and treat non-content cells honestly). JS-side
+         * consumers should ONLY read `.id` / `.playbackId` from
+         * `onFeedTransition` items — deeper fields are placeholders for
+         * non-content cells.
+         *
+         * Mirrors iOS PR #170 ShortKitBridge.swift:770-790.
+         */
+        fun serializeFeedItemIdentityJSON(feedItem: com.shortkit.sdk.model.FeedItem): String {
+            if (feedItem is com.shortkit.sdk.model.FeedItem.Content) {
+                return serializeContentItemToJSON(feedItem.item)
+            }
+            val synthetic = ContentItem(
+                id = feedItem.id,
+                playbackId = null,
+                title = "",
+                description = null,
+                duration = 0.0,
+                streamingUrl = "",
+                thumbnailUrl = "",
+                captionTracks = emptyList(),
+                customMetadata = null,
+                author = null,
+                articleUrl = null,
+                commentCount = null,
+                fallbackUrl = null,
+            )
+            return serializeContentItemToJSON(synthetic)
+        }
+
         /**
          * Serialize a [ContentItem] to a JSON string for bridge transport.
          */
@@ -349,7 +413,7 @@ class ShortKitBridge(
             } catch (_: Exception) { null }
         }
 
-        private fun parseFeedInputs(json: String): List<FeedInput>? {
+        internal fun parseFeedInputs(json: String): List<FeedInput>? {
             return try {
                 val arr = JSONArray(json)
                 val result = mutableListOf<FeedInput>()
@@ -535,7 +599,12 @@ class ShortKitBridge(
         // Wire delegate
         sdk.delegate = object : ShortKitDelegate {
             override fun onContentTapped(contentId: String, index: Int) {
+                // Capture feedId synchronously — after the post-to-main hop
+                // the active surface may have shifted (user swiped tabs).
+                // Mirrors iOS ShortKitBridge.swift:1174 pattern.
+                val feedId = activeSurfaceFeedId()
                 val params = Arguments.createMap().apply {
+                    putString("feedId", feedId)
                     putString("contentId", contentId)
                     putInt("index", index)
                 }
@@ -550,7 +619,9 @@ class ShortKitBridge(
                     lastProgressEmitTime = now
                 }
 
+                val feedId = activeSurfaceFeedId()
                 val params = Arguments.createMap().apply {
+                    putString("feedId", feedId)
                     when (state) {
                         is ShortKitRefreshState.Idle -> {
                             putString("status", "idle")
@@ -574,11 +645,13 @@ class ShortKitBridge(
             }
 
             override fun onFeedContentFetched(items: List<ContentItem>) {
+                val feedId = activeSurfaceFeedId()
                 val arr = org.json.JSONArray()
                 for (item in items) {
                     arr.put(org.json.JSONObject(serializeContentItemToJSON(item)))
                 }
                 val params = Arguments.createMap().apply {
+                    putString("feedId", feedId)
                     putString("items", arr.toString())
                 }
                 emitEventOnMain("onDidFetchContentItems", params)
@@ -640,6 +713,57 @@ class ShortKitBridge(
             }
             emitEventOnMain("onFeedReady", params)
         }
+        // Per-feed pull-to-refresh — the JS-side ShortKitFeed subscribes
+        // to `onRefreshStateChangedPerFeed` (not the unscoped `onRefreshStateChanged`),
+        // so this is the event that actually drives the host's refresh
+        // handler. Mirrors iOS ShortKitBridge.swift:74-90 emit pattern.
+        fragment.onRefreshStateChanged = { state ->
+            // 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) {
+                    lastProgressEmitTime = now
+                    emitRefreshPerFeed(id, state)
+                }
+            } else {
+                emitRefreshPerFeed(id, state)
+            }
+        }
+        fragment.onVideoCarouselCellTap = { payload ->
+            emitVideoCarouselCellTap(payload.id, payload.index, payload.pageIndex)
+        }
+        // Per-feed transition event. Fires once per transition, bound to this
+        // fragment. Replaces the global player.feedTransition.collect pattern
+        // (which fanned every feed's transitions out to every mounted
+        // <ShortKitFeed>, causing cross-feed state pollution). Structural fix:
+        // callback literally cannot fire on the wrong feed. Mirrors iOS
+        // PR #170 ShortKitBridge.swift:117-143.
+        fragment.onFeedTransition = { event ->
+            val params = Arguments.createMap().apply {
+                putString("feedId", id)
+                putString("phase", when (event.phase) {
+                    FeedTransitionPhase.BEGAN -> "began"
+                    FeedTransitionPhase.ENDED -> "ended"
+                })
+                putString("direction", when (event.direction) {
+                    FeedDirection.FORWARD -> "forward"
+                    FeedDirection.BACKWARD -> "backward"
+                    else -> "forward"
+                })
+                // Serialize from the underlying FeedItem (not event.from/to
+                // which are null for non-content cells). See the docstring on
+                // serializeFeedItemIdentityJSON for the why — in short, this
+                // ensures carousels/ads/surveys come through with a populated
+                // id, so JS-side hosts can track feed position for any cell type.
+                event.fromFeedItem?.let {
+                    putString("fromItem", serializeFeedItemIdentityJSON(it))
+                }
+                event.toFeedItem?.let {
+                    putString("toItem", serializeFeedItemIdentityJSON(it))
+                }
+            }
+            emitEventOnMain("onFeedTransition", params)
+        }
 
         // Replay buffered operations after the fragment's view is created.
         // commitNowAllowingStateLoss triggers onCreate but onViewCreated
@@ -669,6 +793,61 @@ class ShortKitBridge(
         return feedRegistry[id]?.get()
     }
 
+    /**
+     * Emit `onRefreshStateChangedPerFeed` with feedId in the payload.
+     * Used by the per-feed [ShortKitFeedFragment.onRefreshStateChanged]
+     * hook wired in [registerFeedFragment]. Mirrors iOS
+     * `ShortKitBridge.swift:74-90` body construction.
+     */
+    private fun emitRefreshPerFeed(feedId: String, state: ShortKitRefreshState) {
+        val params = Arguments.createMap().apply {
+            putString("feedId", feedId)
+            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("onRefreshStateChangedPerFeed", params)
+    }
+
+    /**
+     * Reverse lookup: which registered feedId corresponds to the SDK's
+     * currently-active surface? Returns the empty string when no feed
+     * surface is active or when the active surface isn't a registered
+     * fragment (e.g. host-driven scenario without RN bridge mounting).
+     *
+     * Used by the three delegate-level emit sites
+     * (`onContentTapped`, `onRefreshStateChanged`, `onDidFetchContentItems`)
+     * so multi-feed setups route the callback to the originating
+     * `<ShortKitFeed>` instead of broadcasting to all mounted feeds.
+     *
+     * Mirrors iOS `ShortKitBridge.activeSurfaceFeedId()`
+     * (`react_native_sdk/ios/ShortKitBridge.swift:1174`). Capture this
+     * synchronously at delegate-call time; after any await/post the
+     * active surface may have shifted (user swiped tabs).
+     */
+    fun activeSurfaceFeedId(): String {
+        val active = shortKit?.activeSurface ?: return ""
+        for ((id, ref) in feedRegistry) {
+            if (ref.get() === active) return id
+        }
+        return ""
+    }
+
     fun registerFeed(id: String) {
         // No-op — registerFeedFragment handles drain
     }
@@ -735,6 +914,25 @@ class ShortKitBridge(
         emitEvent.invoke(name, params)
     }
 
+    /**
+     * Emit `onVideoCarouselCellTap` with the active surface's feedId and
+     * the cell-supplied (id, index, pageIndex). Mirrors iOS
+     * ShortKitBridge.swift:94-101.
+     *
+     * Called from the cell's onCellTap closure (installed in
+     * ShortKitFeedFragment) — see Task 5.
+     */
+    internal fun emitVideoCarouselCellTap(itemId: String, index: Int, pageIndex: Int) {
+        val feedId = activeSurfaceFeedId()
+        val params = Arguments.createMap().apply {
+            putString("feedId", feedId)
+            putString("id", itemId)
+            putInt("index", index)
+            putInt("pageIndex", pageIndex)
+        }
+        emitEventOnMain("onVideoCarouselCellTap", params)
+    }
+
     // ------------------------------------------------------------------
     // Player commands
     // ------------------------------------------------------------------
@@ -753,6 +951,24 @@ class ShortKitBridge(
     fun skipToNext() { runOnMain { shortKit?.player?.skipToNext() } }
     fun skipToPrevious() { runOnMain { shortKit?.player?.skipToPrevious() } }
     fun setMuted(muted: Boolean) { runOnMain { shortKit?.player?.setMuted(muted) } }
+
+    /**
+     * Toggle outer feed scroll on every registered feed. Note this
+     * intentionally diverges from iOS: iOS routes the same command only
+     * to the *active* feed (via player.onCommand), but Android fans out
+     * to all registered feeds — including masked-feed underlays. The
+     * user-visible effect is the same (the active feed's scroll is
+     * locked) and fanning out costs nothing, avoiding an active-surface
+     * lookup at this layer. Must run on main: viewPager.isUserInputEnabled
+     * mutates RecyclerView state, and feedRegistry is mutated on main
+     * during register/unregister — concurrent iteration would race.
+     */
+    fun setFeedScrollEnabled(enabled: Boolean) = runOnMain {
+        feedRegistry.values.forEach { ref ->
+            ref.get()?.setFeedScrollEnabled(enabled)
+        }
+    }
+
     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) } }
@@ -762,6 +978,17 @@ class ShortKitBridge(
     }
     fun setMaxBitrate(bitrate: Double) { runOnMain { shortKit?.player?.setMaxBitrate(bitrate.toInt()) } }
 
+    // ---- SHO-15: ShortKitCarousel imperative methods + sync accessors ----
+    // ShortKitCarousel's onMain shim handles cross-thread routing internally,
+    // so we DON'T wrap with bridge.runOnMain — the namespace's threading
+    // contract already routes to main + blocks on the latch when called from
+    // a background thread.
+    fun carouselNext(): Boolean = shortKit?.carousel?.next() ?: false
+    fun carouselPrevious(): Boolean = shortKit?.carousel?.previous() ?: false
+    fun carouselSetActiveIndex(index: Int): Boolean = shortKit?.carousel?.setActiveIndex(index) ?: false
+    fun carouselActiveIndex(): Int = shortKit?.carousel?.activeIndexValue ?: -1
+    fun carouselVideoCount(): Int = shortKit?.carousel?.videoCountValue ?: 0
+
     fun setUserId(userId: String) {
         shortKit?.setUserId(userId)
     }
@@ -1090,10 +1317,16 @@ class ShortKitBridge(
             }
         }
 
-        // Did loop
+        // Did loop — tagged with active surface's feedId. player.didLoop is a
+        // singleton flow on the shared ShortKitPlayer (only one item plays at
+        // a time). The event semantically belongs to whichever feed owns the
+        // active surface; tag with that feedId so JS consumers bound to
+        // specific feeds can filter. Empty string means no active surface
+        // (treat as unknown/global). Mirrors iOS bridge :615-631.
         newScope.launch {
             player.didLoop.collect { event ->
                 val params = Arguments.createMap().apply {
+                    putString("feedId", activeSurfaceFeedId())
                     putString("contentId", event.contentId)
                     putInt("loopCount", event.loopCount)
                 }
@@ -1101,34 +1334,26 @@ class ShortKitBridge(
             }
         }
 
-        // 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
+        // NOTE: the global `player.feedTransition.collect` subscription used
+        // to live here. It's been removed — feed transitions are now emitted
+        // to RN via the per-fragment `fragment.onFeedTransition` closure
+        // wired in `registerFeedFragment` above. This eliminates the cross-
+        // feed routing bug where every mounted <ShortKitFeed> consumer
+        // received every feed's transitions. Mirrors iOS PR #170
+        // ShortKitBridge.swift:633-642.
+        //
+        // `player.sendFeedTransition` is still called by ShortKitFeedFragment
+        // for backward compatibility with native Kotlin SDK consumers that
+        // subscribe to `ShortKitPlayer.feedTransition` directly.
+
+        // Format change — tagged with active surface's feedId. Same reasoning
+        // as onDidLoop: fires from shared player singleton, but semantically
+        // belongs to whichever feed owns the active surface. Mirrors iOS
+        // bridge :671-688.
         newScope.launch {
             player.formatChange.collect { event ->
                 val params = Arguments.createMap().apply {
+                    putString("feedId", activeSurfaceFeedId())
                     putString("contentId", event.contentId)
                     putDouble("fromBitrate", event.fromBitrate.toDouble())
                     putDouble("toBitrate", event.toBitrate.toDouble())

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

@@ -30,6 +30,15 @@ class ShortKitFeedView(context: Context) : FrameLayout(context) {
     var feedId: String? = null
     var startAtItemId: String? = null
     var preloadId: String? = null
+    /**
+     * JSON-encoded `FeedInput[]` from the `feedItems` JS prop. Parsed at
+     * fragment-construction time only — post-mount changes are a no-op
+     * (matches iOS PR #150). Host apps that need post-mount item updates
+     * use the imperative `ShortKit.setFeedItems(feedId, items)` API.
+     *
+     * `preloadId` takes precedence when both are set.
+     */
+    var feedItemsJSON: String? = null
     // Fabric's generated delegate maps an absent boolean prop to the Java
     // primitive false, so Boolean? is always non-null from the bridge. Track
     // whether the prop was explicitly set so we can fall back to the provider
@@ -37,6 +46,62 @@ class ShortKitFeedView(context: Context) : FrameLayout(context) {
     var debugPanel: Boolean = false
     var debugPanelPropSet: Boolean = false
 
+    /**
+     * URL of the thumbnail the host app is already rendering for the item that
+     * will be the first active cell. Looked up synchronously via Glide's cache
+     * (10ms cap; supports expo-image / FastImage clients) and seeded onto the
+     * fragment before its first lifecycle event. Falls back to the existing
+     * patchMissingThumbnailIfNeeded helper on cache miss or timeout.
+     *
+     * Mirrors iOS ShortKitFeedView.seedThumbnailUrl
+     * (react_native_sdk/ios/ShortKitFeedView.swift:28).
+     */
+    var seedThumbnailUrl: String? = null
+
+    /**
+     * Host-driven activation state, set by the `active` JS prop. Defaults to
+     * `true`. Mirrors iOS [`ShortKitFeedView.active`](react_native_sdk/ios/ShortKitFeedView.swift:46).
+     */
+    var active: Boolean = true
+        internal set
+
+    /**
+     * Tracks whether `active` was explicitly set by the host (vs. defaulted).
+     * Same purpose as `debugPanelPropSet` — distinguishes "absent" from "false"
+     * since Fabric maps absent boolean props to the Java primitive `false`.
+     *
+     * Used only by the first-mount race fix in [embedFeedFragmentIfNeeded] to
+     * decide whether a `false` value is a real host intent or a Fabric default.
+     */
+    var activePropSet: Boolean = false
+        internal set
+
+    /**
+     * Set the `active` prop from the bridge. The canonical entry point for
+     * all `active` state transitions — do not mutate the field directly.
+     *
+     * Behavior:
+     * - Always sets `activePropSet = true`.
+     * - On transition while a fragment is embedded:
+     *   - `true → false`: calls `fragment.deactivate()`.
+     *   - `false → true`: calls `fragment.activate()`.
+     * - Returns early if no fragment is yet embedded — the first-mount race
+     *   in [embedFeedFragmentIfNeeded] handles the deferred deactivate case.
+     *
+     * Invoked by [ShortKitFeedViewManager.setActive].
+     */
+    fun setActiveFromBridge(value: Boolean) {
+        val prev = active
+        active = value
+        activePropSet = true
+        val fragment = feedFragment ?: return
+        if (prev && !value) {
+            fragment.deactivate()
+        } else if (!prev && value) {
+            fragment.activate()
+        }
+    }
+
     // -----------------------------------------------------------------------
     // Fragment management
     // -----------------------------------------------------------------------
@@ -140,7 +205,15 @@ class ShortKitFeedView(context: Context) : FrameLayout(context) {
         synchronized(ShortKitBridge.staticPendingFeedViews) {
             ShortKitBridge.staticPendingFeedViews.remove(this)
         }
-        suspendFeedFragment()
+        // Mirror iOS willMove(toWindow:) at react_native_sdk/ios/ShortKitFeedView.swift:91-99 —
+        // suspend only if leaving the window AND the prop says we should be active.
+        // When active=false the host has already driven the fragment into deactivate
+        // (or will once setActiveFromBridge runs), and we mustn't double-suspend.
+        // Default active=true preserves legacy window-inference behavior for hosts
+        // that never set the active prop.
+        if (active) {
+            suspendFeedFragment()
+        }
         super.onDetachedFromWindow()
     }
 
@@ -167,7 +240,11 @@ class ShortKitFeedView(context: Context) : FrameLayout(context) {
                         .beginTransaction()
                         .show(existingFragment)
                         .commitNowAllowingStateLoss()
-                    existingFragment.activate()
+                    // Mirror iOS: only auto-activate if the host's active prop says so.
+                    // Default active=true preserves legacy "always activate on un-hide" behavior.
+                    if (active) {
+                        existingFragment.activate()
+                    }
                 } catch (e: Exception) {
                     Log.e(TAG, "Failed to show feed fragment", e)
                 }
@@ -188,24 +265,58 @@ class ShortKitFeedView(context: Context) : FrameLayout(context) {
 
         var feedConfig = ShortKitBridge.parseFeedConfig(config ?: "{}", context)
 
-        preloadId?.let { id ->
-            val preload = ShortKitBridge.shared?.consumePreload(id)
+        val explicitPreloadId = preloadId
+        val explicitFeedItemsJSON = feedItemsJSON
+        if (explicitPreloadId != null) {
+            val preload = ShortKitBridge.shared?.consumePreload(explicitPreloadId)
             if (preload != null) {
                 feedConfig = feedConfig.copy(preload = preload)
             }
+        } else if (explicitFeedItemsJSON != null) {
+            // Mount-time custom-feed fast-path (SHO-29 / iOS PR #150).
+            // Parse JSON → FeedInput[] → sdk.preloadFeed(items=) which
+            // internally calls FeedPreload.forCustomItems with the SDK's
+            // own scope. Assign to feedConfig.preload BEFORE constructing
+            // the fragment, so FeedPreload.consume() returns synchronously
+            // on the first cell bind. Requires Task 1's sync-payload fix
+            // in FeedPreload.kt.
+            //
+            // Using sdk.preloadFeed(items=) (the public SDK entry point at
+            // ShortKit.kt:232) instead of FeedPreload.forCustomItems
+            // directly — avoids needing to promote internal SDK helpers
+            // for cross-module access from the bridge.
+            val parsed = ShortKitBridge.parseFeedInputs(explicitFeedItemsJSON)
+            if (parsed != null && parsed.isNotEmpty()) {
+                val preload = sdk.preloadFeed(items = parsed)
+                feedConfig = feedConfig.copy(preload = preload)
+            } else {
+                Log.w(TAG, "feedItemsJSON parsed to null/empty — ignoring (config feedSource will drive the fetch path)")
+            }
         }
 
         val fragment = ShortKitFeedFragment.newInstance(sdk, feedConfig, startAtItemId)
 
         val debugPanelEnabled = if (debugPanelPropSet) debugPanel else sdk.debugPanelEnabled
         if (debugPanelEnabled) {
-            fragment.debugPanelFactory = { active, prev, next, lifecycleOwner ->
+            fragment.debugPanelFactory = { activeMetrics, prev, next, lifecycleOwner ->
                 com.shortkit.sdk.debug.DebugPanelView(context).also { panel ->
-                    panel.subscribe(active, prev, next, lifecycleOwner)
+                    panel.subscribe(activeMetrics, prev, next, lifecycleOwner)
                 }
             }
         }
 
+        // SHO-11: seed a thumbnail from the host app's image cache so the first
+        // cell renders with a visible thumbnail from frame zero. Synchronous
+        // Glide lookup (memory-only via 10ms cap) — no network. If null (cache
+        // miss, timeout, or Glide not linked), the existing
+        // patchMissingThumbnailIfNeeded helper handles the fallback at feed-open
+        // time. Mirrors iOS ShortKitFeedView.swift:170-173.
+        seedThumbnailUrl?.let { url ->
+            com.shortkit.sdk.feed.SeedThumbnailResolver.resolveFromCache(context, url)?.let { bitmap ->
+                fragment.seedThumbnail = bitmap
+            }
+        }
+
         try {
             activity.supportFragmentManager
                 .beginTransaction()
@@ -213,6 +324,24 @@ class ShortKitFeedView(context: Context) : FrameLayout(context) {
                 .commitNowAllowingStateLoss()
             this.feedFragment = fragment
 
+            // Android-specific first-mount race: Fabric may have set active=false
+            // BEFORE we got to embed the fragment. The fragment self-claims the
+            // player pool in onResume (ShortKitFeedFragment.kt:2112), so by the
+            // time commitNowAllowingStateLoss returns the fragment is already
+            // active. Retroactively deactivate to honor the host's intent.
+            //
+            // Note: this produces a brief claim-then-yield window (microseconds).
+            // Acceptable for normal use; if a host needs strictly never-active
+            // mounts, the fragment's onResume self-claim would need a managed-mode
+            // flag to suppress (separate ticket).
+            //
+            // activePropSet guard: only fires when the host explicitly set the prop.
+            // Fabric maps absent booleans to Java false, so without this guard
+            // every fragment would deactivate at mount.
+            if (activePropSet && !active) {
+                fragment.deactivate()
+            }
+
             // View.generateViewId() can return IDs that collide with Fabric-
             // managed views (e.g. ReactSurfaceView also gets id=1).  When that
             // happens, FragmentManager.replace() places the fragment view in

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

@@ -35,12 +35,27 @@ class ShortKitFeedViewManager : SimpleViewManager<ShortKitFeedView>() {
         view.preloadId = preloadId
     }
 
+    @ReactProp(name = "feedItemsJSON")
+    fun setFeedItemsJSON(view: ShortKitFeedView, feedItemsJSON: String?) {
+        view.feedItemsJSON = feedItemsJSON
+    }
+
     @ReactProp(name = "debugPanel")
     fun setDebugPanel(view: ShortKitFeedView, debugPanel: Boolean) {
         view.debugPanel = debugPanel
         view.debugPanelPropSet = true
     }
 
+    @ReactProp(name = "active")
+    fun setActive(view: ShortKitFeedView, active: Boolean) {
+        view.setActiveFromBridge(active)
+    }
+
+    @ReactProp(name = "seedThumbnailUrl")
+    fun setSeedThumbnailUrl(view: ShortKitFeedView, url: String?) {
+        view.seedThumbnailUrl = url
+    }
+
     override fun onDropViewInstance(view: ShortKitFeedView) {
         view.destroy()
         super.onDropViewInstance(view)

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

@@ -136,6 +136,11 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
     @ReactMethod
     override fun pause() { bridge?.pause() }
 
+    @ReactMethod
+    override fun setFeedScrollEnabled(enabled: Boolean) {
+        bridge?.setFeedScrollEnabled(enabled)
+    }
+
     @ReactMethod
     override fun seek(seconds: Double) { bridge?.seek(seconds) }
 
@@ -149,28 +154,30 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
     override fun skipToPrevious() { bridge?.skipToPrevious() }
 
     // -----------------------------------------------------------------
-    // Carousel commands — stubs for PR 1.
-    // TODO: PR 2 — replace these stubs with real bridge to ShortKit.activeInstance.get().carousel
+    // Carousel commands — bridge to ShortKit.activeInstance().carousel.
+    // Mirrors iOS RN bridge from PR #136. SHO-15.
+    // Boundary semantics: returns false / -1 / 0 when no ShortKit instance
+    // is active or no fragment is bound, matching iOS `?? false` / `?? nil`
+    // fallbacks via the namespace's onMain shim + null-tolerance.
     // -----------------------------------------------------------------
 
     @ReactMethod(isBlockingSynchronousMethod = true)
-    override fun carouselNext(): Boolean = false
+    override fun carouselNext(): Boolean = bridge?.carouselNext() ?: false
 
     @ReactMethod(isBlockingSynchronousMethod = true)
-    override fun carouselPrevious(): Boolean = false
+    override fun carouselPrevious(): Boolean = bridge?.carouselPrevious() ?: false
 
     @ReactMethod(isBlockingSynchronousMethod = true)
-    override fun carouselSetActiveIndex(index: Double): Boolean = false
-
-    // Carousel accessors — stubs for PR 1.
-    // onCarouselActiveVideoCompleted emitter intentionally unwired — never fires on Android in PR 1.
-    // PR 2 will subscribe to ShortKit.activeInstance.get().carousel.activeVideoCompleted.
+    override fun carouselSetActiveIndex(index: Double): Boolean =
+        bridge?.carouselSetActiveIndex(index.toInt()) ?: false
 
     @ReactMethod(isBlockingSynchronousMethod = true)
-    override fun getCarouselActiveIndex(): Double = -1.0
+    override fun getCarouselActiveIndex(): Double =
+        (bridge?.carouselActiveIndex() ?: -1).toDouble()
 
     @ReactMethod(isBlockingSynchronousMethod = true)
-    override fun getCarouselVideoCount(): Double = 0.0
+    override fun getCarouselVideoCount(): Double =
+        (bridge?.carouselVideoCount() ?: 0).toDouble()
 
     @ReactMethod
     override fun setMuted(muted: Boolean) { bridge?.setMuted(muted) }
@@ -326,6 +333,7 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
                 "onContentTapped" -> emitOnContentTapped(params)
                 "onDismiss" -> emitOnDismiss(params)
                 "onRefreshStateChanged" -> emitOnRefreshStateChanged(params)
+                "onRefreshStateChangedPerFeed" -> emitOnRefreshStateChangedPerFeed(params)
                 "onDidFetchContentItems" -> emitOnDidFetchContentItems(params)
                 "onFeedReady" -> emitOnFeedReady(params)
                 "onOverlayActiveChanged" -> emitOnOverlayActiveChanged(params)
@@ -341,8 +349,10 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
                 "onCarouselActiveImageChanged" -> emitOnCarouselActiveImageChanged(params)
                 "onCarouselItemChanged" -> emitOnCarouselItemChanged(params)
                 "onVideoCarouselActiveVideoChanged" -> emitOnVideoCarouselActiveVideoChanged(params)
+                "onVideoCarouselCellTap" -> emitOnVideoCarouselCellTap(params)
                 "onVideoCarouselItemChanged" -> emitOnVideoCarouselItemChanged(params)
                 "onCarouselActiveVideoCompleted" -> emitOnCarouselActiveVideoCompleted(params)
+                "onVideoCarouselCellTap" -> emitOnVideoCarouselCellTap(params)
                 else -> {
                     android.util.Log.w("SK:Module", "sendEvent: unknown event name '$name', using legacy emitter")
                     reactApplicationContext