@shortkitsdk/react-native 0.2.35 → 0.2.37

package/android/src/test/java/com/shortkit/reactnative/ReactCarouselOverlayHostEmitTest.kt

@@ -0,0 +1,134 @@
+package com.shortkit.reactnative
+
+import android.content.Context
+import android.os.Bundle
+import android.view.ViewGroup
+import androidx.test.core.app.ApplicationProvider
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.interfaces.TaskInterface
+import com.facebook.react.interfaces.fabric.ReactSurface
+import com.shortkit.sdk.model.CarouselImage
+import com.shortkit.sdk.model.ImageCarouselItem
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import java.util.concurrent.TimeUnit
+
+/**
+ * Tests SHO-8 emit-on-change gating in ReactCarouselOverlayHost.
+ *
+ * Behavior under test (mirrors iOS ReactCarouselOverlayHost.swift:132-145):
+ *   - First configure() with item A → applySurfaceProps path; no emit.
+ *   - Second configure() with same item A → no emit, no setProperties.
+ *   - Second configure() with different item B → emit onCarouselItemChanged
+ *     with payload { surfaceId, item, isActive: false, activeImageIndex: 0 }.
+ */
+@RunWith(RobolectricTestRunner::class)
+class ReactCarouselOverlayHostEmitTest {
+
+    /** No-op TaskInterface returned by stub surface lifecycle methods. */
+    private object NoOpTask : TaskInterface<Void> {
+        override fun waitForCompletion() = Unit
+        override fun waitForCompletion(duration: Long, timeUnit: TimeUnit): Boolean = true
+        override fun getResult(): Void? = null
+        override fun getError(): Exception? = null
+        override fun isCompleted(): Boolean = true
+        override fun isCancelled(): Boolean = false
+        override fun isFaulted(): Boolean = false
+    }
+
+    /**
+     * Minimal ReactSurface stub for Robolectric tests. ApplicationProvider does
+     * not supply a ReactApplication, so createSurfaceIfNeeded() would normally
+     * fail silently with reactHost == null. The createSurface seam lets tests
+     * inject this stub so surface != null after pushProps(), allowing
+     * hasPushedInitialProps to flip correctly (the bug-fix gate under test).
+     *
+     * isRunning is false so applySurfaceProps() calls start() (no-op here) and
+     * the updateInitProps cast to ReactSurfaceImpl is a safe no-op via `as?`.
+     */
+    private class StubReactSurface(private val ctx: Context) : ReactSurface {
+        override val surfaceID: Int = 0
+        override val moduleName: String = "StubSurface"
+        override val isRunning: Boolean = false
+        override val view: ViewGroup? = null
+        override val context: Context get() = ctx
+        override fun prerender(): TaskInterface<Void> = NoOpTask
+        override fun start(): TaskInterface<Void> = NoOpTask
+        override fun stop(): TaskInterface<Void> = NoOpTask
+        override fun clear() = Unit
+        override fun detach() = Unit
+    }
+
+    private fun makeHost(): ReactCarouselOverlayHost {
+        val ctx = ApplicationProvider.getApplicationContext<Context>()
+        return ReactCarouselOverlayHost(ctx).also {
+            // JavaOnlyMap is a pure-Java WritableMap that avoids the JNI init
+            // requirement of WritableNativeMap in Robolectric unit tests.
+            it.createMap = { com.facebook.react.bridge.JavaOnlyMap() }
+            // Inject a stub surface so createSurfaceIfNeeded() succeeds and
+            // hasPushedInitialProps flips after the first configure().
+            it.createSurface = { _, _ -> StubReactSurface(ctx) }
+        }
+    }
+
+    private fun item(id: String) = ImageCarouselItem(
+        id = id,
+        images = listOf(CarouselImage(url = "https://example.com/a.jpg", alt = null)),
+    )
+
+    @Test
+    fun firstConfigureSetsHasPushedAndCurrentItemNoEmit() {
+        val host = makeHost()
+        val emitted = mutableListOf<Pair<String, WritableMap>>()
+        host.emitEvent = { name, params -> emitted.add(name to params) }
+
+        host.configure(item("A"))
+
+        assertEquals("A", host.currentItemId)
+        assertTrue(host.hasPushedInitialProps)
+        assertTrue("first mount must not emit", emitted.isEmpty())
+    }
+
+    @Test
+    fun sameItemConfigureIsNoOpAfterFirstMount() {
+        val host = makeHost()
+        host.configure(item("A"))
+        val emitted = mutableListOf<Pair<String, WritableMap>>()
+        host.emitEvent = { name, params -> emitted.add(name to params) }
+
+        host.configure(item("A"))
+
+        assertEquals("A", host.currentItemId)
+        assertTrue("same item must not emit", emitted.isEmpty())
+    }
+
+    @Test
+    fun differentItemEmitsCarouselItemChanged() {
+        val host = makeHost()
+        host.configure(item("A"))
+        val emitted = mutableListOf<Pair<String, WritableMap>>()
+        host.emitEvent = { name, params -> emitted.add(name to params) }
+
+        host.configure(item("B"))
+
+        assertEquals("B", host.currentItemId)
+        assertEquals(1, emitted.size)
+        assertEquals("onCarouselItemChanged", emitted[0].first)
+        val params = emitted[0].second
+        assertEquals(host.surfaceId, params.getString("surfaceId"))
+        assertFalse(params.getBoolean("isActive"))
+        assertEquals(0, params.getInt("activeImageIndex"))
+        // `item` is a JSON string of the ImageCarouselItem; assert it contains
+        // the new id. Payload-shape correctness is covered by the cross-platform
+        // JS subscriber's destructuring, not asserted here.
+        val itemJson = params.getString("item")
+        assertTrue(
+            "item JSON should contain id=B but was: $itemJson",
+            itemJson?.contains("\"id\":\"B\"") == true,
+        )
+    }
+}

