@shortkitsdk/react-native 0.2.23 → 0.2.25

package/README.md

@@ -0,0 +1,151 @@
+# ShortKit React Native SDK — Carousel Navigation API
+
+> **Android support coming in the next release.** The carousel navigation API is currently iOS-only. Android stubs are present but return defaults.
+
+## Video Carousel Navigation
+
+Navigate videos within a carousel item using the `useShortKitCarousel()` hook or imperative commands.
+
+### Hook-based Navigation
+
+Access carousel state and imperative controls using `useShortKitCarousel()`:
+
+```tsx
+import { useShortKitCarousel } from '@shortkitsdk/react-native';
+import { View, Text, Button } from 'react-native';
+
+function MyCarouselControls() {
+  const { activeIndex, videoCount, next, previous, setActiveIndex } = useShortKitCarousel();
+
+  if (activeIndex === null) {
+    return null; // no carousel currently active
+  }
+
+  return (
+    <View style={{ padding: 16 }}>
+      <Text style={{ marginBottom: 12 }}>
+        {activeIndex + 1} of {videoCount}
+      </Text>
+      <View style={{ flexDirection: 'row', gap: 8 }}>
+        <Button
+          title="Previous"
+          onPress={previous}
+          disabled={activeIndex === 0}
+        />
+        <Button
+          title="Next"
+          onPress={next}
+          disabled={activeIndex === videoCount - 1}
+        />
+      </View>
+    </View>
+  );
+}
+```
+
+The hook returns:
+- `activeIndex`: Current video index in the carousel, or `null` if no carousel is active
+- `videoCount`: Total number of videos in the active carousel
+- `activeCarouselItem`: The full carousel item object, or `null` if none
+- `next()`: Advance to the next video (returns `false` at the last index)
+- `previous()`: Go to the previous video (returns `false` at index 0)
+- `setActiveIndex(index)`: Jump to a specific index (returns `false` if out of range)
+
+### Imperative Commands (Inside Overlay Surfaces)
+
+For overlay components that run in isolated React surfaces and cannot access context, use `ShortKitCommands` directly:
+
+```tsx
+import { ShortKitCommands } from '@shortkitsdk/react-native';
+import { Pressable, Text } from 'react-native';
+
+function CarouselOverlay() {
+  return (
+    <Pressable
+      onPress={() => {
+        const success = ShortKitCommands.carouselNext();
+        if (!success) {
+          // already at the last video
+        }
+      }}
+    >
+      <Text>Next Video</Text>
+    </Pressable>
+  );
+}
+```
+
+Available carousel commands:
+- `carouselNext()`: Advance to the next video (returns `false` if already at last index)
+- `carouselPrevious()`: Go to the previous video (returns `false` if already at index 0)
+- `carouselSetActiveIndex(index)`: Jump to a specific index (returns `false` if out of range)
+
+### Completion Event Handling
+
+Use the `onCarouselActiveVideoCompleted` callback on `<ShortKitFeed>` to react when a video completes playback:
+
+```tsx
+<ShortKitFeed
+  onCarouselActiveVideoCompleted={(event) => {
+    console.log(`Video ${event.indexInCarousel} completed in carousel`);
+
+    if (event.wasLast && !event.willAutoAdvance) {
+      // Show an "End of carousel" call-to-action
+      showEndOfCarouselCTA({
+        contentItem: event.contentItem,
+        carouselItem: event.carouselItem,
+      });
+    }
+  }}
+/>
+```
+
+Event properties:
+- `surfaceId`: Identifier of the overlay surface
+- `contentItem`: The video that just completed
+- `indexInCarousel`: Index of the completed video within the carousel
+- `carouselItem`: The full carousel item
+- `wasLast`: Whether this was the last video in the carousel
+- `willAutoAdvance`: Whether the carousel will automatically advance (always `false` for the last video)
+
+### Behavior Contract
+
+- **Boundary returns**: `next()` returns `false` when already at the last index; `previous()` returns `false` at index 0; `setActiveIndex()` returns `false` for out-of-range indices.
+- **Last video loops**: The final video loops automatically; it does **not** advance to the next feed item.
+- **Completion event only on natural end**: `onCarouselActiveVideoCompleted` fires when a video reaches the end naturally. It does **not** fire for user-initiated swipes or programmatic navigation.
+- **Auto-advance**: When a non-final video completes, the SDK automatically advances to the next video (same as a user swipe). This behavior is suppressed if the user is mid-drag on the carousel.
+
+### Example: End-of-Carousel CTA
+
+Build a custom call-to-action when the carousel reaches its end:
+
+```tsx
+function FeedWithCarouselCTA() {
+  const [showCTA, setShowCTA] = useState(false);
+
+  return (
+    <>
+      <ShortKitFeed
+        onCarouselActiveVideoCompleted={(event) => {
+          if (event.wasLast) {
+            setShowCTA(true);
+          }
+        }}
+      />
+      {showCTA && (
+        <View style={{ padding: 20, backgroundColor: 'rgba(0,0,0,0.8)' }}>
+          <Text style={{ color: 'white', fontSize: 16, marginBottom: 12 }}>
+            You've seen all videos in this collection!
+          </Text>
+          <Button
+            title="Explore More"
+            onPress={() => {
+              setShowCTA(false);
+            }}
+          />
+        </View>
+      )}
+    </>
+  );
+}
+```

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

