@shortkitsdk/react-native 0.2.24 → 0.2.26

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

@@ -70,6 +70,37 @@ import ShortKitSDK
             self?.emitOnMain("onFeedReady", body: ["feedId": id])
         }
 
+        // Wire per-feed refresh state callback (scoped by feedId)
+        vc.onRefreshStateChanged = { [weak self] state in
+            NSLog("[ShortKit Bridge] onRefreshStateChangedPerFeed feedId=%@ status=%@", id, "\(state)")
+            var body: [String: Any] = ["feedId": id]
+            switch state {
+            case .idle:
+                body["status"] = "idle"
+                body["progress"] = 0.0
+            case .pulling(let progress):
+                body["status"] = "pulling"
+                body["progress"] = progress
+            case .triggered:
+                body["status"] = "triggered"
+                body["progress"] = 0.0
+            case .refreshing:
+                body["status"] = "refreshing"
+                body["progress"] = 0.0
+            }
+            self?.emitOnMain("onRefreshStateChangedPerFeed", body: body)
+        }
+
+        // Wire per-feed video-carousel cell tap event
+        vc.onVideoCarouselCellTap = { [weak self] payload in
+            self?.emitOnMain("onVideoCarouselCellTap", body: [
+                "feedId": id,
+                "id": payload.id,
+                "index": payload.index,
+                "pageIndex": payload.pageIndex,
+            ])
+        }
+
         // Replay buffered operations on the next run-loop tick so the VC's
         // view hierarchy is fully set up after didMoveToWindow returns.
         if let ops = pendingOps.removeValue(forKey: id) {
@@ -207,6 +238,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)
     }
@@ -234,20 +303,27 @@ import ShortKitSDK
 
     // MARK: - Custom Feed
 