package/android/src/test/java/com/shortkit/reactnative/ReactOverlayHostDragTest.kt

@@ -0,0 +1,45 @@
+package com.shortkit.reactnative
+
+import androidx.test.core.app.ApplicationProvider
+import org.junit.Assert.assertFalse
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+
+/**
+ * Tests SHO-9 drag-phase field on ReactOverlayHost.
+ * The full state-machine wiring (flow → field, emissions gated, full
+ * state on settle) is verified via the manual / instrumented test in
+ * the spec test plan. This test verifies the field's existence and
+ * resettability via configure().
+ */
+@RunWith(RobolectricTestRunner::class)
+class ReactOverlayHostDragTest {
+
+    private fun makeHost() = ReactOverlayHost(
+        ApplicationProvider.getApplicationContext()
+    )
+
+    @Test
+    fun isDraggingDefaultsFalse() {
+        val host = makeHost()
+        assertFalse(host.isDragging)
+    }
+
+    @Test
+    fun configureResetsIsDragging() {
+        val host = makeHost()
+        host.isDraggingForTest = true
+        host.configure(makeContentItem("A"))
+        assertFalse(host.isDragging)
+    }
+
+    private fun makeContentItem(id: String) = com.shortkit.sdk.model.ContentItem(
+        id = id,
+        title = "t",
+        duration = 5.0,
+        streamingUrl = "https://example.com/$id.m3u8",
+        thumbnailUrl = "https://example.com/$id.jpg",
+        captionTracks = emptyList(),
+    )
+}

package/android/src/test/java/com/shortkit/reactnative/ReactVideoCarouselOverlayHostDragTest.kt

