@shortkitsdk/react-native 0.2.34 → 0.2.36

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

@@ -4,6 +4,7 @@ import android.content.Context
 import android.os.Bundle
 import android.os.Handler
 import android.os.Looper
+import android.view.MotionEvent
 import android.widget.FrameLayout
 import com.facebook.react.ReactApplication
 import com.facebook.react.bridge.Arguments
@@ -11,6 +12,7 @@ import com.facebook.react.interfaces.fabric.ReactSurface
 import com.facebook.react.runtime.ReactSurfaceImpl
 import com.shortkit.sdk.ShortKitPlayer
 import com.shortkit.sdk.model.ContentItem
+import com.shortkit.sdk.model.FeedScrollPhase
 import com.shortkit.sdk.model.PlayerState
 import com.shortkit.sdk.model.VideoCarouselItem
 import com.shortkit.sdk.overlay.VideoCarouselOverlay
@@ -40,9 +42,17 @@ class ReactVideoCarouselOverlayHost(context: Context) : FrameLayout(context), Vi
         const val TAG = "SK:VidCarouselHost"
     }
 
-    // Touch handling: this view sits below the ViewPager2 in z-order.
-    // The cell's root FrameLayout dispatches taps to this overlay when the
-    // ViewPager2 doesn't consume them (i.e. non-scroll touches).
+    // Touch handling: this view sits ABOVE the ViewPager2 in z-order
+    // (overlay_container is the last child of cell_video_carousel.xml's
+    // root FrameLayout). RN's pointerEvents="box-none" lets the React
+    // tree claim DOWN only for interactive children; the inner pager
+    // sees DOWN for empty-area touches via standard z-order dispatch.
+    //
+    // For touches that DO land on interactive overlay children — chiefly
+    // the scrubber drag — we additionally call requestDisallowIntercept
+    // on the parent chain so the inner carousel pager and the outer feed
+    // pager don't intercept on subsequent MOVE events. Mirrors the same
+    // idiom used in ReactOverlayHost for the regular feed overlay.
 
     // ------------------------------------------------------------------
     // Configuration
@@ -65,6 +75,62 @@ class ReactVideoCarouselOverlayHost(context: Context) : FrameLayout(context), Vi
     /** Cached carouselItem JSON — updateInitProps replaces all props, doesn't merge. */
     private var carouselItemJSON: String? = null
 
+    /**
+     * Currently configured carousel item — used to detect item transitions so
+     * we can emit an event instead of triggering a full Fabric remount, and
+     * (SHO-15) to surface-filter onCarouselActiveVideoCompleted events so
+     * only the host bound to the just-completed video's carousel emits.
+     */
+    internal var currentCarouselItem: VideoCarouselItem? = null
+        private set
+
+    /**
+     * Whether initial props have been pushed at least once. First mount goes
+     * through applySurfaceProps + emit (matches iOS asymmetry); subsequent
+     * different-item rebinds emit only.
+     */
+    internal var hasPushedInitialProps: Boolean = false
+        private set
+
+    /**
+     * Tracks active drag phase. While true, per-frame player-state emissions
+     * (playerState, isMuted, time) are suppressed; emitFullState() re-syncs
+     * cached values on settle.
+     */
+    internal var isDragging: Boolean = false
+        private set
+
+    /** Test-only setter for [isDragging]. */
+    internal var isDraggingForTest: Boolean
+        get() = isDragging
+        set(value) { isDragging = value }
+
+    /**
+     * Test seam for emit-event interception. Production uses the default;
+     * tests overwrite to capture emitted (name, params) pairs.
+     */
+    internal var emitEvent: (String, com.facebook.react.bridge.WritableMap) -> Unit =
+        { name, params -> ShortKitBridge.shared?.emitEvent(name, params) }
+
+    /**
+     * Test seam for WritableMap creation. Production uses Arguments.createMap()
+     * which requires JNI; tests overwrite with JavaOnlyMap() to avoid Robolectric
+     * NativeLoader issues. Same pattern as ReactCarouselOverlayHost.
+     */
+    internal var createMap: () -> com.facebook.react.bridge.WritableMap =
+        { com.facebook.react.bridge.Arguments.createMap() }
+
+    /**
+     * Test seam for ReactSurface creation. Production resolves from ReactHost.
+     * Tests inject a stub so the surface is non-null after applySurfaceProps()
+     * and hasPushedInitialProps can flip. Same pattern as ReactCarouselOverlayHost.
+     */
+    internal var createSurface: (moduleName: String, initialProps: Bundle?) -> ReactSurface? =
+        { moduleName, initialProps ->
+            (context.applicationContext as? ReactApplication)?.reactHost
+                ?.createSurface(context, moduleName, initialProps)
+        }
+
     // Player state
     private var player: ShortKitPlayer? = null
     private var isActive: Boolean = false
