@shortkitsdk/react-native 0.2.6 → 0.2.11

package/ios/ReactOverlayHost.swift

@@ -0,0 +1,458 @@
+import UIKit
+import Combine
+import ShortKitSDK
+
+/// A UIView that conforms to `FeedOverlay` and hosts an `RCTFabricSurface`
+/// for rendering the developer's React overlay component inside a feed cell.
+///
+/// Each cell gets its own instance (via the overlay factory). The surface is
+/// created lazily on the first `configure(with:)` call and reused across cell
+/// reuse cycles.
+///
+/// Surface properties are set ONCE per item (in configure()) to provide initial
+/// values. All subsequent dynamic state changes flow through native module events
+/// routed by surfaceId, triggering React re-renders instead of Fabric remounts.
+@objc public class ReactOverlayHost: UIView, @unchecked Sendable, FeedOverlay {
+
+    // MARK: - Configuration
+
+    /// Surface presenter for creating RCTFabricSurface instances.
+    /// Set by the factory closure from ShortKitBridge.shared.
+    var surfacePresenter: AnyObject? // RCTSurfacePresenter
+
+    /// Module name for the RCTFabricSurface. Set by the overlay factory
+    /// based on the feed config's overlay name (e.g. "ShortKitOverlay_news").
+    var overlayModuleName: String = "ShortKitOverlay"
+
+    /// Unique identifier for this overlay instance, used for event routing.
+    /// Generated once at init, stable across cell reuse.
+    let surfaceId = UUID().uuidString
+
+    /// Bridge reference for emitting events. Set by the overlay factory.
+    weak var bridge: ShortKitBridge?
+
+    // MARK: - State
+
+    private var surface: SKFabricSurfaceWrapper?
+    private var surfaceView: UIView?
+    private var player: ShortKitPlayer?
+    private var cancellables = Set<AnyCancellable>()
+    private var currentItem: ContentItem?
+    private var isActive = false
+
+    // Player state cache
+    private var cachedPlayerState: String = "idle"
+    private var cachedIsMuted: Bool = true
+    private var cachedPlaybackRate: Double = 1.0
+    private var cachedCaptionsEnabled: Bool = false
+    private var cachedActiveCue: [String: Any]? = nil
+    private var cachedFeedScrollPhase: String? = nil
+
+    // Time coalescing
+    private var cachedTime: (current: Double, duration: Double, buffered: Double) = (0, 0, 0)
+    private var timeCoalesceTimer: Timer?
+    private var timeDirty = false
+
+    // MARK: - Init
+
+    /// Height of the scrubber touch area at the bottom of the overlay.
+    /// Matches the scrubberTouchArea height in NewsOverlay.tsx.
+    private let scrubberTouchHeight: CGFloat = 40
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        backgroundColor = .clear
+        isUserInteractionEnabled = true
+        setupScrubberGestureGuard()
+    }
+
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) is not supported")
+    }
+
+    // MARK: - Scrubber Gesture Guard
+
+    /// Disables the parent scroll view's gesture recognizer momentarily when
+    /// a touch begins in the scrubber region. This prevents the feed's
+    /// UICollectionView from stealing the scrub gesture. The recognizer is
+    /// re-enabled after a short delay — once it misses the initial touch
+    /// dispatch, it cannot retroactively claim the gesture.
+    ///
+    /// This approach is fully transparent to RN's touch system: no gesture
+    /// recognizers are added, and no touch events are consumed.
+    private func setupScrubberGestureGuard() {
+        // No setup needed — handled in hitTest override
+    }
+
+    public override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        let hit = super.hitTest(point, with: event)
+        if hit != nil && point.y >= bounds.height - scrubberTouchHeight {
+            if let scrollView = findParentScrollView() {
+                // Briefly disable the scroll view's pan recognizer so it doesn't
+                // claim this touch. Re-enable on the next run loop — by then RN's
+                // PanResponder owns the gesture and the scroll view can't steal it.
+                scrollView.panGestureRecognizer.isEnabled = false
+                DispatchQueue.main.async {
+                    scrollView.panGestureRecognizer.isEnabled = true
+                }
+            }
+        }
+        return hit
+    }
+
+    private func findParentScrollView() -> UIScrollView? {
+        var view: UIView? = superview
+        while let v = view {
+            if let scrollView = v as? UIScrollView { return scrollView }
+            view = v.superview
+        }
+        return nil
+    }
+
+    // MARK: - Cleanup
+
+    deinit {
+        timeCoalesceTimer?.invalidate()
+        surface?.stop()
+    }
+
+    // MARK: - FeedOverlay
+
+    public func attach(player: ShortKitPlayer) {
+        self.player = player
+        subscribeToPlayer(player)
+        // Eagerly create the surface so it's ready before the first configure.
+        createSurfaceIfNeeded()
+    }
+
+    public func configure(with item: ContentItem) {
+        currentItem = item
+        isActive = false
+        timeDirty = false
+        timeCoalesceTimer?.invalidate()
+        timeCoalesceTimer = nil
+
+        // Reset cached state so recycled cells don't flash stale values
+        cachedTime = (0, 0, 0)
+        cachedPlayerState = "idle"
+        cachedActiveCue = nil
+        cachedFeedScrollPhase = nil
+
+        createSurfaceIfNeeded()
+
+        // Set surface properties ONCE per item. This triggers a Fabric remount,
+        // which is desired on cell reuse (new content, fresh React state).
+        // All subsequent dynamic updates go through events, not setProperties().
+        pushInitialProperties()
+    }
+
+    public func activatePlayback() {
+        isActive = true
+        startTimeCoalescing()
+
+        // Defer the event burst to the next tick. The JS surface needs time to
+        // mount and establish event subscriptions (useEffect runs after render).
+        // Emitting before subscriptions are established crashes the codegen's
+        // AsyncEventEmitter (null shared_ptr). Initial values come from surface
+        // properties, so the one-tick delay only affects values that changed
+        // between configure() and activatePlayback().
+        DispatchQueue.main.async { [weak self] in
+            guard let self, self.isActive else { return }
+            self.emitFullState()
+        }
+    }
+
+    /// Emit all cached state as individual events. Called from activatePlayback()
+    /// (deferred) and can be called whenever we need to synchronize JS state.
+    private func emitFullState() {
+        bridge?.emit("onOverlayActiveChanged", body: [
+            "surfaceId": surfaceId, "isActive": true
+        ])
+        bridge?.emit("onOverlayPlayerStateChanged", body: [
+            "surfaceId": surfaceId, "playerState": cachedPlayerState
+        ])
+        bridge?.emit("onOverlayMutedChanged", body: [
+            "surfaceId": surfaceId, "isMuted": cachedIsMuted
+        ])
+        bridge?.emit("onOverlayPlaybackRateChanged", body: [
+            "surfaceId": surfaceId, "playbackRate": cachedPlaybackRate
+        ])
+        bridge?.emit("onOverlayCaptionsEnabledChanged", body: [
+            "surfaceId": surfaceId, "captionsEnabled": cachedCaptionsEnabled
+        ])
+        if let cue = cachedActiveCue,
+           let cueData = try? JSONSerialization.data(withJSONObject: cue),
+           let cueJson = String(data: cueData, encoding: .utf8) {
+            bridge?.emit("onOverlayActiveCueChanged", body: [
+                "surfaceId": surfaceId, "activeCue": cueJson
+            ])
+        } else {
+            bridge?.emit("onOverlayActiveCueChanged", body: [
+                "surfaceId": surfaceId, "activeCue": NSNull()
+            ])
+        }
+        if let scrollPhase = cachedFeedScrollPhase {
+            bridge?.emit("onOverlayFeedScrollPhaseChanged", body: [
+                "surfaceId": surfaceId, "feedScrollPhase": scrollPhase
+            ])
+        } else {
+            bridge?.emit("onOverlayFeedScrollPhaseChanged", body: [
+                "surfaceId": surfaceId, "feedScrollPhase": NSNull()
+            ])
+        }
+    }
+
+    // MARK: - Surface Creation
+
+    private func createSurfaceIfNeeded() {
+        guard surface == nil, let presenter = surfacePresenter else { return }
+
+        // RCTFabricSurface.view requires the main *dispatch queue* (checked via
+        // dispatch_get_specific), but UICollectionViewDiffableDataSource calls
+        // cell providers on "com.apple.uikit.datasource.diffing" — which runs
+        // on the main thread but is NOT the main dispatch queue. Always dispatch
+        // to main queue to satisfy RCTAssertMainQueue().
+        DispatchQueue.main.async { [weak self] in
+            guard let self, self.surface == nil else { return }
+            self.installSurface(presenter: presenter)
+        }
+    }
+
+    private func installSurface(presenter: AnyObject) {
+        guard let surf = SKFabricSurfaceWrapper(
+            presenter: presenter,
+            moduleName: overlayModuleName,
+            initialProperties: [:]
+        ) else { return }
+        surf.start()
+
+        let view = surf.view
+        view.translatesAutoresizingMaskIntoConstraints = false
+        addSubview(view)
+        NSLayoutConstraint.activate([
+            view.topAnchor.constraint(equalTo: topAnchor),
+            view.leadingAnchor.constraint(equalTo: leadingAnchor),
+            view.trailingAnchor.constraint(equalTo: trailingAnchor),
+            view.bottomAnchor.constraint(equalTo: bottomAnchor),
+        ])
+        surfaceView = view
+        surface = surf
+
+        // Push any pending properties now that the surface exists
+        pushInitialProperties()
+    }
+
+    // MARK: - Layout
+
+    public override func layoutSubviews() {
+        super.layoutSubviews()
+        guard let surface else { return }
+        let size = bounds.size
+        guard size.width > 0, size.height > 0 else { return }
+
+        surface.setMinimumSize(size)
+        surface.setMaximumSize(size)
+    }
+
+    // MARK: - Player Subscriptions
+
+    private func subscribeToPlayer(_ player: ShortKitPlayer) {
+        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
+                    ])
+                }
+            }
+            .store(in: &cancellables)
+
+        player.isMuted
+            .receive(on: DispatchQueue.main)
+            .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
+                    ])
+                }
+            }
+            .store(in: &cancellables)
+
+        player.playbackRate
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] rate in
+                guard let self else { return }
+                self.cachedPlaybackRate = Double(rate)
+                if self.isActive {
+                    self.bridge?.emit("onOverlayPlaybackRateChanged", body: [
+                        "surfaceId": self.surfaceId,
+                        "playbackRate": self.cachedPlaybackRate
+                    ])
+                }
+            }
+            .store(in: &cancellables)
+
+        player.captionsEnabled
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] enabled in
+                guard let self else { return }
+                self.cachedCaptionsEnabled = enabled
+                if self.isActive {
+                    self.bridge?.emit("onOverlayCaptionsEnabledChanged", body: [
+                        "surfaceId": self.surfaceId,
+                        "captionsEnabled": self.cachedCaptionsEnabled
+                    ])
+                }
+            }
+            .store(in: &cancellables)
+
+        player.activeCue
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] cue in
+                guard let self else { return }
+                if let cue {
+                    self.cachedActiveCue = [
+                        "text": cue.text,
+                        "startTime": cue.startTime,
+                        "endTime": cue.endTime,
+                    ]
+                } else {
+                    self.cachedActiveCue = nil
+                }
+                if self.isActive {
+                    if let cached = self.cachedActiveCue,
+                       let data = try? JSONSerialization.data(withJSONObject: cached),
+                       let json = String(data: data, encoding: .utf8) {
+                        self.bridge?.emit("onOverlayActiveCueChanged", body: [
+                            "surfaceId": self.surfaceId,
+                            "activeCue": json
+                        ])
+                    } else {
+                        self.bridge?.emit("onOverlayActiveCueChanged", body: [
+                            "surfaceId": self.surfaceId,
+                            "activeCue": NSNull()
+                        ])
+                    }
+                }
+            }
+            .store(in: &cancellables)
+
+        player.feedScrollPhase
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] phase in
+                guard let self else { return }
+                switch phase {
+                case .dragging(let from):
+                    let dict: [String: Any] = ["phase": "dragging", "fromId": from]
+                    if let data = try? JSONSerialization.data(withJSONObject: dict),
+                       let json = String(data: data, encoding: .utf8) {
+                        self.cachedFeedScrollPhase = json
+                    }
+                case .settled:
+                    let dict: [String: Any] = ["phase": "settled"]
+                    if let data = try? JSONSerialization.data(withJSONObject: dict),
+                       let json = String(data: data, encoding: .utf8) {
+                        self.cachedFeedScrollPhase = json
+                    }
+                }
+                if self.isActive {
+                    self.bridge?.emit("onOverlayFeedScrollPhaseChanged", body: [
+                        "surfaceId": self.surfaceId,
+                        "feedScrollPhase": self.cachedFeedScrollPhase ?? NSNull()
+                    ])
+                }
+            }
+            .store(in: &cancellables)
+
+        player.time
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] time in
+                guard let self, self.isActive else { return }
+                self.cachedTime = (time.current, time.duration, time.buffered)
+                self.timeDirty = true
+            }
+            .store(in: &cancellables)
+    }
+
+    // MARK: - Time Coalescing
+
+    private func startTimeCoalescing() {
+        timeCoalesceTimer?.invalidate()
+        timeCoalesceTimer = Timer.scheduledTimer(withTimeInterval: 0.25, repeats: true) { [weak self] _ in
+            guard let self, self.timeDirty else { return }
+            self.timeDirty = false
+            self.bridge?.emit("onOverlayTimeUpdate", body: [
+                "surfaceId": self.surfaceId,
+                "current": self.cachedTime.current,
+                "duration": self.cachedTime.duration,
+                "buffered": self.cachedTime.buffered
+            ])
+        }
+    }
+
+    // MARK: - Initial Properties
+
+    /// Push initial properties to the surface. Called once per item in configure()
+    /// and once in installSurface() (for async surface creation).
+    /// This is the ONLY place setProperties() is called — all subsequent updates
+    /// use event emission to avoid Fabric remounts.
+    private func pushInitialProperties() {
+        guard let surface,
+              let item = currentItem else { return }
+
+        var props: [String: Any] = [:]
+
+        // Surface ID for event routing (stable for life of this host)
+        props["surfaceId"] = surfaceId
+
+        // Serialize ContentItem as JSON string
+        if let data = try? JSONEncoder().encode(item),
+           let json = String(data: data, encoding: .utf8) {
+            props["item"] = json
+        }
+
+        // Initial values — may be stale by the time activatePlayback() fires,
+        // which is why activatePlayback() emits a full state flush via events.
+        props["isActive"] = false
+        props["playerState"] = "idle"
+        props["isMuted"] = cachedIsMuted
+        props["playbackRate"] = cachedPlaybackRate
+        props["captionsEnabled"] = cachedCaptionsEnabled
+
+        if let cue = cachedActiveCue,
+           let cueData = try? JSONSerialization.data(withJSONObject: cue),
+           let cueJson = String(data: cueData, encoding: .utf8) {
+            props["activeCue"] = cueJson
+        }
+
+        if let scrollPhase = cachedFeedScrollPhase {
+            props["feedScrollPhase"] = scrollPhase
+        }
+
+        surface.setProperties(props as [AnyHashable: Any])
+    }
+
+    // MARK: - Helpers
+
+    private static func playerStateString(_ state: PlayerState) -> String {
+        switch state {
+        case .idle: return "idle"
+        case .loading: return "loading"
+        case .ready: return "ready"
+        case .playing: return "playing"
+        case .paused: return "paused"
+        case .seeking: return "seeking"
+        case .buffering: return "buffering"
+        case .ended: return "ended"
+        case .error(_): return "error"
+        }
+    }
+}
+