@@ -0,0 +1,69 @@
+package com.shortkit.reactnative
+
+import androidx.test.core.app.ApplicationProvider
+import com.facebook.react.bridge.JavaOnlyMap
+import com.shortkit.sdk.model.VideoCarouselItem
+import org.junit.Assert.assertFalse
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+
+/**
+ * Tests SHO-9 drag-phase field on ReactVideoCarouselOverlayHost.
+ * The full state-machine wiring requires a ShortKitPlayer instance with
+ * controllable flows; verified via manual / instrumented testing per the
+ * spec test plan. This test verifies the field's existence and reset
+ * behavior on configure().
+ *
+ * configure() always calls emitItemChanged(), so the createMap and
+ * createSurface seams must be injected here too (same as the emit test).
+ */
+@RunWith(RobolectricTestRunner::class)
+class ReactVideoCarouselOverlayHostDragTest {
+
+    private fun makeHost(): ReactVideoCarouselOverlayHost {
+        val host = ReactVideoCarouselOverlayHost(ApplicationProvider.getApplicationContext())
+        host.createMap = { JavaOnlyMap() }
+        // Stub surface so hasPushedInitialProps can flip and configure()
+        // doesn't retry on every call due to null surface.
+        host.createSurface = { _, _ ->
+            // Re-use the same stub shape from the emit test — no-arg style.
+            object : com.facebook.react.interfaces.fabric.ReactSurface {
+                override val surfaceID: Int = 0
+                override val moduleName: String = "StubSurface"
+                override val isRunning: Boolean = false
+                override val view: android.view.ViewGroup? = null
+                override val context: android.content.Context
+                    get() = ApplicationProvider.getApplicationContext()
+                override fun prerender() = object : com.facebook.react.interfaces.TaskInterface<Void> {
+                    override fun waitForCompletion() = Unit
+                    override fun waitForCompletion(d: Long, u: java.util.concurrent.TimeUnit) = true
+                    override fun getResult(): Void? = null
+                    override fun getError(): Exception? = null
+                    override fun isCompleted() = true
+                    override fun isCancelled() = false
+                    override fun isFaulted() = false
+                }
+                override fun start() = prerender()
+                override fun stop() = prerender()
+                override fun clear() = Unit
+                override fun detach() = Unit
+            }
+        }
+        return host
+    }
+
+    @Test
+    fun isDraggingDefaultsFalse() {
+        val host = makeHost()
+        assertFalse(host.isDragging)
+    }
+
+    @Test
+    fun configureResetsIsDragging() {
+        val host = makeHost()
+        host.isDraggingForTest = true
+        host.configure(VideoCarouselItem(id = "A", videos = emptyList()))
+        assertFalse(host.isDragging)
+    }
+}

package/android/src/test/java/com/shortkit/reactnative/ReactVideoCarouselOverlayHostEmitTest.kt

