@shortkitsdk/react-native 0.2.24 → 0.2.25

package/ios/ReactVideoCarouselOverlayHost.swift

@@ -13,7 +13,9 @@ import ShortKitSDK
     // MARK: - Configuration
 
     var surfacePresenter: AnyObject?
-    weak var bridge: ShortKitBridge?
+    weak var bridge: ShortKitBridge? {
+        didSet { subscribeToCarouselCompletion() }
+    }
 
     /// Module name for the RCTFabricSurface. Set by the overlay factory
     /// based on the feed config's video carousel overlay name.
@@ -37,16 +39,36 @@ import ShortKitSDK
     /// Cached carouselItem JSON — setProperties replaces all props, doesn't merge.
     private var carouselItemJSON: String?
 
+    /// Currently configured carousel item — used to detect item transitions
+    /// so we can emit an event instead of triggering a full Fabric remount.
+    private var currentCarouselItem: VideoCarouselItem?
+
+    /// Whether initial props have been pushed to the surface at least once.
+    /// First mount must go through setProperties (for item + surfaceId + initial
+    /// state). Subsequent item changes use the event path.
+    private var hasPushedInitialProps: Bool = false
+
     // Player state
     private var player: ShortKitPlayer?
     private var cancellables = Set<AnyCancellable>()
+    /// Separate cancellable set for the carousel-completion subscription.
+    /// Kept out of `cancellables` so `subscribeToPlayer`'s removeAll() doesn't
+    /// wipe it out — the completion subscription is wired once at bridge didSet
+    /// time and must survive player re-attachments.
+    private var carouselCompletionCancellables = Set<AnyCancellable>()
     private var isActive = false
+    private var isDragging: Bool = false                  // FIX: track drag phase
     private var cachedPlayerState: String = "idle"
     private var cachedIsMuted: Bool = true
     private var cachedTime: (current: Double, duration: Double, buffered: Double) = (0, 0, 0)
     private var timeCoalesceTimer: Timer?
     private var timeDirty = false
 