@@ -163,11 +163,18 @@ class ReactOverlayHost(context: Context) : FrameLayout(context), FeedOverlay {
         timeDirty = false
         stopTimeCoalescing()
 
-        // Reset ALL cached state so recycled cells don't flash stale values.
+        // Reset ALL 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; the new player's flow subscriptions will
+        // re-emit current values after attach(), so defaults are only visible
+        // for the single frame between configure() and first emission.
         cachedCurrentTime = 0.0
         cachedDuration = 0.0
         cachedBuffered = 0.0
         cachedPlayerState = "idle"
+        cachedIsMuted = true
+        cachedPlaybackRate = 1.0
+        cachedCaptionsEnabled = false
         cachedActiveCue = null
         cachedFeedScrollPhase = null
 
@@ -185,9 +192,20 @@ class ReactOverlayHost(context: Context) : FrameLayout(context), FeedOverlay {
         } else {
             // Different item — send via event for React tree diff (not
             // updateInitProps which causes full Fabric remount).
+            // Includes full initial state so there's no stale-state window
+            // between configure() and activatePlayback(). Matches iOS.
             val params = Arguments.createMap().apply {
                 putString("surfaceId", surfaceId)
                 putString("item", ShortKitBridge.serializeContentItemToJSON(item))
+                putBoolean("isActive", false)
+                putString("playerState", cachedPlayerState)
+                putBoolean("isMuted", cachedIsMuted)
+                putDouble("playbackRate", cachedPlaybackRate)
+                putBoolean("captionsEnabled", cachedCaptionsEnabled)
+                cachedActiveCue?.let { putString("activeCue", it.toString()) }
+                    ?: putNull("activeCue")
+                cachedFeedScrollPhase?.let { putString("feedScrollPhase", it) }
+                    ?: putNull("feedScrollPhase")
             }
             ShortKitBridge.shared?.emitEvent("onOverlayItemChanged", params)
         }

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

@@ -17,7 +17,8 @@ import com.shortkit.sdk.model.FeedInput
 import com.shortkit.sdk.model.FeedScrollPhase
 import com.shortkit.sdk.model.FeedTransitionPhase
 import com.shortkit.sdk.model.ImageCarouselItem
-import com.shortkit.sdk.model.VideoCarouselItem
+import com.shortkit.sdk.model.VideoCarouselInput
+import com.shortkit.sdk.model.VideoCarouselVideoInput
 import com.shortkit.sdk.model.JsonValue
 import com.shortkit.sdk.model.PlayerState
 import com.shortkit.sdk.config.SurveyOverlayMode
@@ -366,22 +367,24 @@ class ShortKitBridge(
                         "videoCarousel" -> {
                             val itemObj = obj.optJSONObject("item") ?: continue
                             val videosArr = itemObj.optJSONArray("videos") ?: continue
-                            val videos = mutableListOf<ContentItem>()
+                            val videoInputs = mutableListOf<VideoCarouselVideoInput>()
                             for (i in 0 until videosArr.length()) {
                                 val videoObj = videosArr.getJSONObject(i)
-                                parseContentItem(videoObj)?.let { videos.add(it) }
+                                val playbackId = videoObj.optString("playbackId", null) ?: continue
+                                val fallbackUrl = videoObj.optString("fallbackUrl", null)
+                                videoInputs.add(VideoCarouselVideoInput(playbackId, fallbackUrl))
                             }
-                            if (videos.isEmpty()) continue
-                            val carouselItem = VideoCarouselItem(
+                            if (videoInputs.isEmpty()) continue
+                            val carouselInput = VideoCarouselInput(
                                 id = itemObj.getString("id"),
-                                videos = videos,
+                                videos = videoInputs,
                                 title = itemObj.optString("title", null),
                                 description = itemObj.optString("description", null),
                                 author = itemObj.optString("author", null),
                                 section = itemObj.optString("section", null),
                                 articleUrl = itemObj.optString("articleUrl", null),
                             )
-                            result.add(FeedInput.VideoCarousel(carouselItem))
+                            result.add(FeedInput.VideoCarousel(carouselInput))
                         }
                     }
                 }

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

@@ -144,6 +144,30 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
     @ReactMethod
     override fun skipToPrevious() { bridge?.skipToPrevious() }
 
+    // -----------------------------------------------------------------
+    // Carousel commands — stubs for PR 1.
+    // TODO: PR 2 — replace these stubs with real bridge to ShortKit.activeInstance.get().carousel
+    // -----------------------------------------------------------------
+
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    override fun carouselNext(): Boolean = false
+
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    override fun carouselPrevious(): Boolean = false
+
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    override fun carouselSetActiveIndex(index: Double): Boolean = false
+
+    // Carousel accessors — stubs for PR 1.
+    // onCarouselActiveVideoCompleted emitter intentionally unwired — never fires on Android in PR 1.
+    // PR 2 will subscribe to ShortKit.activeInstance.get().carousel.activeVideoCompleted.
+
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    override fun getCarouselActiveIndex(): Double = -1.0
+
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    override fun getCarouselVideoCount(): Double = 0.0
+
     @ReactMethod
     override fun setMuted(muted: Boolean) { bridge?.setMuted(muted) }
 
@@ -235,6 +259,21 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
         b.getStoryboardData(playbackId) { result -> promise.resolve(result) }
     }
 