@@ -0,0 +1,144 @@
+package com.shortkit.reactnative
+
+import android.content.Context
+import android.os.Bundle
+import android.view.ViewGroup
+import androidx.test.core.app.ApplicationProvider
+import com.facebook.react.bridge.JavaOnlyMap
+import com.facebook.react.bridge.ReadableType
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.interfaces.TaskInterface
+import com.facebook.react.interfaces.fabric.ReactSurface
+import com.shortkit.sdk.model.ContentItem
+import com.shortkit.sdk.model.VideoCarouselItem
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import java.util.concurrent.TimeUnit
+
+/**
+ * Tests SHO-8 emit-on-change gating in ReactVideoCarouselOverlayHost,
+ * including the iOS first-mount asymmetry where BOTH setProperties AND
+ * emitItemChanged are called on first mount (matches iOS at
+ * ReactVideoCarouselOverlayHost.swift:127-138).
+ */
+@RunWith(RobolectricTestRunner::class)
+class ReactVideoCarouselOverlayHostEmitTest {
+
+    /** No-op TaskInterface returned by stub surface lifecycle methods. */
+    private object NoOpTask : TaskInterface<Void> {
+        override fun waitForCompletion() = Unit
+        override fun waitForCompletion(duration: Long, timeUnit: TimeUnit): Boolean = true
+        override fun getResult(): Void? = null
+        override fun getError(): Exception? = null
+        override fun isCompleted(): Boolean = true
+        override fun isCancelled(): Boolean = false
+        override fun isFaulted(): Boolean = false
+    }
+
+    /**
+     * Minimal ReactSurface stub for Robolectric tests. ApplicationProvider does
+     * not supply a ReactApplication, so createSurfaceIfNeeded() would normally
+     * fail silently with reactHost == null. The createSurface seam lets tests
+     * inject this stub so surface != null after applySurfaceProps(), allowing
+     * hasPushedInitialProps to flip correctly.
+     *
+     * isRunning is false so applySurfaceProps() calls start() (no-op here) and
+     * the updateInitProps cast to ReactSurfaceImpl is a safe no-op via `as?`.
+     */
+    private class StubReactSurface : ReactSurface {
+        private val ctx: Context = ApplicationProvider.getApplicationContext()
+        override val surfaceID: Int = 0
+        override val moduleName: String = "StubSurface"
+        override val isRunning: Boolean = false
+        override val view: ViewGroup? = null
+        override val context: Context get() = ctx
+        override fun prerender(): TaskInterface<Void> = NoOpTask
+        override fun start(): TaskInterface<Void> = NoOpTask
+        override fun stop(): TaskInterface<Void> = NoOpTask
+        override fun clear() = Unit
+        override fun detach() = Unit
+    }
+
+    private fun makeHost(): ReactVideoCarouselOverlayHost {
+        val host = ReactVideoCarouselOverlayHost(ApplicationProvider.getApplicationContext())
+        host.createMap = { JavaOnlyMap() }
+        // Inject a stub surface so hasPushedInitialProps can flip in tests.
+        // Same pattern as Task 1's ReactCarouselOverlayHost — see commit 6e5e1dce.
+        host.createSurface = { _, _ -> StubReactSurface() }
+        return host
+    }
+
+    private fun video(id: String) = ContentItem(
+        id = id,
+        title = "t",
+        duration = 5.0,
+        streamingUrl = "https://example.com/$id.m3u8",
+        thumbnailUrl = "https://example.com/$id.jpg",
+        captionTracks = emptyList(),
+    )
+
+    private fun item(id: String, videoCount: Int = 1) = VideoCarouselItem(
+        id = id,
+        videos = (0 until videoCount).map { video("$id-$it") },
+    )
+
+    @Test
+    fun firstConfigureBothPushesAndEmits() {
+        val host = makeHost()
+        val emitted = mutableListOf<Pair<String, WritableMap>>()
+        host.emitEvent = { name, params -> emitted.add(name to params) }
+
+        host.configure(item("A"))
+
+        assertEquals("A", host.currentCarouselItem?.id)
+        assertTrue(host.hasPushedInitialProps)
+        assertEquals(1, emitted.size)
+        assertEquals("onVideoCarouselItemChanged", emitted[0].first)
+    }
+
+    @Test
+    fun sameItemConfigureIsNoOpAfterFirstMount() {
+        val host = makeHost()
+        host.configure(item("A"))
+        val emitted = mutableListOf<Pair<String, WritableMap>>()
+        host.emitEvent = { name, params -> emitted.add(name to params) }
+
+        host.configure(item("A"))
+
+        assertTrue("same item must not emit", emitted.isEmpty())
+    }
+
+    @Test
+    fun differentItemEmitsOnly() {
+        val host = makeHost()
+        host.configure(item("A"))
+        val emitted = mutableListOf<Pair<String, WritableMap>>()
+        host.emitEvent = { name, params -> emitted.add(name to params) }
+
+        host.configure(item("B"))
+
+        assertEquals("B", host.currentCarouselItem?.id)
+        assertEquals(1, emitted.size)
+        assertEquals("onVideoCarouselItemChanged", emitted[0].first)
+        val params = emitted[0].second
+        assertEquals(host.surfaceId, params.getString("surfaceId"))
+    }
+
+    @Test
+    fun emptyVideosUsesNullSentinelForActiveVideo() {
+        val host = makeHost()
+        host.configure(item("A", videoCount = 0))
+        val emitted = mutableListOf<Pair<String, WritableMap>>()
+        host.emitEvent = { name, params -> emitted.add(name to params) }
+
+        host.configure(item("B", videoCount = 0))
+
+        // Per spec: empty videos must use putNull, NOT key absent.
+        // iOS uses NSNull at ReactVideoCarouselOverlayHost.swift:179.
+        val params = emitted[0].second
+        assertEquals(ReadableType.Null, params.getType("activeVideo"))
+    }
+}