+    // Tracks the last bounds.size pushed to the surface. Used in layoutSubviews
+    // to skip redundant setSize calls that would otherwise trigger a Fabric
+    // layout recalc on every frame during scroll.
+    private var lastLayoutSize: CGSize = .zero
+
     // MARK: - Init
 
     override init(frame: CGRect) {
@@ -67,12 +89,21 @@ import ShortKitSDK
     // MARK: - VideoCarouselOverlay
 
     public func configure(with item: VideoCarouselItem) {
+        let isSameItem = item.id == currentCarouselItem?.id
+        currentCarouselItem = item
+
         isActive = false
+        isDragging = false
         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.
         cachedTime = (0, 0, 0)
         cachedPlayerState = "idle"
+        cachedIsMuted = true
 
         createSurfaceIfNeeded()
 
@@ -80,6 +111,35 @@ import ShortKitSDK
               let json = String(data: data, encoding: .utf8) else { return }
         carouselItemJSON = json
 
+        // Surface lifecycle on item change:
+        //   - First mount: pushInitialProperties() via setProperties (unavoidable
+        //     — React needs props at mount time). ALSO emit
+        //     onVideoCarouselItemChanged so external subscribers that live
+        //     outside the overlay's React tree (e.g. useShortKitCarousel() hook
+        //     consumers) see the initial carousel too. The in-surface subscriber
+        //     at ShortKitVideoCarouselOverlaySurface.tsx:153 is sid-filtered
+        //     and sets the same JSON-parsed item, so it's a redundant second
+        //     set with identical value — safe.
+        //   - Subsequent item change with surface ready: emit event for React
+        //     diff (no remount).
+        //   - Same item: no-op.
+        if !hasPushedInitialProps {
+            let props = buildInitialProps(item: item, json: json)
+            if let surface {
+                surface.setProperties(props)
+                hasPushedInitialProps = true
+            } else {
+                pendingProps = props
+            }
+            emitItemChanged(item: item, json: json)
+        } else if !isSameItem {
+            emitItemChanged(item: item, json: json)
+        }
+    }
+
+    /// Build the initial-properties dictionary for an item. Used on first mount
+    /// (via setProperties) and shadowed by emitItemChanged() on subsequent changes.
+    private func buildInitialProps(item: VideoCarouselItem, json: String) -> [String: Any] {
         var props: [String: Any] = [
             "surfaceId": surfaceId,
             "carouselItem": json,
@@ -93,11 +153,32 @@ import ShortKitSDK
             props["activeVideo"] = videoJSON
             props["activeVideoIndex"] = 0
         }
-        if let surface {
-            surface.setProperties(props)
+        return props
+    }
+
+    /// 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) {
+        var body: [String: Any] = [
+            "surfaceId": surfaceId,
+            "carouselItem": json,
+            "isActive": false,
+            "playerState": "idle",
+            "isMuted": cachedIsMuted,
+            "activeVideoIndex": 0,
+        ]
+        if let firstVideo = item.videos.first,
+           let videoData = try? JSONEncoder().encode(firstVideo),
+           let videoJSON = String(data: videoData, encoding: .utf8) {
+            body["activeVideo"] = videoJSON
         } else {
-            pendingProps = props
+            // Match buildInitialProps: omit the key rather than emitting an
+            // empty-string sentinel that JS treats as falsy (overlay would
+            // disappear on every cell reuse with a zero-video carousel).
+            body["activeVideo"] = NSNull()
         }
+
+        bridge?.emit("onVideoCarouselItemChanged", body: body)
     }
 
     public func updateActiveVideo(index: Int, item: ContentItem) {
@@ -147,17 +228,20 @@ import ShortKitSDK
 
     private func subscribeToPlayer(_ player: ShortKitPlayer) {
         cancellables.removeAll()
+        // FIX: playerState, isMuted, and time are suppressed during .dragging to
+        // avoid unnecessary bridge traffic while scrolling. emitFullState() on
+        // drag→settled re-syncs cached values.
+
         player.playerState
             .receive(on: DispatchQueue.main)
             .sink { [weak self] state in
                 guard let self else { return }
                 self.cachedPlayerState = Self.playerStateString(state)
-                if self.isActive {
-                    self.bridge?.emit("onOverlayPlayerStateChanged", body: [
-                        "surfaceId": self.surfaceId,
-                        "playerState": self.cachedPlayerState
-                    ])
-                }
+                guard self.isActive, !self.isDragging else { return }
+                self.bridge?.emit("onOverlayPlayerStateChanged", body: [
+                    "surfaceId": self.surfaceId,
+                    "playerState": self.cachedPlayerState
+                ])
             }
             .store(in: &cancellables)
 
@@ -166,23 +250,90 @@ import ShortKitSDK
             .sink { [weak self] muted in
                 guard let self else { return }
                 self.cachedIsMuted = muted
-                if self.isActive {
-                    self.bridge?.emit("onOverlayMutedChanged", body: [
-                        "surfaceId": self.surfaceId,
-                        "isMuted": self.cachedIsMuted
-                    ])
-                }
+                guard self.isActive, !self.isDragging else { return }
+                self.bridge?.emit("onOverlayMutedChanged", body: [
+                    "surfaceId": self.surfaceId,
+                    "isMuted": self.cachedIsMuted
+                ])
             }
             .store(in: &cancellables)
 
         player.time
             .receive(on: DispatchQueue.main)
             .sink { [weak self] time in
-                guard let self, self.isActive else { return }
+                guard let self, self.isActive, !self.isDragging else { return }
                 self.cachedTime = (time.current, time.duration, time.buffered)
                 self.timeDirty = true
             }
             .store(in: &cancellables)
+
+        // FIX: subscribe to feedScrollPhase so we know when a drag starts/settles.
+        // On drag start: invalidate the time coalescing timer.
+        // On settle: restart timer and re-sync state via emitFullState().
+        player.feedScrollPhase
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] phase in
+                guard let self else { return }
+                switch phase {
+                case .dragging:
+                    self.isDragging = true
+                    // Stop the time coalescing timer during drags. Time updates
+                    // are suppressed while isDragging is true, so the timer
+                    // would just wake the main thread to check timeDirty.
+                    self.timeCoalesceTimer?.invalidate()
+                    self.timeCoalesceTimer = nil
+                case .settled:
+                    let wasDragging = self.isDragging
+                    self.isDragging = false
+                    if self.isActive {
+                        self.startTimeCoalescing()
+                        if wasDragging {
+                            // Re-sync state that was suppressed during the drag.
+                            self.emitFullState()
+                        }
+                    }
+                }
+            }
+            .store(in: &cancellables)
+    }
+
+    // MARK: - Carousel Completion
+
+    /// Subscribe to the carousel's activeVideoCompleted publisher and emit
+    /// `onCarouselActiveVideoCompleted` with this host's surfaceId.
+    /// Called via `bridge` didSet so the subscription is wired once per host
+    /// instance, mirroring how `onVideoCarouselActiveVideoChanged` is emitted.
+    private func subscribeToCarouselCompletion() {
+        guard let carousel = bridge?.sdk?.carousel else { return }
+        carousel.activeVideoCompleted
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] event in
+                guard let self, self.isActive,
+                      event.carouselItem.id == self.currentCarouselItem?.id else { return }
+                let contentItemJSON: String
+                if let data = try? JSONEncoder().encode(event.contentItem),
+                   let json = String(data: data, encoding: .utf8) {
+                    contentItemJSON = json
+                } else {
+                    contentItemJSON = "{}"
+                }
+                let carouselItemJSON: String
+                if let data = try? JSONEncoder().encode(event.carouselItem),
+                   let json = String(data: data, encoding: .utf8) {
+                    carouselItemJSON = json
+                } else {
+                    carouselItemJSON = "{}"
+                }
+                self.bridge?.emit("onCarouselActiveVideoCompleted", body: [
+                    "surfaceId": self.surfaceId,
+                    "contentItem": contentItemJSON,
+                    "indexInCarousel": event.indexInCarousel,
+                    "carouselItem": carouselItemJSON,
+                    "wasLast": event.wasLast,
+                    "willAutoAdvance": event.willAutoAdvance,
+                ])
+            }
+            .store(in: &carouselCompletionCancellables)
     }
 
     // MARK: - Time Coalescing