@@ -76,6 +142,17 @@ class ReactVideoCarouselOverlayHost(context: Context) : FrameLayout(context), Vi
     private var timeDirty: Boolean = false
     private val handler = Handler(Looper.getMainLooper())
     private var timeCoalesceRunnable: Runnable? = null
+
+    /**
+     * Bottom strip in which a DOWN signals "interactive overlay drag pending"
+     * (chiefly the scrubber). Width = scrubberTouchArea height (40dp) plus the
+     * sample's BOTTOM_SAFE_AREA (100dp) = 140dp. Matches the JS scrubberTouchArea
+     * geometry in NewsVideoCarouselOverlay.tsx; future overlays with non-default
+     * BOTTOM_SAFE_AREA will need a prop to communicate this down.
+     */
+    private val interactiveBottomStripPx: Int
+        get() = (140 * resources.displayMetrics.density).toInt()
+
     private var flowScope: CoroutineScope? = null
 
     // ------------------------------------------------------------------
@@ -129,30 +206,49 @@ class ReactVideoCarouselOverlayHost(context: Context) : FrameLayout(context), Vi
     // ------------------------------------------------------------------
 
     override fun configure(item: VideoCarouselItem) {
+        val isSameItem = item.id == currentCarouselItem?.id
+        currentCarouselItem = item
+
         isActive = false
+        isDragging = false
         timeDirty = false
         stopTimeCoalescing()
         cachedCurrentTime = 0.0
         cachedDuration = 0.0
         cachedBuffered = 0.0
         cachedPlayerState = "idle"
+        // Seed cachedIsMuted from the SDK's current value so the new
+        // surface's initialProps reflect actual mute state. The flow
+        // subscription (resubscribeToPlayer) will keep it in sync going
+        // forward, but its first emission can race with a host tap on the
+        // new cell, leading to a stale-true bug where the toggle target is
+        // computed wrong.
+        player?.isMuted?.value?.let { cachedIsMuted = it }
 
         val json = Json.encodeToString(item)
         carouselItemJSON = json
-        val bundle = Bundle().apply {
-            putString("surfaceId", surfaceId)
-            putString("carouselItem", json)
-            putBoolean("isActive", false)
-            putString("playerState", "idle")
-            putBoolean("isMuted", cachedIsMuted)
-            if (item.videos.isNotEmpty()) {
-                putString("activeVideo", ShortKitBridge.serializeContentItemToJSON(item.videos.first()))
-                putInt("activeVideoIndex", 0)
+
+        if (!hasPushedInitialProps) {
+            // First mount: BOTH applySurfaceProps AND emit. Matches iOS asymmetry
+            // at ReactVideoCarouselOverlayHost.swift:127-138.
+            applySurfaceProps(buildInitialPropsBundle(item, json))
+            // Only flip the flag if surface was actually created. If reactHost was
+            // null (createSurface seam returned null), surface remains null and
+            // pendingProps is parked — stay in "first mount" mode so the next
+            // configure() retries. Mirrors iOS pattern.
+            if (surface != null) {
+                hasPushedInitialProps = true
             }
+            // Emit fires regardless of surface state — external subscribers
+            // should see the item update even when the in-surface listener
+            // isn't yet wired. iOS does the same at :135-137.
+            emitItemChanged(item, json)
+        } else if (!isSameItem) {
+            emitItemChanged(item, json)
         }
-        applySurfaceProps(bundle)
+        // else: same item rebind — no emit, no Fabric prop push.
 
-        // Pre-size the surface view
+        // Pre-size the surface view (existing logic, unchanged).
         val parentView = parent as? android.view.View
         val w = if (width > 0) width
                 else if (parentView != null && parentView.width > 0) parentView.width
@@ -163,6 +259,58 @@ class ReactVideoCarouselOverlayHost(context: Context) : FrameLayout(context), Vi
         measureAndLayoutSurfaceView(w, h)
     }
 
+    /**
+     * Build the initial-properties bundle for first-mount setProperties path.
+     * Mirrors iOS buildInitialProps(item:json:) at
+     * ReactVideoCarouselOverlayHost.swift:143-158.
+     *
+     * Note: when videos is empty, activeVideo + activeVideoIndex keys are
+     * OMITTED from the bundle (matches iOS first-mount behavior). The
+     * emit path uses a separate convention — it emits putNull("activeVideo")
+     * to match iOS NSNull(). See emitItemChanged() below.
+     */
+    private fun buildInitialPropsBundle(item: VideoCarouselItem, json: String): Bundle =
+        Bundle().apply {
+            putString("surfaceId", surfaceId)
+            putString("carouselItem", json)
+            putBoolean("isActive", false)
+            putString("playerState", "idle")
+            putBoolean("isMuted", cachedIsMuted)
+            if (item.videos.isNotEmpty()) {
+                putString("activeVideo", ShortKitBridge.serializeContentItemToJSON(item.videos.first()))
+                putInt("activeVideoIndex", 0)
+            }
+        }
+
+    /**
+     * Emit onVideoCarouselItemChanged for React diff on cell reuse.
+     * Mirrors iOS emitItemChanged(item:json:) at
+     * ReactVideoCarouselOverlayHost.swift:162-183.
+     *
+     * Empty-videos: uses putNull("activeVideo") — NOT key omission. This
+     * matches iOS NSNull() and avoids the empty-string-falsy-check bug
+     * documented at iOS :175-180.
+     */
+    private fun emitItemChanged(item: VideoCarouselItem, json: String) {
+        val params = createMap().apply {
+            putString("surfaceId", surfaceId)
+            putString("carouselItem", json)
+            putBoolean("isActive", false)
+            putString("playerState", "idle")
+            putBoolean("isMuted", cachedIsMuted)
+            putInt("activeVideoIndex", 0)
+            if (item.videos.isNotEmpty()) {
+                putString(
+                    "activeVideo",
+                    ShortKitBridge.serializeContentItemToJSON(item.videos.first()),
+                )
+            } else {
+                putNull("activeVideo")
+            }
+        }
+        emitEvent("onVideoCarouselItemChanged", params)
+    }
+
     override fun updateActiveVideo(index: Int, item: ContentItem) {
         // Only emit when active — matches ReactOverlayHost pattern.
         // During initial setup, configure() sets the first video via surface props.
@@ -214,12 +362,12 @@ class ReactVideoCarouselOverlayHost(context: Context) : FrameLayout(context), Vi
         scope.launch {
             player.playerState.collect { state ->
                 cachedPlayerState = ShortKitBridge.playerStateString(state)
-                if (isActive) {
-                    val params = Arguments.createMap().apply {
+                if (isActive && !isDragging) {
+                    val params = createMap().apply {
                         putString("surfaceId", surfaceId)
                         putString("playerState", cachedPlayerState)
                     }
-                    ShortKitBridge.shared?.emitEvent("onOverlayPlayerStateChanged", params)
+                    emitEvent("onOverlayPlayerStateChanged", params)
                 }
             }
         }
@@ -227,12 +375,12 @@ class ReactVideoCarouselOverlayHost(context: Context) : FrameLayout(context), Vi
         scope.launch {
             player.isMuted.collect { muted ->
                 cachedIsMuted = muted
-                if (isActive) {
-                    val params = Arguments.createMap().apply {
+                if (isActive && !isDragging) {
+                    val params = createMap().apply {
                         putString("surfaceId", surfaceId)
                         putBoolean("isMuted", cachedIsMuted)
                     }
-                    ShortKitBridge.shared?.emitEvent("onOverlayMutedChanged", params)
+                    emitEvent("onOverlayMutedChanged", params)
                 }
             }
         }
@@ -242,11 +390,56 @@ class ReactVideoCarouselOverlayHost(context: Context) : FrameLayout(context), Vi
                 cachedCurrentTime = time.currentMs / 1000.0
                 cachedDuration = time.durationMs / 1000.0
                 cachedBuffered = time.bufferedMs / 1000.0
-                if (isActive) {
+                if (isActive && !isDragging) {
                     timeDirty = true
                 }
             }
         }
+
+        scope.launch {
+            player.feedScrollPhase.collect { phase ->
+                when (phase) {
+                    is FeedScrollPhase.Dragging -> {
+                        isDragging = true
+                        stopTimeCoalescing()
+                    }
+                    is FeedScrollPhase.Settled -> {
+                        val wasDragging = isDragging
+                        isDragging = false
+                        if (isActive) {
+                            startTimeCoalescing()
+                            if (wasDragging) emitFullState()
+                        }
+                    }
+                }
+            }
+        }
+
+        // SHO-15: subscribe to ShortKitCarousel.activeVideoCompleted and emit
+        // onCarouselActiveVideoCompleted to JS. Surface-filtering: only the
+        // currently-active host (one per active carousel cell) emits, AND the
+        // completed item's id must belong to this host's bound carousel.
+        scope.launch {
+            val carousel = com.shortkit.sdk.ShortKit.activeInstance()?.carousel ?: return@launch
+            carousel.activeVideoCompleted.collect { event ->
+                if (!isActive) return@collect
+                val ourCarousel = currentCarouselItem ?: return@collect
+                val belongs = ourCarousel.videos.any { it.id == event.contentItem.id }
+                if (!belongs) return@collect
+
+                val feedId = ShortKitBridge.shared?.activeSurfaceFeedId() ?: ""
+                val params = Arguments.createMap().apply {
+                    putString("feedId", feedId)
+                    putString("surfaceId", surfaceId)
+                    putString("contentItem", ShortKitBridge.serializeContentItemToJSON(event.contentItem))
+                    putInt("indexInCarousel", event.indexInCarousel)
+                    putString("carouselItem", ShortKitBridge.serializeVideoCarouselItemToJSON(event.carouselItem))
+                    putBoolean("wasLast", event.wasLast)
+                    putBoolean("willAutoAdvance", event.willAutoAdvance)
+                }
+                ShortKitBridge.shared?.emitEvent("onCarouselActiveVideoCompleted", params)
+            }
+        }
     }
 
     // ------------------------------------------------------------------
@@ -323,6 +516,24 @@ class ReactVideoCarouselOverlayHost(context: Context) : FrameLayout(context), Vi
         }
     }
 
+    /**
+     * Pre-dispatch hook so a DOWN inside the scrubber strip immediately tells
+     * every ancestor (the cell, the inner carousel pager, and the outer feed
+     * pager) to stop intercepting touch events. Without this, the inner
+     * carousel pager's horizontal-pan recognizer and the outer feed pager's
+     * vertical-pan recognizer can grab a scrubber drag mid-stream.
+     *
+     * Mirrors ReactOverlayHost.onInterceptTouchEvent for the regular feed.
+     */
+    override fun onInterceptTouchEvent(ev: MotionEvent): Boolean {
+        if (ev.action == MotionEvent.ACTION_DOWN && height > 0) {
+            if (ev.y > height - interactiveBottomStripPx) {
+                parent?.requestDisallowInterceptTouchEvent(true)
+            }
+        }
+        return super.onInterceptTouchEvent(ev)
+    }
+
     override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
         super.onSizeChanged(w, h, oldw, oldh)
         if (w > 0 && h > 0) {
@@ -380,17 +591,18 @@ class ReactVideoCarouselOverlayHost(context: Context) : FrameLayout(context), Vi
     private fun createSurfaceIfNeeded() {
         if (surface != null) return
 
-        val reactHost = (context.applicationContext as? ReactApplication)?.reactHost
-        if (reactHost == null) {
-            android.util.Log.e(TAG, "createSurface FAILED: reactHost is null")
-            return
-        }
         val moduleName = "ShortKitVideoCarouselOverlay_$videoCarouselOverlayName"
 
         val initialProps = pendingProps
         pendingProps = null
 
-        val newSurface = reactHost.createSurface(context, moduleName, initialProps)
+        val newSurface = createSurface(moduleName, initialProps)
+        if (newSurface == null) {
+            android.util.Log.e(TAG, "createSurface FAILED: reactHost is null")
+            // Restore pending props so a future createSurfaceIfNeeded() can retry.
+            if (initialProps != null) pendingProps = initialProps
+            return
+        }
         surface = newSurface
 
         newSurface.view?.let { surfaceView ->
@@ -423,6 +635,7 @@ class ReactVideoCarouselOverlayHost(context: Context) : FrameLayout(context), Vi
         flowScope?.cancel()
         flowScope = null
         isActive = false
+        currentCarouselItem = null
         stopTimeCoalescing()
         if (surface?.isRunning == true) {
             surface?.stop()

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

@@ -76,6 +76,25 @@ 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 [ContentItem] to a JSON string for bridge transport.
          */
@@ -349,7 +368,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 +554,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 +574,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 +600,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 +668,25 @@ 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)
+        }
 
         // Replay buffered operations after the fragment's view is created.
         // commitNowAllowingStateLoss triggers onCreate but onViewCreated
@@ -669,6 +716,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 +837,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 +874,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 +901,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)
     }