package/android/src/test/java/com/shortkit/reactnative/ShortKitFeedViewActivePropTest.kt

@@ -0,0 +1,57 @@
+package com.shortkit.reactnative
+
+import androidx.test.core.app.ApplicationProvider
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+
+/**
+ * Tests the `active` prop state machine on ShortKitFeedView.
+ *
+ * Covers:
+ *   - Default state (active=true, activePropSet=false)
+ *   - First-mount race precondition (active=false set before embed)
+ *   - activePropSet flips on every call
+ */
+@RunWith(RobolectricTestRunner::class)
+class ShortKitFeedViewActivePropTest {
+
+    private fun makeView() = ShortKitFeedView(
+        ApplicationProvider.getApplicationContext()
+    )
+
+    @Test
+    fun activeDefaultsToTrueAndPropSetIsFalse() {
+        val view = makeView()
+        assertTrue(view.active)
+        assertFalse(view.activePropSet)
+    }
+
+    @Test
+    fun settingActiveTrueFlipsPropSet() {
+        val view = makeView()
+        view.setActiveFromBridge(true)
+        assertTrue(view.active)
+        assertTrue(view.activePropSet)
+    }
+
+    @Test
+    fun settingActiveFalseFlipsPropSet() {
+        val view = makeView()
+        view.setActiveFromBridge(false)
+        assertFalse(view.active)
+        assertTrue(view.activePropSet)
+    }
+
+    @Test
+    fun activeReflectsLatestValue() {
+        val view = makeView()
+        view.setActiveFromBridge(false)
+        view.setActiveFromBridge(true)
+        assertTrue(view.active)
+        view.setActiveFromBridge(false)
+        assertFalse(view.active)
+    }
+}

package/ios/ReactOverlayHost.swift

@@ -140,16 +140,18 @@ import ShortKitSDK
         timeCoalesceTimer?.invalidate()
         timeCoalesceTimer = nil
 
-        // Reset cached state so recycled cells don't flash stale values from
-        // the previous item's player. Player-owned values (mute, rate, captions)
-        // are also reset here; the new player's publishers will re-emit their
-        // current values after attach(), so the defaults are only visible for
-        // the single frame between configure() and the first publisher tick.
+        // Reset item-owned cached state so recycled cells don't flash stale
+        // values from the previous item. Player-owned values (mute, rate,
+        // captions) are NOT reset here: the player is a single global
+        // instance with session-wide state, and its `CurrentValueSubject`
+        // publishers are subscribed to ONCE in `attach(player:)` (gated by
+        // `customOverlay == nil` in FeedCell). On cell reuse, attach() does
+        // not re-run, so the subscription does not re-emit the publisher's
+        // current value to overwrite a reset cache. Resetting here would
+        // leave the cache stuck at the default until the user manually
+        // toggles the value again.
         cachedTime = (0, 0, 0)
         cachedPlayerState = "idle"
-        cachedIsMuted = true
-        cachedPlaybackRate = 1.0
-        cachedCaptionsEnabled = false
         cachedActiveCue = nil
         cachedActiveCueJson = nil
         cachedFeedScrollPhase = nil

package/ios/ReactVideoCarouselOverlayHost.swift