@@ -190,7 +341,10 @@ import ShortKitSDK
     private func startTimeCoalescing() {
         timeCoalesceTimer?.invalidate()
         timeCoalesceTimer = Timer.scheduledTimer(withTimeInterval: 0.25, repeats: true) { [weak self] _ in
-            guard let self, self.timeDirty else { return }
+            guard let self else { return }
+            // Timer is invalidated on drag start; this guard is belt-and-suspenders.
+            if self.isDragging { return }
+            guard self.timeDirty else { return }
             self.timeDirty = false
             self.bridge?.emit("onOverlayTimeUpdate", body: [
                 "surfaceId": self.surfaceId,
@@ -251,6 +405,7 @@ import ShortKitSDK
         if let pending = pendingProps {
             surf.setProperties(pending)
             pendingProps = nil
+            hasPushedInitialProps = true
         }
     }
 
@@ -261,8 +416,15 @@ import ShortKitSDK
         guard let surface else { return }
         let size = bounds.size
         guard size.width > 0, size.height > 0 else { return }
+
+        // Skip setSize when bounds haven't changed. UICollectionView calls
+        // layoutSubviews every frame during scroll; without this guard we'd
+        // trigger a Fabric layout recalc each time.
+        guard size != lastLayoutSize else { return }
+        lastLayoutSize = size
+
         surface.setMinimumSize(size)
-        surface.setMaximumSize(size)
+        // setMaximumSize is a no-op in SKFabricSurfaceWrapper — not called.
     }
 
     // MARK: - Helpers

package/ios/SKFabricSurfaceWrapper.mm

@@ -5,6 +5,7 @@
 @implementation SKFabricSurfaceWrapper {
     RCTFabricSurface *_surface;
     NSDictionary *_lastProperties;
+    CGSize _lastSize;
 }
 
 - (nullable instancetype)initWithPresenter:(nonnull id)surfacePresenter
@@ -46,7 +47,12 @@
 }
 
 - (void)setMinimumSize:(CGSize)size {
-    // RCTFabricSurface min/max are readonly; use setSize: to set both.
+    // Skip when size hasn't changed — belt-and-suspenders guard in case a
+    // caller other than the overlay hosts invokes this during scroll.
+    if (CGSizeEqualToSize(_lastSize, size)) {
+        return;
+    }
+    _lastSize = size;
     [_surface setSize:size];
 }
 

package/ios/ShortKitBridge.swift

@@ -207,6 +207,44 @@ import ShortKitSDK
         shortKit?.player.skipToPrevious()
     }
 