+    // -----------------------------------------------------------------
+    // Download Management
+    // -----------------------------------------------------------------
+
+    @ReactMethod
+    override fun downloadVideo(itemId: String, mode: String, promise: Promise) {
+        // TODO: PR 2 — wire to ShortKit.activeInstance.get().downloadVideo
+        promise.reject("UNSUPPORTED", "downloadVideo not yet implemented on Android")
+    }
+
+    @ReactMethod
+    override fun cancelDownload() {
+        // TODO: PR 2 — wire to ShortKit.activeInstance.get().cancelDownload
+    }
+
     // -----------------------------------------------------------------
     // Event emission
     // -----------------------------------------------------------------
@@ -274,8 +313,12 @@ class ShortKitModule(reactContext: ReactApplicationContext) :
                 "onOverlayFeedScrollPhaseChanged" -> emitOnOverlayFeedScrollPhaseChanged(params)
                 "onOverlayTimeUpdate" -> emitOnOverlayTimeUpdate(params)
                 "onOverlayFullState" -> emitOnOverlayFullState(params)
+                "onOverlayItemChanged" -> emitOnOverlayItemChanged(params)
                 "onCarouselActiveImageChanged" -> emitOnCarouselActiveImageChanged(params)
+                "onCarouselItemChanged" -> emitOnCarouselItemChanged(params)
                 "onVideoCarouselActiveVideoChanged" -> emitOnVideoCarouselActiveVideoChanged(params)