-    @objc public func setFeedItems(_ feedId: String, items json: String) {
+    @objc public func setFeedItems(_ feedId: String, items json: String, startAtId: String?) {
         guard let items = Self.parseFeedInputs(json) else { return }
         DispatchQueue.main.async { [weak self] in
             guard let self else { return }
             if let vc = self.feedViewController(for: feedId) {
-                vc.setFeedItems(items)
+                vc.setFeedItems(items, startAtId: startAtId)
             } else {
                 self.pendingOps[feedId, default: []].append { vc in
-                    vc.setFeedItems(items)
+                    vc.setFeedItems(items, startAtId: startAtId)
                 }
             }
         }
     }
 
+    @objc public func scrollFeedToItem(_ feedId: String, id: String, animated: Bool) {
+        DispatchQueue.main.async { [weak self] in
+            guard let self else { return }
+            self.feedViewController(for: feedId)?.scrollToItem(id: id, animated: animated)
+        }
+    }
+
     @objc public func appendFeedItems(_ feedId: String, items json: String) {
         guard let items = Self.parseFeedInputs(json) else { return }
         DispatchQueue.main.async { [weak self] in
@@ -552,6 +628,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
@@ -869,7 +948,7 @@ import ShortKitSDK
     }
 
     /// Parse a JSON string of FeedInput[] from the JS bridge.
-    private static func parseFeedInputs(_ json: String) -> [FeedInput]? {
+    static func parseFeedInputs(_ json: String) -> [FeedInput]? {
         guard let data = json.data(using: .utf8),
               let arr = try? JSONSerialization.jsonObject(with: data) as? [[String: Any]] else {
             return nil
@@ -881,8 +960,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,40 @@ 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 */ }
+    }
+
+    /// JSON-serialized FeedInput[] for initial custom-feed items at mount time.
+    /// Parsed and wrapped in FeedPreload(immediateItems:) at embed time so the
+    /// SDK takes the sync render path — no async preload wait, no ref-attach
+    /// race, first cell dequeued on the first run-loop tick.
+    /// When preloadId is also set, preloadId takes precedence.
+    @objc public var feedItemsJSON: String? {
+        didSet { /* used at embed time only */ }
+    }
+
+    /// When the consumer explicitly manages this prop, it becomes the
+    /// authoritative suspension signal — overriding willMove(toWindow:).
+    private var isActiveManagedByProp = false
+
+    @objc public var active: Bool = true {
+        didSet {
+            guard active != oldValue, let feedVC = feedViewController else { return }
+            if !active { isActiveManagedByProp = true }
+            if active {
+                feedVC.activate()
+            } else {
+                feedVC.deactivate()
+            }
+        }
+    }
+
     @objc var feedId: String?
 
     // MARK: - Child VC
@@ -39,7 +73,7 @@ import ShortKitSDK
     public override func willMove(toWindow newWindow: UIWindow?) {
         super.willMove(toWindow: newWindow)
 
-        if newWindow == nil {
+        if newWindow == nil && !isActiveManagedByProp {
             suspendFeedViewController()
         }
     }
@@ -62,14 +96,18 @@ import ShortKitSDK
 
         // Re-attach an existing suspended VC (e.g. after native stack pop)
         if let feedVC = feedViewController {
+            NSLog("[ShortKit FeedView] re-attaching suspended VC feedId=%@", feedId ?? "nil")
             parentVC.addChild(feedVC)
             feedVC.view.frame = bounds
             addSubview(feedVC.view)
             feedVC.didMove(toParent: parentVC)
-            feedVC.activate()
+            if !isActiveManagedByProp {
+                feedVC.activate()
+            }
             if let feedId = self.feedId {
                 ShortKitBridge.shared?.registerFeed(id: feedId, viewController: feedVC)
             }
+            NSLog("[ShortKit FeedView] re-attach complete — activate() called")
             return
         }
 
@@ -90,8 +128,14 @@ import ShortKitSDK
                 NSLog("[ShortKit FeedView] ❌ No preload handle found for feedId: %@", preloadId)
                 NSLog("[ShortKit FeedView] Available preload handles: %@", ShortKitBridge.shared?.preloadHandles.keys.joined(separator: ", ") ?? "none")
             }
+        } else if let json = self.feedItemsJSON,
+                  let items = ShortKitBridge.parseFeedInputs(json) {
+            // feedItems prop: wrap in an immediate preload (no async prefetch
+            // work — items are available synchronously at viewDidLoad).
+            feedConfig.preload = FeedPreload(immediateItems: items)
+            NSLog("[ShortKit FeedView] feedItems prop: created immediate preload with %d items", items.count)
         } else {
-            NSLog("[ShortKit FeedView] No preloadId prop set")
+            NSLog("[ShortKit FeedView] No preloadId or feedItems prop set")
         }
 
         NSLog("[ShortKit FeedView] feedConfig.preload is %@", feedConfig.preload != nil ? "SET" : "NIL")
@@ -104,6 +148,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(
@@ -135,6 +190,12 @@ import ShortKitSDK
         feedVC.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
         addSubview(feedVC.view)
         feedVC.didMove(toParent: parentVC)
+
+        // Fabric sets props BEFORE didMoveToWindow, so active=false may have
+        // fired its didSet while feedViewController was still nil. Apply now.
+        if isActiveManagedByProp && !active, let feedVC = feedViewController {
+            feedVC.deactivate()
+        }
     }
 
     /// Detach the feedVC from the parent VC hierarchy without destroying it.
@@ -142,15 +203,20 @@ import ShortKitSDK
     /// (e.g. pushing a new screen on top). The feedVC and its state are preserved
     /// so they can be re-attached when the view returns to the window.
     private func suspendFeedViewController() {
+        NSLog("[ShortKit FeedView] suspendFeedViewController ENTRY feedId=%@", feedId ?? "nil")
         if let feedId = self.feedId {
             ShortKitBridge.shared?.unregisterFeed(id: feedId)
         }
-        guard let feedVC = feedViewController else { return }
+        guard let feedVC = feedViewController else {
+            NSLog("[ShortKit FeedView] suspendFeedViewController NOOP — no feedVC")
+            return
+        }
 
         feedVC.deactivate()
         feedVC.willMove(toParent: nil)
         feedVC.view.removeFromSuperview()
         feedVC.removeFromParent()
+        NSLog("[ShortKit FeedView] suspendFeedViewController EXIT — VC retained for re-attach")
         // Keep feedViewController reference — re-attached in embedFeedViewControllerIfNeeded
     }
 

package/ios/ShortKitFeedViewManager.mm

@@ -26,5 +26,8 @@ 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)
+RCT_EXPORT_VIEW_PROPERTY(feedItemsJSON, NSString)
+RCT_EXPORT_VIEW_PROPERTY(active, BOOL)
 
 @end