@@ -97,13 +97,14 @@ import ShortKitSDK
         timeDirty = false
         timeCoalesceTimer?.invalidate()
         timeCoalesceTimer = nil
-        // Reset cached state so recycled cells don't flash stale values from
-        // the previous item's player. The new player's publishers will re-emit
-        // current values after attach(), so the defaults are only visible for
-        // the single frame between configure() and the first publisher tick.
+        // Reset item-owned cached state so recycled cells don't flash stale
+        // values from the previous item. Player-owned values (mute) are
+        // NOT reset here: the player's `CurrentValueSubject` publishers are
+        // subscribed to ONCE in `attach(player:)`, which doesn't re-run on
+        // cell reuse, so a reset would not be refreshed by a subsequent
+        // publisher tick — the cache would be stuck at the default.
         cachedTime = (0, 0, 0)
         cachedPlayerState = "idle"
-        cachedIsMuted = true
 
         createSurfaceIfNeeded()
 
@@ -147,11 +148,12 @@ import ShortKitSDK
             "playerState": "idle",
             "isMuted": cachedIsMuted,
         ]
-        if let firstVideo = item.videos.first,
-           let videoData = try? JSONEncoder().encode(firstVideo),
+        let initialIndex = item.clampedInitialPageIndex
+        if item.videos.indices.contains(initialIndex),
+           let videoData = try? JSONEncoder().encode(item.videos[initialIndex]),
            let videoJSON = String(data: videoData, encoding: .utf8) {
             props["activeVideo"] = videoJSON
-            props["activeVideoIndex"] = 0
+            props["activeVideoIndex"] = initialIndex
         }
         return props
     }
@@ -159,16 +161,17 @@ import ShortKitSDK
     /// Emit onVideoCarouselItemChanged with full initial state for the new item.
     /// Replaces setProperties() on cell reuse, avoiding a full Fabric root remount.
     private func emitItemChanged(item: VideoCarouselItem, json: String) {
+        let initialIndex = item.clampedInitialPageIndex
         var body: [String: Any] = [
             "surfaceId": surfaceId,
             "carouselItem": json,
             "isActive": false,
             "playerState": "idle",
             "isMuted": cachedIsMuted,
-            "activeVideoIndex": 0,
+            "activeVideoIndex": initialIndex,
         ]
-        if let firstVideo = item.videos.first,
-           let videoData = try? JSONEncoder().encode(firstVideo),
+        if item.videos.indices.contains(initialIndex),
+           let videoData = try? JSONEncoder().encode(item.videos[initialIndex]),
            let videoJSON = String(data: videoData, encoding: .utf8) {
             body["activeVideo"] = videoJSON
         } else {

package/ios/ShortKitBridge.swift

@@ -100,6 +100,20 @@ import ShortKitSDK
             ])
         }
 
+        // Wire per-feed video-carousel cell long-press event. Recognizer is
+        // owned by the cell and dies with the cell — no bridge bookkeeping
+        // needed. State is forwarded as a string ("began"/"ended"/"cancelled")
+        // because the underlying enum is `String`-backed.
+        vc.onVideoCarouselCellLongPress = { [weak self] payload in
+            self?.emitOnMain("onVideoCarouselCellLongPress", body: [
+                "feedId": id,
+                "id": payload.id,
+                "index": payload.index,
+                "pageIndex": payload.pageIndex,
+                "state": payload.state.rawValue,
+            ])
+        }
+
         // Wire per-feed transition event. The FVC fires this closure from
         // handleSwipe(to:) — one per transition, bound to this feed. This
         // replaces the global `player.feedTransition` subscription pattern
@@ -337,6 +351,10 @@ import ShortKitSDK
         shortKit?.player.setCaptionsEnabled(enabled)
     }
 