+                "onVideoCarouselItemChanged" -> emitOnVideoCarouselItemChanged(params)
+                "onCarouselActiveVideoCompleted" -> emitOnCarouselActiveVideoCompleted(params)
                 else -> {
                     android.util.Log.w("SK:Module", "sendEvent: unknown event name '$name', using legacy emitter")
                     reactApplicationContext

package/ios/ReactCarouselOverlayHost.swift

@@ -37,12 +37,26 @@ import ShortKitSDK
     private var isActive = false
     private var activeImageIndex = 0
 
+    /// Currently configured item id — used to detect item transitions so we can
+    /// emit an event instead of triggering a full Fabric remount.
+    private var currentItemId: String?
+
+    /// Whether initial props have been pushed to the surface at least once.
+    /// First configure must go through setProperties (for item + surfaceId).
+    /// Subsequent item changes use the event path.
+    private var hasPushedInitialProps: Bool = false
+
     /// Serial queue for JPEG encoding + temp file writes (off main thread).
     private static let imageWriteQueue = DispatchQueue(label: "com.shortkit.carousel-image-write", qos: .userInitiated)
 
     /// Unique identifier for this overlay instance, used for event routing.
     let surfaceId = UUID().uuidString
 
+    // 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) {
@@ -62,6 +76,9 @@ import ShortKitSDK
     // MARK: - CarouselOverlay
 
     public func configure(with item: ImageCarouselItem) {
+        let isSameItem = item.id == currentItemId
+        currentItemId = item.id
+
         isActive = false
         activeImageIndex = 0
         createSurfaceIfNeeded()
@@ -103,20 +120,43 @@ import ShortKitSDK
             )
         }
 
-        if let data = try? JSONEncoder().encode(modifiedItem),
-           let json = String(data: data, encoding: .utf8) {
+        guard let data = try? JSONEncoder().encode(modifiedItem),
+              let json = String(data: data, encoding: .utf8) else { return }
+
+        // Surface lifecycle on item change:
+        //   - First mount: setProperties (via pendingProps if surface still
+        //     installing; directly otherwise).
+        //   - Subsequent item change with surface ready: emit
+        //     onCarouselItemChanged for React diff (no remount).
+        //   - Same item: no-op.
+        if !hasPushedInitialProps {
             let props: [String: Any] = [
                 "surfaceId": surfaceId,
                 "item": json,
             ]
             if let surface {
                 surface.setProperties(props)
+                hasPushedInitialProps = true
             } else {
                 pendingProps = props
             }
+        } else if !isSameItem {
+            emitItemChanged(json: json)
         }
     }
 
+    /// Emit onCarouselItemChanged with the new item JSON and a reset of
+    /// isActive/activeImageIndex. Replaces setProperties() on cell reuse so the
+    /// React tree does a diff instead of a full Fabric remount.
+    private func emitItemChanged(json: String) {
+        bridge?.emit("onCarouselItemChanged", body: [
+            "surfaceId": surfaceId,
+            "item": json,
+            "isActive": false,
+            "activeImageIndex": 0,
+        ])
+    }
+
     public func activatePlayback() {
         isActive = true
         bridge?.emit("onOverlayFullState", body: [
@@ -193,6 +233,7 @@ import ShortKitSDK
         if let pending = pendingProps {
             surf.setProperties(pending)
             pendingProps = nil
+            hasPushedInitialProps = true
         }
     }
 
@@ -203,7 +244,14 @@ 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.
     }
 }