+    // MARK: - Carousel Commands
+
+    /// Advance the active carousel to the next video.
+    /// Returns NSNumber wrapping Bool: @(YES) on success, @(NO) when no carousel active.
+    @objc public func carouselNext() -> NSNumber {
+        return NSNumber(value: shortKit?.carousel.next() ?? false)
+    }
+
+    /// Move the active carousel to the previous video.
+    @objc public func carouselPrevious() -> NSNumber {
+        return NSNumber(value: shortKit?.carousel.previous() ?? false)
+    }
+
+    /// Jump the active carousel to a specific zero-based index.
+    ///
+    /// Accepts `Int` (bridged to ObjC `NSInteger` / encoding `q`), matching
+    /// what RN TurboModule codegen emits for a TS `Int32` parameter. Declaring
+    /// this with `NSNumber *` crashed at the Swift @objc thunk's ARC retain
+    /// because the codegen wrote a raw int into the NSInvocation slot, which
+    /// the thunk interpreted as an object pointer.
+    @objc public func carouselSetActiveIndex(_ index: Int) -> NSNumber {
+        return NSNumber(value: shortKit?.carousel.setActiveIndex(index) ?? false)
+    }
+
+    // MARK: - Carousel Accessors
+
+    /// Zero-based index of the currently playing carousel video, or -1 when no carousel is active.
+    @objc public func getCarouselActiveIndex() -> NSNumber {
+        guard let idx = shortKit?.carousel.activeIndexValue else { return NSNumber(value: -1) }
+        return NSNumber(value: idx)
+    }
+
+    /// Total number of videos in the active carousel, or 0 when no carousel is active.
+    @objc public func getCarouselVideoCount() -> NSNumber {
+        guard let count = shortKit?.carousel.videoCountValue else { return NSNumber(value: 0) }
+        return NSNumber(value: count)
+    }
+
     @objc public func setMuted(_ muted: Bool) {
         shortKit?.player.setMuted(muted)
     }
@@ -552,6 +590,9 @@ import ShortKitSDK
             .store(in: &cancellables)
 
         // Remaining content count — now handled per-feed via onRemainingContentCountChange callback
+
+        // Carousel video completion is emitted from ReactVideoCarouselOverlayHost
+        // using that host's surfaceId, so useOverlayEvent subscribers can match it.
     }
 
     // MARK: - Event Emission Helpers
@@ -881,8 +922,9 @@ import ShortKitSDK
             switch type {
             case "video":
                 guard let playbackId = obj["playbackId"] as? String else { continue }
+                let origin = (obj["origin"] as? String).flatMap { ContentOrigin(rawValue: $0) } ?? .other
                 let fallbackUrl = obj["fallbackUrl"] as? String
-                result.append(.video(playbackId: playbackId, fallbackUrl: fallbackUrl))
+                result.append(.video(playbackId: playbackId, origin: origin, fallbackUrl: fallbackUrl))
             case "imageCarousel":
                 guard let itemData = obj["item"],
                       let itemJSON = try? JSONSerialization.data(withJSONObject: itemData),

package/ios/ShortKitFeedView.swift

@@ -20,6 +20,15 @@ import ShortKitSDK
         didSet { /* used at init time only */ }
     }
 
+    /// URL of the thumbnail the host app is already rendering for the item that
+    /// will be the first active cell. Looked up synchronously via SDWebImage's
+    /// memory cache (supports expo-image / FastImage clients) and seeded onto
+    /// the feed VC before viewDidLoad fires. Falls back to patchMissingThumbnail
+    /// (network fetch) on cache miss.
+    @objc public var seedThumbnailUrl: String? {
+        didSet { /* used at embed time only */ }
+    }
+
     @objc var feedId: String?
 
     // MARK: - Child VC
@@ -104,6 +113,17 @@ import ShortKitSDK
         let feedVC = ShortKitFeedViewController(shortKit: sdk, config: feedConfig, startAtItemId: startAtItemId)
         feedVC.setBridgeManaged()
 
