@shortkitsdk/react-native 0.2.35 → 0.2.36

package/ios/ShortKitSDK.xcframework/ios-arm64_x86_64-simulator/ShortKitSDK.framework/Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.private.swiftinterface

@@ -556,6 +556,14 @@ public enum ShortKitFeedLifecycle {
     get
   }
 }
+public enum VideoCarouselCellLongPressState : Swift.String {
+  case began, ended, cancelled
+  public init?(rawValue: Swift.String)
+  public typealias RawValue = Swift.String
+  public var rawValue: Swift.String {
+    get
+  }
+}
 @objc @_hasMissingDesignatedInitializers @_Concurrency.MainActor @preconcurrency public class ShortKitFeedViewController : UIKit.UIViewController {
   @_Concurrency.MainActor @preconcurrency public var debugPanelFactory: ((_ active: Combine.CurrentValueSubject<ShortKitSDK.DebugMetrics, Swift.Never>, _ prev: Combine.CurrentValueSubject<ShortKitSDK.DebugMetrics, Swift.Never>, _ next: Combine.CurrentValueSubject<ShortKitSDK.DebugMetrics, Swift.Never>) -> UIKit.UIView)?
   @_Concurrency.MainActor @preconcurrency public var onDismiss: (() -> Swift.Void)?
@@ -567,6 +575,13 @@ public enum ShortKitFeedLifecycle {
     public let pageIndex: Swift.Int
   }
   @_Concurrency.MainActor @preconcurrency public var onVideoCarouselCellTap: ((ShortKitSDK.ShortKitFeedViewController.VideoCarouselCellTapPayload) -> Swift.Void)?
+  public struct VideoCarouselCellLongPressPayload {
+    public let id: Swift.String
+    public let index: Swift.Int
+    public let pageIndex: Swift.Int
+    public let state: ShortKitSDK.VideoCarouselCellLongPressState
+  }
+  @_Concurrency.MainActor @preconcurrency public var onVideoCarouselCellLongPress: ((ShortKitSDK.ShortKitFeedViewController.VideoCarouselCellLongPressPayload) -> Swift.Void)?
   @_Concurrency.MainActor @preconcurrency public var onRefreshStateChanged: ((ShortKitSDK.ShortKitRefreshState) -> Swift.Void)?
   @_Concurrency.MainActor @preconcurrency public var onFeedTransition: ((ShortKitSDK.FeedTransitionEvent) -> Swift.Void)?
   @_Concurrency.MainActor @preconcurrency public var isActiveSurface: Swift.Bool {
@@ -893,12 +908,13 @@ public struct VTTCue : Swift.Equatable, Swift.Sendable {
 public struct VideoCarouselInput : Swift.Codable, Swift.Equatable, Swift.Sendable {
   public let id: Swift.String
   public let videos: [ShortKitSDK.VideoCarouselVideoInput]
+  public let initialPageIndex: Swift.Int?
   public let title: Swift.String?
   public let description: Swift.String?
   public let author: Swift.String?
   public let section: Swift.String?
   public let articleUrl: Swift.String?
-  public init(id: Swift.String, videos: [ShortKitSDK.VideoCarouselVideoInput], title: Swift.String? = nil, description: Swift.String? = nil, author: Swift.String? = nil, section: Swift.String? = nil, articleUrl: Swift.String? = nil)
+  public init(id: Swift.String, videos: [ShortKitSDK.VideoCarouselVideoInput], initialPageIndex: Swift.Int? = nil, title: Swift.String? = nil, description: Swift.String? = nil, author: Swift.String? = nil, section: Swift.String? = nil, articleUrl: Swift.String? = nil)
   public static func == (a: ShortKitSDK.VideoCarouselInput, b: ShortKitSDK.VideoCarouselInput) -> Swift.Bool
   public func encode(to encoder: any Swift.Encoder) throws
   public init(from decoder: any Swift.Decoder) throws
@@ -906,12 +922,16 @@ public struct VideoCarouselInput : Swift.Codable, Swift.Equatable, Swift.Sendabl
 public struct VideoCarouselItem : Swift.Codable, Swift.Equatable, Swift.Sendable {
   public let id: Swift.String
   public let videos: [ShortKitSDK.ContentItem]
+  public let initialPageIndex: Swift.Int?
   public let title: Swift.String?
   public let description: Swift.String?
   public let author: Swift.String?
   public let section: Swift.String?
   public let articleUrl: Swift.String?
-  public init(id: Swift.String, videos: [ShortKitSDK.ContentItem], title: Swift.String? = nil, description: Swift.String? = nil, author: Swift.String? = nil, section: Swift.String? = nil, articleUrl: Swift.String? = nil)
+  public init(id: Swift.String, videos: [ShortKitSDK.ContentItem], initialPageIndex: Swift.Int? = nil, title: Swift.String? = nil, description: Swift.String? = nil, author: Swift.String? = nil, section: Swift.String? = nil, articleUrl: Swift.String? = nil)
+  public var clampedInitialPageIndex: Swift.Int {
+    get
+  }
   public static func == (a: ShortKitSDK.VideoCarouselItem, b: ShortKitSDK.VideoCarouselItem) -> Swift.Bool
   public func encode(to encoder: any Swift.Encoder) throws
   public init(from decoder: any Swift.Decoder) throws
@@ -1165,6 +1185,7 @@ public enum ContentSignal : Swift.Equatable, Swift.Sendable {
   final public func setMaxBitrate(_ bps: Swift.Int)
   final public func setCaptionsEnabled(_ enabled: Swift.Bool)
   final public func selectCaptionTrack(language: Swift.String)
+  final public func setFeedScrollEnabled(_ enabled: Swift.Bool)
   final public func dismissLiveRoom()
   final public func seekThumbnail(at time: Swift.Double) -> UIKit.UIImage?
   @objc deinit
@@ -1357,6 +1378,9 @@ extension ShortKitSDK.DownloadMode : Swift.Hashable {}
 extension ShortKitSDK.ShortKitFeedView : Swift.Sendable {}
 extension ShortKitSDK.ShortKitFeedLifecycle : Swift.Equatable {}
 extension ShortKitSDK.ShortKitFeedLifecycle : Swift.Hashable {}
+extension ShortKitSDK.VideoCarouselCellLongPressState : Swift.Equatable {}
+extension ShortKitSDK.VideoCarouselCellLongPressState : Swift.Hashable {}
+extension ShortKitSDK.VideoCarouselCellLongPressState : Swift.RawRepresentable {}
 extension ShortKitSDK.CaptionSource : Swift.Equatable {}
 extension ShortKitSDK.CaptionSource : Swift.Hashable {}
 extension ShortKitSDK.CaptionSource : Swift.RawRepresentable {}

package/ios/ShortKitSDK.xcframework/ios-arm64_x86_64-simulator/ShortKitSDK.framework/Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.swiftinterface

@@ -556,6 +556,14 @@ public enum ShortKitFeedLifecycle {
     get
   }
 }
+public enum VideoCarouselCellLongPressState : Swift.String {
+  case began, ended, cancelled
+  public init?(rawValue: Swift.String)
+  public typealias RawValue = Swift.String
+  public var rawValue: Swift.String {
+    get
+  }
+}
 @objc @_hasMissingDesignatedInitializers @_Concurrency.MainActor @preconcurrency public class ShortKitFeedViewController : UIKit.UIViewController {
   @_Concurrency.MainActor @preconcurrency public var debugPanelFactory: ((_ active: Combine.CurrentValueSubject<ShortKitSDK.DebugMetrics, Swift.Never>, _ prev: Combine.CurrentValueSubject<ShortKitSDK.DebugMetrics, Swift.Never>, _ next: Combine.CurrentValueSubject<ShortKitSDK.DebugMetrics, Swift.Never>) -> UIKit.UIView)?
   @_Concurrency.MainActor @preconcurrency public var onDismiss: (() -> Swift.Void)?
@@ -567,6 +575,13 @@ public enum ShortKitFeedLifecycle {
     public let pageIndex: Swift.Int
   }
   @_Concurrency.MainActor @preconcurrency public var onVideoCarouselCellTap: ((ShortKitSDK.ShortKitFeedViewController.VideoCarouselCellTapPayload) -> Swift.Void)?
+  public struct VideoCarouselCellLongPressPayload {
+    public let id: Swift.String
+    public let index: Swift.Int
+    public let pageIndex: Swift.Int
+    public let state: ShortKitSDK.VideoCarouselCellLongPressState
+  }
+  @_Concurrency.MainActor @preconcurrency public var onVideoCarouselCellLongPress: ((ShortKitSDK.ShortKitFeedViewController.VideoCarouselCellLongPressPayload) -> Swift.Void)?
   @_Concurrency.MainActor @preconcurrency public var onRefreshStateChanged: ((ShortKitSDK.ShortKitRefreshState) -> Swift.Void)?
   @_Concurrency.MainActor @preconcurrency public var onFeedTransition: ((ShortKitSDK.FeedTransitionEvent) -> Swift.Void)?
   @_Concurrency.MainActor @preconcurrency public var isActiveSurface: Swift.Bool {
@@ -893,12 +908,13 @@ public struct VTTCue : Swift.Equatable, Swift.Sendable {
 public struct VideoCarouselInput : Swift.Codable, Swift.Equatable, Swift.Sendable {
   public let id: Swift.String
   public let videos: [ShortKitSDK.VideoCarouselVideoInput]
+  public let initialPageIndex: Swift.Int?
   public let title: Swift.String?
   public let description: Swift.String?
   public let author: Swift.String?
   public let section: Swift.String?
   public let articleUrl: Swift.String?
-  public init(id: Swift.String, videos: [ShortKitSDK.VideoCarouselVideoInput], title: Swift.String? = nil, description: Swift.String? = nil, author: Swift.String? = nil, section: Swift.String? = nil, articleUrl: Swift.String? = nil)
+  public init(id: Swift.String, videos: [ShortKitSDK.VideoCarouselVideoInput], initialPageIndex: Swift.Int? = nil, title: Swift.String? = nil, description: Swift.String? = nil, author: Swift.String? = nil, section: Swift.String? = nil, articleUrl: Swift.String? = nil)
   public static func == (a: ShortKitSDK.VideoCarouselInput, b: ShortKitSDK.VideoCarouselInput) -> Swift.Bool
   public func encode(to encoder: any Swift.Encoder) throws
   public init(from decoder: any Swift.Decoder) throws
@@ -906,12 +922,16 @@ public struct VideoCarouselInput : Swift.Codable, Swift.Equatable, Swift.Sendabl
 public struct VideoCarouselItem : Swift.Codable, Swift.Equatable, Swift.Sendable {
   public let id: Swift.String
   public let videos: [ShortKitSDK.ContentItem]
+  public let initialPageIndex: Swift.Int?
   public let title: Swift.String?
   public let description: Swift.String?
   public let author: Swift.String?
   public let section: Swift.String?
   public let articleUrl: Swift.String?
-  public init(id: Swift.String, videos: [ShortKitSDK.ContentItem], title: Swift.String? = nil, description: Swift.String? = nil, author: Swift.String? = nil, section: Swift.String? = nil, articleUrl: Swift.String? = nil)
+  public init(id: Swift.String, videos: [ShortKitSDK.ContentItem], initialPageIndex: Swift.Int? = nil, title: Swift.String? = nil, description: Swift.String? = nil, author: Swift.String? = nil, section: Swift.String? = nil, articleUrl: Swift.String? = nil)
+  public var clampedInitialPageIndex: Swift.Int {
+    get
+  }
   public static func == (a: ShortKitSDK.VideoCarouselItem, b: ShortKitSDK.VideoCarouselItem) -> Swift.Bool
   public func encode(to encoder: any Swift.Encoder) throws
   public init(from decoder: any Swift.Decoder) throws
@@ -1165,6 +1185,7 @@ public enum ContentSignal : Swift.Equatable, Swift.Sendable {
   final public func setMaxBitrate(_ bps: Swift.Int)
   final public func setCaptionsEnabled(_ enabled: Swift.Bool)
   final public func selectCaptionTrack(language: Swift.String)
+  final public func setFeedScrollEnabled(_ enabled: Swift.Bool)
   final public func dismissLiveRoom()
   final public func seekThumbnail(at time: Swift.Double) -> UIKit.UIImage?
   @objc deinit
@@ -1357,6 +1378,9 @@ extension ShortKitSDK.DownloadMode : Swift.Hashable {}
 extension ShortKitSDK.ShortKitFeedView : Swift.Sendable {}
 extension ShortKitSDK.ShortKitFeedLifecycle : Swift.Equatable {}
 extension ShortKitSDK.ShortKitFeedLifecycle : Swift.Hashable {}
+extension ShortKitSDK.VideoCarouselCellLongPressState : Swift.Equatable {}
+extension ShortKitSDK.VideoCarouselCellLongPressState : Swift.Hashable {}
+extension ShortKitSDK.VideoCarouselCellLongPressState : Swift.RawRepresentable {}
 extension ShortKitSDK.CaptionSource : Swift.Equatable {}
 extension ShortKitSDK.CaptionSource : Swift.Hashable {}
 extension ShortKitSDK.CaptionSource : Swift.RawRepresentable {}

package/ios/ShortKitSDK.xcframework/ios-arm64_x86_64-simulator/ShortKitSDK.framework/_CodeSignature/CodeResources

@@ -10,39 +10,39 @@
 		</data>
 		<key>Info.plist</key>
 		<data>
-		OvrkhBvYgEeQNGBIL8Sk+zwmd+8=
+		WQrFujyFbopBKGGWbEKoC1woXeM=
 		</data>
 		<key>Modules/ShortKitSDK.swiftmodule/arm64-apple-ios-simulator.abi.json</key>
 		<data>
-		gUMbcAXcwCbvhUG1oUpN35PTUFU=
+		mwN55YBG0lFbYyqh8rFLlhydUhg=
 		</data>
 		<key>Modules/ShortKitSDK.swiftmodule/arm64-apple-ios-simulator.private.swiftinterface</key>
 		<data>
-		h6Cg/BD9N7YWvWXoaZDHIvsBs+Q=
+		VtQKD6iU2DxNLUgN8Nm9hVEd+LA=
 		</data>
 		<key>Modules/ShortKitSDK.swiftmodule/arm64-apple-ios-simulator.swiftdoc</key>
 		<data>
-		WN66xa1ykIuY1q8/q3xX14rO1qU=
+		RYBSyi3j5xH2WhtxZngr8vlpDDM=
 		</data>
 		<key>Modules/ShortKitSDK.swiftmodule/arm64-apple-ios-simulator.swiftinterface</key>
 		<data>
-		h6Cg/BD9N7YWvWXoaZDHIvsBs+Q=
+		VtQKD6iU2DxNLUgN8Nm9hVEd+LA=
 		</data>
 		<key>Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.abi.json</key>
 		<data>
-		gUMbcAXcwCbvhUG1oUpN35PTUFU=
+		mwN55YBG0lFbYyqh8rFLlhydUhg=
 		</data>
 		<key>Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.private.swiftinterface</key>
 		<data>
-		MiQorgvuaKDH14aSEh9ZJVYQfjo=
+		l/8aNIdTZYrYfdGjeCunQev+z2s=
 		</data>
 		<key>Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.swiftdoc</key>
 		<data>
-		K085KBZpASu5rTlrMsWTnd618bw=
+		dK384fZQxXLFp6AahpyFqGJOfnY=
 		</data>
 		<key>Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.swiftinterface</key>
 		<data>
-		MiQorgvuaKDH14aSEh9ZJVYQfjo=
+		l/8aNIdTZYrYfdGjeCunQev+z2s=
 		</data>
 		<key>Modules/module.modulemap</key>
 		<data>
@@ -66,56 +66,56 @@
 		<dict>
 			<key>hash2</key>
 			<data>
-			98/sM6XrtDCNV+236cKUe+xeL8df0JeaP/P+lEE01ew=
+			lPV80dTyQRi3R5Al7WxpvZYLMH1fLtDMRPj8kH++RCs=
 			</data>
 		</dict>
 		<key>Modules/ShortKitSDK.swiftmodule/arm64-apple-ios-simulator.private.swiftinterface</key>
 		<dict>
 			<key>hash2</key>
 			<data>
-			znlbvvD4pnPCRu9Aei74T4NdRxjdD2cIswo6AC4CsTA=
+			rf7zOX3BNWSgC2Lvt4rs/pTvzoqY4r2easqa7IcD/BY=
 			</data>
 		</dict>
 		<key>Modules/ShortKitSDK.swiftmodule/arm64-apple-ios-simulator.swiftdoc</key>
 		<dict>
 			<key>hash2</key>
 			<data>
-			Bn3ZIMIwiUnv4XCjNMicV7dy8dh3SrBhja0tyxB9BhU=
+			U33t59L18Q9DqIsgOyi6pcHV+IuHxLRdntw2IQW1DLo=
 			</data>
 		</dict>
 		<key>Modules/ShortKitSDK.swiftmodule/arm64-apple-ios-simulator.swiftinterface</key>
 		<dict>
 			<key>hash2</key>
 			<data>
-			znlbvvD4pnPCRu9Aei74T4NdRxjdD2cIswo6AC4CsTA=
+			rf7zOX3BNWSgC2Lvt4rs/pTvzoqY4r2easqa7IcD/BY=
 			</data>
 		</dict>
 		<key>Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.abi.json</key>
 		<dict>
 			<key>hash2</key>
 			<data>
-			98/sM6XrtDCNV+236cKUe+xeL8df0JeaP/P+lEE01ew=
+			lPV80dTyQRi3R5Al7WxpvZYLMH1fLtDMRPj8kH++RCs=
 			</data>
 		</dict>
 		<key>Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.private.swiftinterface</key>
 		<dict>
 			<key>hash2</key>
 			<data>
-			xoM3qxlgST57eK/vJqzmI4rFvll9ZmfMr4+El60Pq/c=
+			c3dj4IBlPLhIqbUCIQDEpGHL5WE7f1b16++z2hPOOTU=
 			</data>
 		</dict>
 		<key>Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.swiftdoc</key>
 		<dict>
 			<key>hash2</key>
 			<data>
-			IjhLI8nlyrN3P1GlQbXjVHfr4vkxgKw5OqJNmlk0Fv4=
+			kFhyC63KxDPM8/iRTzRd5M1FO7ojEQzF0migxa4EIpU=
 			</data>
 		</dict>
 		<key>Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.swiftinterface</key>
 		<dict>
 			<key>hash2</key>
 			<data>
-			xoM3qxlgST57eK/vJqzmI4rFvll9ZmfMr4+El60Pq/c=
+			c3dj4IBlPLhIqbUCIQDEpGHL5WE7f1b16++z2hPOOTU=
 			</data>
 		</dict>
 		<key>Modules/module.modulemap</key>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shortkitsdk/react-native",
-  "version": "0.2.35",
+  "version": "0.2.36",
   "description": "ShortKit React Native SDK — short-form video feed",
   "react-native": "src/index",
   "source": "src/index",

package/src/ShortKitCommands.ts

@@ -28,6 +28,26 @@ export const ShortKitCommands = {
     NativeShortKitModule?.sendContentSignal(signal),
   setMaxBitrate: (bitrate: number) =>
     NativeShortKitModule?.setMaxBitrate(bitrate),
+  /**
+   * Toggle feed scroll while an overlay-owned gesture is in flight.
+   *
+   * Hosts use this to grant exclusive priority to an in-flight gesture in
+   * an overlay (e.g. a horizontal scrubber drag) so the feed's pan
+   * recognizer can't steal the touch mid-drag. Pair the call: pass
+   * `false` when the host gesture starts (RN PanResponder grant), `true`
+   * when it ends or is cancelled (release / terminate).
+   *
+   * iOS: toggles the active feed view controller's
+   * `collectionView.panGestureRecognizer.isEnabled`. No-op when no feed
+   * VC is currently active.
+   *
+   * Android: fans out across every registered feed (including any masked
+   * underlay), toggling each `ViewPager2.isUserInputEnabled`. Intentional
+   * divergence from iOS — broader fan-out is simpler and has the same
+   * user-visible effect since only the active feed is interactable.
+   */
+  setFeedScrollEnabled: (enabled: boolean) =>
+    NativeShortKitModule?.setFeedScrollEnabled(enabled),
   prefetchStoryboard: (playbackId: string) =>
     NativeShortKitModule?.prefetchStoryboard(playbackId),
   getStoryboardData: (playbackId: string): Promise<string | null> =>

package/src/ShortKitFeed.tsx

@@ -47,6 +47,7 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
     onFeedReady,
     onCarouselActiveVideoCompleted,
     onVideoCarouselCellTap,
+    onVideoCarouselCellLongPress,
     debugPanel,
   } = props;
 
@@ -126,6 +127,26 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
     return () => subscription.remove();
   }, [feedId, onVideoCarouselCellTap]);
 
+  // Subscribe to per-feed video-carousel cell long-press events
+  useEffect(() => {
+    if (!NativeShortKitModule || !onVideoCarouselCellLongPress) return;
+
+    const subscription = NativeShortKitModule.onVideoCarouselCellLongPress((event) => {
+      if (event.feedId === feedId) {
+        // Bridge emits `state` as plain `string` (codegen constraint);
+        // the native side only ever emits these three values.
+        onVideoCarouselCellLongPress({
+          id: event.id,
+          index: event.index,
+          pageIndex: event.pageIndex,
+          state: event.state as 'began' | 'ended' | 'cancelled',
+        });
+      }
+    });
+
+    return () => subscription.remove();
+  }, [feedId, onVideoCarouselCellLongPress]);
+
   // Register overlay components before native view mounts.
   // useLayoutEffect fires after commit but before paint — before
   // didMoveToWindow/onAttachedToWindow on the native view.

package/src/specs/NativeShortKitModule.ts

@@ -127,6 +127,14 @@ type VideoCarouselCellTapEvent = Readonly<{
   pageIndex: Int32;
 }>;
 
+type VideoCarouselCellLongPressEvent = Readonly<{
+  feedId: string;
+  id: string;
+  index: Int32;
+  pageIndex: Int32;
+  state: string;     // "began" | "ended" | "cancelled" — string for codegen compat
+}>;
+
 type WidgetCardTapEvent = Readonly<{
   widgetId: string;
   playbackId: string;
@@ -292,6 +300,7 @@ export interface Spec extends TurboModule {
   selectCaptionTrack(language: string): void;
   sendContentSignal(signal: string): void;
   setMaxBitrate(bitrate: Double): void;
+  setFeedScrollEnabled(enabled: boolean): void;
 
   // --- Custom feed ---
   setFeedItems(feedId: string, items: string, startAtId: string | null): void;
@@ -336,6 +345,7 @@ export interface Spec extends TurboModule {
   readonly onDidFetchContentItems: EventEmitter<DidFetchContentItemsEvent>;
   readonly onFeedReady: EventEmitter<FeedReadyEvent>;
   readonly onVideoCarouselCellTap: EventEmitter<VideoCarouselCellTapEvent>;
+  readonly onVideoCarouselCellLongPress: EventEmitter<VideoCarouselCellLongPressEvent>;
   readonly onWidgetCardTap: EventEmitter<WidgetCardTapEvent>;
 
   // --- Overlay per-surface events ---

package/src/types.ts

@@ -144,6 +144,12 @@ export interface ImageCarouselItem {
 export interface VideoCarouselItem {
   id: string;
   videos: ContentItem[];
+  /**
+   * Zero-based index of the page the carousel landed on. Mirrors
+   * `VideoCarouselInput.initialPageIndex` from the host's input. Available
+   * to overlay components for reading the active page on first paint.
+   */
+  initialPageIndex?: number;
   title?: string;
   description?: string;
   author?: string;
@@ -175,6 +181,18 @@ export interface VideoCarouselVideoInput {
 export interface VideoCarouselInput {
   id: string;
   videos: VideoCarouselVideoInput[];
+  /**
+   * Zero-based index of the page the carousel should land on the first time
+   * it becomes visible (vertical-arrival or initial mount). Defaults to 0.
+   * Out-of-range values are clamped to a valid index.
+   *
+   * **Has no effect after the carousel is first configured.** To move the
+   * user imperatively after landing, use
+   * `useShortKitCarousel().setActiveIndex(n)`. Re-rendering with a new
+   * `initialPageIndex` on the same `id` is ignored — change the `id` to force
+   * a re-bind if you genuinely want to land on a different page.
+   */
+  initialPageIndex?: number;
   title?: string;
   description?: string;
   author?: string;
@@ -426,6 +444,23 @@ export interface ShortKitFeedProps {
     index: number;
     pageIndex: number;
   }) => void;
+  /**
+   * Fires for the lifecycle of a video-carousel cell long-press: `began`
+   * after a short native press delay, `ended` on touch release, and
+   * `cancelled` on user finger movement past ~10pt or when the cell is
+   * recycled (e.g. by `setFeedItems`).
+   *
+   * The recognizer runs simultaneously with the carousel's horizontal pan
+   * and the feed's vertical pan — it does not block scrolling. The intended
+   * use case is Instagram-style hold-to-pause: pause playback and hide
+   * overlay chrome on `began`, restore them on `ended` / `cancelled`.
+   */
+  onVideoCarouselCellLongPress?: (event: {
+    id: string;
+    index: number;
+    pageIndex: number;
+    state: 'began' | 'ended' | 'cancelled';
+  }) => void;
 }
 
 /**