package/ios/ReactOverlayHost.swift

@@ -55,6 +55,11 @@ import ShortKitSDK
     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
 
     /// Height of the scrubber touch area at the bottom of the overlay.
@@ -135,9 +140,16 @@ import ShortKitSDK
         timeCoalesceTimer?.invalidate()
         timeCoalesceTimer = nil
 
-        // Reset cached state so recycled cells don't flash stale values
+        // 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.
         cachedTime = (0, 0, 0)
         cachedPlayerState = "idle"
+        cachedIsMuted = true
+        cachedPlaybackRate = 1.0
+        cachedCaptionsEnabled = false
         cachedActiveCue = nil
         cachedActiveCueJson = nil
         cachedFeedScrollPhase = nil
@@ -145,14 +157,42 @@ import ShortKitSDK
 
         createSurfaceIfNeeded()
 
-        // Only push properties if the surface already exists.
-        // If the surface is still being created asynchronously,
-        // installSurface() will call pushInitialProperties() when ready.
+        // Surface lifecycle on item change:
+        //   - First mount (surface==nil): installSurface() will call
+        //     pushInitialProperties() once the surface is ready.
+        //   - Same item: no-op (overlay already has correct content).
+        //   - Different item AND surface exists: emit onOverlayItemChanged
+        //     event so React does a prop-diff update instead of the full
+        //     Fabric remount that setProperties() would trigger.
+        //     Matches the Android path in ReactOverlayHost.kt.
         if surface != nil && !isSameItem {
-            pushInitialProperties()
+            emitItemChanged(item: item)
         }
     }
 
+    /// Emit a single onOverlayItemChanged event carrying full initial state
+    /// for the new item. Replaces the pushInitialProperties() → setProperties()
+    /// path on cell reuse, avoiding a full Fabric root remount per swipe.
+    private func emitItemChanged(item: ContentItem) {
+        guard let itemData = try? JSONEncoder().encode(item),
+              let itemJSON = String(data: itemData, encoding: .utf8) else { return }
+
+        bridge?.emit("onOverlayItemChanged", body: [
+            "surfaceId": surfaceId,
+            "item": itemJSON,
+            // Full initial state — matches what pushInitialProperties() used to
+            // set via setProperties(). Ensures no stale-state window between
+            // configure() and activatePlayback().
+            "isActive": false,
+            "playerState": cachedPlayerState,
+            "isMuted": cachedIsMuted,
+            "playbackRate": cachedPlaybackRate,
+            "captionsEnabled": cachedCaptionsEnabled,
+            "activeCue": cachedActiveCueJson ?? NSNull(),
+            "feedScrollPhase": cachedFeedScrollPhase ?? NSNull(),
+        ])
+    }
+
     public func activatePlayback() {
         isActive = true
         startTimeCoalescing()
@@ -243,8 +283,14 @@ import ShortKitSDK
         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: - Player Subscriptions
@@ -342,6 +388,12 @@ import ShortKitSDK
                 switch phase {
                 case .dragging(let from):
                     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
+
                     if let data = try? JSONSerialization.data(withJSONObject: ["phase": "dragging", "fromId": from]),
                        let json = String(data: data, encoding: .utf8) {
                         self.cachedFeedScrollPhase = json
@@ -351,6 +403,11 @@ import ShortKitSDK
                     self.isDragging = false
                     self.cachedFeedScrollPhase = "{\"phase\":\"settled\"}"
 
+                    // Restart the timer now that the drag is over.
+                    if self.isActive {
+                        self.startTimeCoalescing()
+                    }
+
                     // Re-sync all state that was suppressed during the drag.
                     // Handles both normal swipes (new item's activatePlayback
                     // will also fire) and cancelled swipes (same item, no
@@ -384,7 +441,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,