+        // Seed a thumbnail from the host app's image cache so the first cell
+        // renders with a visible thumbnail from frame zero. Synchronous
+        // SDWebImage lookup (memory then disk, via reflection) — no network.
+        // If nil (cache miss or SDWebImage not linked), the existing
+        // patchMissingThumbnailIfNeeded helper handles the fallback at
+        // feed-open time.
+        if let url = self.seedThumbnailUrl,
+           let image = SeedThumbnailResolver.resolveFromMemory(url: url) {
+            feedVC.seedThumbnail = image
+        }
+
         if sdk.debugPanelEnabled {
             feedVC.debugPanelFactory = { active, prev, next in
                 let panel = DebugPanelView(frame: CGRect(

package/ios/ShortKitFeedViewManager.mm

@@ -26,5 +26,6 @@ RCT_EXPORT_VIEW_PROPERTY(config, NSString)
 RCT_EXPORT_VIEW_PROPERTY(startAtItemId, NSString)
 RCT_EXPORT_VIEW_PROPERTY(preloadId, NSString)
 RCT_EXPORT_VIEW_PROPERTY(feedId, NSString)
+RCT_EXPORT_VIEW_PROPERTY(seedThumbnailUrl, NSString)
 
 @end

package/ios/ShortKitModule.mm

@@ -82,8 +82,12 @@ RCT_EXPORT_MODULE(ShortKitModule)
     @"onOverlayFeedScrollPhaseChanged",
     @"onOverlayTimeUpdate",
     @"onOverlayFullState",
+    @"onOverlayItemChanged",
     @"onCarouselActiveImageChanged",
+    @"onCarouselItemChanged",
     @"onVideoCarouselActiveVideoChanged",
+    @"onVideoCarouselItemChanged",
+    @"onCarouselActiveVideoCompleted",
     @"onDownloadStarted",
     @"onDownloadProgress",
     @"onDownloadCompleted",
@@ -197,6 +201,35 @@ RCT_EXPORT_METHOD(skipToPrevious) {
   [_shortKitBridge skipToPrevious];
 }
 
+// MARK: - Carousel Commands
+
+RCT_EXPORT_SYNCHRONOUS_TYPED_METHOD(NSNumber *, carouselNext)
+{
+  return [_shortKitBridge carouselNext];
+}
+
+RCT_EXPORT_SYNCHRONOUS_TYPED_METHOD(NSNumber *, carouselPrevious)
+{
+  return [_shortKitBridge carouselPrevious];
+}
+
+RCT_EXPORT_SYNCHRONOUS_TYPED_METHOD(NSNumber *, carouselSetActiveIndex:(NSInteger)index)
+{
+  return [_shortKitBridge carouselSetActiveIndex:index];
+}
+
+// MARK: - Carousel Accessors
+
+RCT_EXPORT_SYNCHRONOUS_TYPED_METHOD(NSNumber *, getCarouselActiveIndex)
+{
+  return [_shortKitBridge getCarouselActiveIndex];
+}
+
+RCT_EXPORT_SYNCHRONOUS_TYPED_METHOD(NSNumber *, getCarouselVideoCount)
+{
+  return [_shortKitBridge getCarouselVideoCount];
+}
+
 RCT_EXPORT_METHOD(setMuted:(BOOL)muted) {
   [_shortKitBridge setMuted:muted];
 }

package/ios/ShortKitSDK.xcframework/Info.plist

@@ -8,32 +8,32 @@
 			<key>BinaryPath</key>
 			<string>ShortKitSDK.framework/ShortKitSDK</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64_x86_64-simulator</string>
+			<string>ios-arm64</string>
 			<key>LibraryPath</key>
 			<string>ShortKitSDK.framework</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
-				<string>x86_64</string>
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
-			<key>SupportedPlatformVariant</key>
-			<string>simulator</string>
 		</dict>
 		<dict>
 			<key>BinaryPath</key>
 			<string>ShortKitSDK.framework/ShortKitSDK</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64</string>
+			<string>ios-arm64_x86_64-simulator</string>
 			<key>LibraryPath</key>
 			<string>ShortKitSDK.framework</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
+				<string>x86_64</string>
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
+			<key>SupportedPlatformVariant</key>
+			<string>simulator</string>
 		</dict>
 	</array>
 	<key>CFBundlePackageType</key>

package/ios/ShortKitSDK.xcframework/ios-arm64/ShortKitSDK.framework/Info.plist

@@ -11,9 +11,9 @@
     <key>CFBundlePackageType</key>
     <string>FMWK</string>
     <key>CFBundleVersion</key>
-    <string>0.2.24</string>
+    <string>0.2.25</string>
     <key>CFBundleShortVersionString</key>
-    <string>0.2.24</string>
+    <string>0.2.25</string>
     <key>MinimumOSVersion</key>
     <string>16.0</string>
 </dict>