+    @objc public func setFeedScrollEnabled(_ enabled: Bool) {
+        shortKit?.player.setFeedScrollEnabled(enabled)
+    }
+
     @objc public func selectCaptionTrack(_ language: String) {
         shortKit?.player.selectCaptionTrack(language: language)
     }

package/ios/ShortKitModule.mm

@@ -72,6 +72,7 @@ RCT_EXPORT_MODULE(ShortKitModule)
     @"onDismiss",
     @"onFeedReady",
     @"onVideoCarouselCellTap",
+    @"onVideoCarouselCellLongPress",
     @"onRefreshStateChanged",
     @"onRefreshStateChangedPerFeed",
     @"onDidFetchContentItems",
@@ -248,6 +249,10 @@ RCT_EXPORT_METHOD(setCaptionsEnabled:(BOOL)enabled) {
   [_shortKitBridge setCaptionsEnabled:enabled];
 }
 
+RCT_EXPORT_METHOD(setFeedScrollEnabled:(BOOL)enabled) {
+  [_shortKitBridge setFeedScrollEnabled:enabled];
+}
+
 RCT_EXPORT_METHOD(selectCaptionTrack:(NSString *)language) {
   [_shortKitBridge selectCaptionTrack:language];
 }

package/ios/ShortKitPlayerNativeView.swift

@@ -48,6 +48,12 @@ import ShortKitSDK
     private var playerVC: ShortKitPlayerViewController?
     private var parsedConfig: PlayerConfig?
     private var parsedFeedItems: [FeedInput] = []
+    /// Parsed feedMask mode pulled out of the serialized config JSON in
+    /// `applyConfig()`. Stored separately because the SDK's
+    /// `ShortKitPlayerViewController.feedMask` is a top-level property,
+    /// not part of `PlayerConfig`. Mirrors the same pattern in the
+    /// widget bridge.
+    private var parsedFeedMask: FeedMaskMode = .none
 
     // MARK: - Lifecycle
 
@@ -112,6 +118,13 @@ import ShortKitSDK
             vc.setFeedItems(parsedFeedItems)
         }
 
+        // Forward the optional host-supplied feed mask. The SDK's
+        // `feedMask` lives as a top-level VC property (not in
+        // PlayerConfig), so it has to be set after construction. The
+        // factory closure inside the mode is invoked by the SDK each
+        // time the feed expansion runs.
+        vc.feedMask = parsedFeedMask
+
         parentVC.addChild(vc)
         vc.view.frame = bounds
         vc.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
@@ -152,6 +165,11 @@ import ShortKitSDK
     private func applyConfig() {
         guard let json = config else { return }
         parsedConfig = Self.parsePlayerConfig(json)
+        // FeedMask is stored as a sibling field in the serialized
+        // config JSON; extract it here so it's available when the VC
+        // gets (re)constructed in embedPlayerVCIfNeeded. Mirrors the
+        // widget bridge.
+        parsedFeedMask = Self.extractFeedMask(json)
         // Config changes require re-embedding
         if playerVC != nil {
             destroyPlayerVC()
@@ -159,6 +177,24 @@ import ShortKitSDK
         }
     }
 
+    /// Pulls the `feedMask` field out of the raw config JSON without
+    /// re-parsing the rest of `PlayerConfig`. Returns `.none` if the
+    /// JSON is malformed or omits `feedMask`. Mirrors how the
+    /// equivalent value is read on `ShortKitWidgetNativeView`.
+    private static func extractFeedMask(_ json: String) -> FeedMaskMode {
+        guard let data = json.data(using: .utf8),
+              let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+            return .none
+        }
+        if let mask = obj["feedMask"] {
+            if let data = try? JSONSerialization.data(withJSONObject: mask),
+               let json = String(data: data, encoding: .utf8) {
+                return ShortKitBridge.parseFeedMask(json)
+            }
+        }
+        return .none
+    }
+
     private func applyContentItem() {
         guard let json = contentItem, let item = Self.parseContentItem(json) else { return }
         playerVC?.configure(with: item)