package/ios/SKFabricSurfaceWrapper.h

@@ -0,0 +1,18 @@
+#import <UIKit/UIKit.h>
+
+/// ObjC wrapper around RCTFabricSurface to avoid exposing C++ headers to Swift.
+@interface SKFabricSurfaceWrapper : NSObject
+
+- (nullable instancetype)initWithPresenter:(nonnull id)surfacePresenter
+                                moduleName:(nonnull NSString *)moduleName
+                         initialProperties:(nonnull NSDictionary *)properties;
+
+@property (nonatomic, readonly, nonnull) UIView *view;
+
+- (void)start;
+- (void)stop;
+- (void)setProperties:(nonnull NSDictionary *)properties;
+- (void)setMinimumSize:(CGSize)size;
+- (void)setMaximumSize:(CGSize)size;
+
+@end

package/ios/SKFabricSurfaceWrapper.mm

@@ -0,0 +1,57 @@
+#import "SKFabricSurfaceWrapper.h"
+#import <React-RCTFabric/React/RCTFabricSurface.h>
+#import <React-RCTFabric/React/RCTSurfacePresenter.h>
+
+@implementation SKFabricSurfaceWrapper {
+    RCTFabricSurface *_surface;
+    NSDictionary *_lastProperties;
+}
+
+- (nullable instancetype)initWithPresenter:(nonnull id)surfacePresenter
+                                moduleName:(nonnull NSString *)moduleName
+                         initialProperties:(nonnull NSDictionary *)properties {
+    if (![surfacePresenter isKindOfClass:[RCTSurfacePresenter class]]) {
+        return nil;
+    }
+    self = [super init];
+    if (self) {
+        _surface = [[RCTFabricSurface alloc] initWithSurfacePresenter:(RCTSurfacePresenter *)surfacePresenter
+                                                           moduleName:moduleName
+                                                    initialProperties:properties];
+    }
+    return self;
+}
+
+- (UIView *)view {
+    return (UIView *)[_surface view];
+}
+
+- (void)start {
+    [_surface start];
+}
+
+- (void)stop {
+    [_surface stop];
+}
+
+- (void)setProperties:(NSDictionary *)properties {
+    // Only push to the surface if properties actually changed.
+    // RCTFabricSurface.properties setter triggers a full root remount,
+    // so we must avoid setting identical properties.
+    if ([_lastProperties isEqualToDictionary:properties]) {
+        return;
+    }
+    _lastProperties = [properties copy];
+    _surface.properties = properties;
+}
+
+- (void)setMinimumSize:(CGSize)size {
+    // RCTFabricSurface min/max are readonly; use setSize: to set both.
+    [_surface setSize:size];
+}
+
+- (void)setMaximumSize:(CGSize)size {
+    // Already set via setMinimumSize → setSize:. No-op here.
+}
+
+@end