@shortkitsdk/react-native 0.2.11 → 0.2.12

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

@@ -169,6 +169,15 @@ public enum FeedHeight : Swift.Codable, Swift.Equatable, Swift.Sendable {
   public func encode(to encoder: any Swift.Encoder) throws
   public init(from decoder: any Swift.Decoder) throws
 }
+public enum ScrollAxis : Swift.String, Swift.Codable, Swift.Equatable, Swift.Sendable {
+  case vertical
+  case horizontal
+  public init?(rawValue: Swift.String)
+  public typealias RawValue = Swift.String
+  public var rawValue: Swift.String {
+    get
+  }
+}
 public enum FeedSource : Swift.String, Swift.Codable, Swift.Equatable, Swift.Sendable {
   case algorithmic
   case custom
@@ -191,6 +200,7 @@ public struct FeedFilter : Swift.Codable, Swift.Equatable, Swift.Sendable {
 }
 public struct FeedConfig : Swift.Codable {
   public var feedHeight: ShortKitSDK.FeedHeight
+  public var scrollAxis: ShortKitSDK.ScrollAxis
   public var videoOverlay: ShortKitSDK.VideoOverlayMode
   public var carouselOverlay: ShortKitSDK.CarouselOverlayMode
   public var surveyOverlay: ShortKitSDK.SurveyOverlayMode
@@ -201,7 +211,7 @@ public struct FeedConfig : Swift.Codable {
   public var coldStartEnabled: Swift.Bool
   public var filter: ShortKitSDK.FeedFilter?
   public var preload: ShortKitSDK.FeedPreload?
-  public init(feedHeight: ShortKitSDK.FeedHeight = .fullscreen, videoOverlay: ShortKitSDK.VideoOverlayMode = .none, carouselOverlay: ShortKitSDK.CarouselOverlayMode = .none, surveyOverlay: ShortKitSDK.SurveyOverlayMode = .none, adOverlay: ShortKitSDK.AdOverlayMode = .none, muteOnStart: Swift.Bool = true, autoplay: Swift.Bool = true, feedSource: ShortKitSDK.FeedSource = .algorithmic, coldStartEnabled: Swift.Bool = false, filter: ShortKitSDK.FeedFilter? = nil, preload: ShortKitSDK.FeedPreload? = nil)
+  public init(feedHeight: ShortKitSDK.FeedHeight = .fullscreen, scrollAxis: ShortKitSDK.ScrollAxis = .vertical, videoOverlay: ShortKitSDK.VideoOverlayMode = .none, carouselOverlay: ShortKitSDK.CarouselOverlayMode = .none, surveyOverlay: ShortKitSDK.SurveyOverlayMode = .none, adOverlay: ShortKitSDK.AdOverlayMode = .none, muteOnStart: Swift.Bool = true, autoplay: Swift.Bool = true, feedSource: ShortKitSDK.FeedSource = .algorithmic, coldStartEnabled: Swift.Bool = false, filter: ShortKitSDK.FeedFilter? = nil, preload: ShortKitSDK.FeedPreload? = nil)
   public func encode(to encoder: any Swift.Encoder) throws
   public init(from decoder: any Swift.Decoder) throws
 }
@@ -266,7 +276,7 @@ extension ShortKitSDK.ShortKitDelegate {
   @objc deinit
 }
 @_Concurrency.MainActor @preconcurrency public struct ShortKitFeedView : SwiftUI.UIViewControllerRepresentable {
-  @_Concurrency.MainActor @preconcurrency public init(shortKit: ShortKitSDK.ShortKit, config: ShortKitSDK.FeedConfig)
+  @_Concurrency.MainActor @preconcurrency public init(shortKit: ShortKitSDK.ShortKit, config: ShortKitSDK.FeedConfig = FeedConfig(), onFeedReady: (() -> Swift.Void)? = nil)
   @_Concurrency.MainActor @preconcurrency public func makeCoordinator() -> ShortKitSDK.ShortKitFeedView.Coordinator
   @_Concurrency.MainActor @preconcurrency public func makeUIViewController(context: ShortKitSDK.ShortKitFeedView.Context) -> ShortKitSDK.ShortKitFeedViewController
   @_Concurrency.MainActor @preconcurrency public func updateUIViewController(_ uiViewController: ShortKitSDK.ShortKitFeedViewController, context: ShortKitSDK.ShortKitFeedView.Context)
@@ -280,6 +290,7 @@ extension ShortKitSDK.ShortKitDelegate {
 @objc @_hasMissingDesignatedInitializers @_Concurrency.MainActor @preconcurrency public class ShortKitFeedViewController : UIKit.UIViewController {
   @_Concurrency.MainActor @preconcurrency public var onDismiss: (() -> Swift.Void)?
   @_Concurrency.MainActor @preconcurrency public var onRemainingContentCountChange: ((Swift.Int) -> Swift.Void)?
+  @_Concurrency.MainActor @preconcurrency public var onFeedReady: (() -> Swift.Void)?
   @_Concurrency.MainActor @preconcurrency public init(shortKit: ShortKitSDK.ShortKit, config: ShortKitSDK.FeedConfig, startAtItemId: Swift.String? = nil)
   @_Concurrency.MainActor public func setFeedItems(_ items: [ShortKitSDK.FeedInput])
   @_Concurrency.MainActor public func appendFeedItems(_ items: [ShortKitSDK.FeedInput])
@@ -289,6 +300,9 @@ extension ShortKitSDK.ShortKitDelegate {
   @_Concurrency.MainActor @preconcurrency @objc override dynamic public func viewWillAppear(_ animated: Swift.Bool)
   @_Concurrency.MainActor @preconcurrency @objc override dynamic public func viewDidAppear(_ animated: Swift.Bool)
   @_Concurrency.MainActor @preconcurrency @objc override dynamic public func viewWillDisappear(_ animated: Swift.Bool)
+  @_Concurrency.MainActor @preconcurrency public func setBridgeManaged()
+  @_Concurrency.MainActor @preconcurrency public func activate()
+  @_Concurrency.MainActor @preconcurrency public func deactivate()
   @_Concurrency.MainActor @preconcurrency @objc override dynamic public func viewDidDisappear(_ animated: Swift.Bool)
   @_Concurrency.MainActor @preconcurrency @objc override dynamic public var supportedInterfaceOrientations: UIKit.UIInterfaceOrientationMask {
     @objc get
@@ -689,9 +703,6 @@ public enum ContentSignal : Swift.Equatable, Swift.Sendable {
   final public var remainingContentCount: Combine.AnyPublisher<Swift.Int, Swift.Never> {
     get
   }
-  final public var feedReady: Combine.AnyPublisher<Swift.Void, Swift.Never> {
-    get
-  }
   final public var currentItemValue: ShortKitSDK.ContentItem? {
     get
   }
@@ -754,6 +765,7 @@ final public class ShortKit {
   final public var loadingViewProvider: (() -> UIKit.UIView)?
   public init(apiKey: Swift.String, userId: Swift.String? = nil, adProvider: (any ShortKitSDK.ShortKitAdProvider)? = nil, clientAppName: Swift.String? = nil, clientAppVersion: Swift.String? = nil, customDimensions: [Swift.String : Swift.String]? = nil, loadingViewProvider: (() -> UIKit.UIView)? = nil)
   final public func preloadFeed(filter: ShortKitSDK.FeedFilter? = nil, limit: Swift.Int = 10) -> ShortKitSDK.FeedPreload
+  final public func preloadFeed(items: [ShortKitSDK.FeedInput]) -> ShortKitSDK.FeedPreload
   final public func fetchContent(limit: Swift.Int = 10, filter: ShortKitSDK.FeedFilter? = nil) async throws -> [ShortKitSDK.ContentItem]
   final public func setUserId(_ id: Swift.String)
   final public func clearUserId()
@@ -835,6 +847,8 @@ public struct WidgetConfig {
 }
 extension ShortKitSDK.AdQuartile : Swift.Equatable {}
 extension ShortKitSDK.AdQuartile : Swift.Hashable {}
+extension ShortKitSDK.ScrollAxis : Swift.Hashable {}
+extension ShortKitSDK.ScrollAxis : Swift.RawRepresentable {}
 extension ShortKitSDK.FeedSource : Swift.Hashable {}
 extension ShortKitSDK.FeedSource : Swift.RawRepresentable {}
 extension ShortKitSDK.ShortKitFeedView : Swift.Sendable {}

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

@@ -169,6 +169,15 @@ public enum FeedHeight : Swift.Codable, Swift.Equatable, Swift.Sendable {
   public func encode(to encoder: any Swift.Encoder) throws
   public init(from decoder: any Swift.Decoder) throws
 }
+public enum ScrollAxis : Swift.String, Swift.Codable, Swift.Equatable, Swift.Sendable {
+  case vertical
+  case horizontal
+  public init?(rawValue: Swift.String)
+  public typealias RawValue = Swift.String
+  public var rawValue: Swift.String {
+    get
+  }
+}
 public enum FeedSource : Swift.String, Swift.Codable, Swift.Equatable, Swift.Sendable {
   case algorithmic
   case custom
@@ -191,6 +200,7 @@ public struct FeedFilter : Swift.Codable, Swift.Equatable, Swift.Sendable {
 }
 public struct FeedConfig : Swift.Codable {
   public var feedHeight: ShortKitSDK.FeedHeight
+  public var scrollAxis: ShortKitSDK.ScrollAxis
   public var videoOverlay: ShortKitSDK.VideoOverlayMode
   public var carouselOverlay: ShortKitSDK.CarouselOverlayMode
   public var surveyOverlay: ShortKitSDK.SurveyOverlayMode
@@ -201,7 +211,7 @@ public struct FeedConfig : Swift.Codable {
   public var coldStartEnabled: Swift.Bool
   public var filter: ShortKitSDK.FeedFilter?
   public var preload: ShortKitSDK.FeedPreload?
-  public init(feedHeight: ShortKitSDK.FeedHeight = .fullscreen, videoOverlay: ShortKitSDK.VideoOverlayMode = .none, carouselOverlay: ShortKitSDK.CarouselOverlayMode = .none, surveyOverlay: ShortKitSDK.SurveyOverlayMode = .none, adOverlay: ShortKitSDK.AdOverlayMode = .none, muteOnStart: Swift.Bool = true, autoplay: Swift.Bool = true, feedSource: ShortKitSDK.FeedSource = .algorithmic, coldStartEnabled: Swift.Bool = false, filter: ShortKitSDK.FeedFilter? = nil, preload: ShortKitSDK.FeedPreload? = nil)
+  public init(feedHeight: ShortKitSDK.FeedHeight = .fullscreen, scrollAxis: ShortKitSDK.ScrollAxis = .vertical, videoOverlay: ShortKitSDK.VideoOverlayMode = .none, carouselOverlay: ShortKitSDK.CarouselOverlayMode = .none, surveyOverlay: ShortKitSDK.SurveyOverlayMode = .none, adOverlay: ShortKitSDK.AdOverlayMode = .none, muteOnStart: Swift.Bool = true, autoplay: Swift.Bool = true, feedSource: ShortKitSDK.FeedSource = .algorithmic, coldStartEnabled: Swift.Bool = false, filter: ShortKitSDK.FeedFilter? = nil, preload: ShortKitSDK.FeedPreload? = nil)
   public func encode(to encoder: any Swift.Encoder) throws
   public init(from decoder: any Swift.Decoder) throws
 }
@@ -266,7 +276,7 @@ extension ShortKitSDK.ShortKitDelegate {
   @objc deinit
 }
 @_Concurrency.MainActor @preconcurrency public struct ShortKitFeedView : SwiftUI.UIViewControllerRepresentable {
-  @_Concurrency.MainActor @preconcurrency public init(shortKit: ShortKitSDK.ShortKit, config: ShortKitSDK.FeedConfig)
+  @_Concurrency.MainActor @preconcurrency public init(shortKit: ShortKitSDK.ShortKit, config: ShortKitSDK.FeedConfig = FeedConfig(), onFeedReady: (() -> Swift.Void)? = nil)
   @_Concurrency.MainActor @preconcurrency public func makeCoordinator() -> ShortKitSDK.ShortKitFeedView.Coordinator
   @_Concurrency.MainActor @preconcurrency public func makeUIViewController(context: ShortKitSDK.ShortKitFeedView.Context) -> ShortKitSDK.ShortKitFeedViewController
   @_Concurrency.MainActor @preconcurrency public func updateUIViewController(_ uiViewController: ShortKitSDK.ShortKitFeedViewController, context: ShortKitSDK.ShortKitFeedView.Context)
@@ -280,6 +290,7 @@ extension ShortKitSDK.ShortKitDelegate {
 @objc @_hasMissingDesignatedInitializers @_Concurrency.MainActor @preconcurrency public class ShortKitFeedViewController : UIKit.UIViewController {
   @_Concurrency.MainActor @preconcurrency public var onDismiss: (() -> Swift.Void)?
   @_Concurrency.MainActor @preconcurrency public var onRemainingContentCountChange: ((Swift.Int) -> Swift.Void)?
+  @_Concurrency.MainActor @preconcurrency public var onFeedReady: (() -> Swift.Void)?
   @_Concurrency.MainActor @preconcurrency public init(shortKit: ShortKitSDK.ShortKit, config: ShortKitSDK.FeedConfig, startAtItemId: Swift.String? = nil)
   @_Concurrency.MainActor public func setFeedItems(_ items: [ShortKitSDK.FeedInput])
   @_Concurrency.MainActor public func appendFeedItems(_ items: [ShortKitSDK.FeedInput])
@@ -289,6 +300,9 @@ extension ShortKitSDK.ShortKitDelegate {
   @_Concurrency.MainActor @preconcurrency @objc override dynamic public func viewWillAppear(_ animated: Swift.Bool)
   @_Concurrency.MainActor @preconcurrency @objc override dynamic public func viewDidAppear(_ animated: Swift.Bool)
   @_Concurrency.MainActor @preconcurrency @objc override dynamic public func viewWillDisappear(_ animated: Swift.Bool)
+  @_Concurrency.MainActor @preconcurrency public func setBridgeManaged()
+  @_Concurrency.MainActor @preconcurrency public func activate()
+  @_Concurrency.MainActor @preconcurrency public func deactivate()
   @_Concurrency.MainActor @preconcurrency @objc override dynamic public func viewDidDisappear(_ animated: Swift.Bool)
   @_Concurrency.MainActor @preconcurrency @objc override dynamic public var supportedInterfaceOrientations: UIKit.UIInterfaceOrientationMask {
     @objc get
@@ -689,9 +703,6 @@ public enum ContentSignal : Swift.Equatable, Swift.Sendable {
   final public var remainingContentCount: Combine.AnyPublisher<Swift.Int, Swift.Never> {
     get
   }
-  final public var feedReady: Combine.AnyPublisher<Swift.Void, Swift.Never> {
-    get
-  }
   final public var currentItemValue: ShortKitSDK.ContentItem? {
     get
   }
@@ -754,6 +765,7 @@ final public class ShortKit {
   final public var loadingViewProvider: (() -> UIKit.UIView)?
   public init(apiKey: Swift.String, userId: Swift.String? = nil, adProvider: (any ShortKitSDK.ShortKitAdProvider)? = nil, clientAppName: Swift.String? = nil, clientAppVersion: Swift.String? = nil, customDimensions: [Swift.String : Swift.String]? = nil, loadingViewProvider: (() -> UIKit.UIView)? = nil)
   final public func preloadFeed(filter: ShortKitSDK.FeedFilter? = nil, limit: Swift.Int = 10) -> ShortKitSDK.FeedPreload
+  final public func preloadFeed(items: [ShortKitSDK.FeedInput]) -> ShortKitSDK.FeedPreload
   final public func fetchContent(limit: Swift.Int = 10, filter: ShortKitSDK.FeedFilter? = nil) async throws -> [ShortKitSDK.ContentItem]
   final public func setUserId(_ id: Swift.String)
   final public func clearUserId()
@@ -835,6 +847,8 @@ public struct WidgetConfig {
 }
 extension ShortKitSDK.AdQuartile : Swift.Equatable {}
 extension ShortKitSDK.AdQuartile : Swift.Hashable {}
+extension ShortKitSDK.ScrollAxis : Swift.Hashable {}
+extension ShortKitSDK.ScrollAxis : Swift.RawRepresentable {}
 extension ShortKitSDK.FeedSource : Swift.Hashable {}
 extension ShortKitSDK.FeedSource : Swift.RawRepresentable {}
 extension ShortKitSDK.ShortKitFeedView : Swift.Sendable {}

package/package.json

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

package/src/ShortKitContext.ts

@@ -3,6 +3,7 @@ import type {
   ContentItem,
   FeedConfig,
   FeedFilter,
+  FeedInput,
   PlayerTime,
   PlayerState,
   CaptionTrack,
@@ -45,7 +46,7 @@ export interface ShortKitContextValue {
   fetchContent: (limit?: number, filter?: FeedFilter) => Promise<ContentItem[]>;
 
   // Preload
-  preloadFeed: (config?: Partial<FeedConfig>) => Promise<string>;
+  preloadFeed: (config?: Partial<FeedConfig>, items?: FeedInput[]) => Promise<string>;
 
   // Storyboard / seek thumbnails
   prefetchStoryboard: (playbackId: string) => void;

package/src/ShortKitFeed.tsx

@@ -41,6 +41,7 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
     onRefreshRequested,
     onDidFetchContentItems,
     onRemainingContentCountChange,
+    onFeedReady,
   } = props;
 
   const context = useContext(ShortKitContext);
@@ -79,6 +80,19 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
     return () => subscription.remove();
   }, [feedId, onRemainingContentCountChange]);
 
+  // Subscribe to per-feed ready event
+  useEffect(() => {
+    if (!NativeShortKitModule || !onFeedReady) return;
+
+    const subscription = NativeShortKitModule.onFeedReady((event) => {
+      if (event.feedId === feedId) {
+        onFeedReady();
+      }
+    });
+
+    return () => subscription.remove();
+  }, [feedId, onFeedReady]);
+
   // Register overlay components before native view mounts.
   // useLayoutEffect fires after commit but before paint — before
   // didMoveToWindow/onAttachedToWindow on the native view.

package/src/ShortKitOverlaySurface.tsx

@@ -1,9 +1,11 @@
-import React, { useEffect, useMemo, useState } from 'react';
-import { AppRegistry, DeviceEventEmitter, Platform } from 'react-native';
+import React, { useEffect, useState } from 'react';
+import { AppRegistry, View, Text } from 'react-native';
 import type { OverlayProps, PlayerState, PlayerTime, FeedScrollPhase } from './types';
 import { deserializeContentItem } from './serialization';
 import NativeShortKitModule from './specs/NativeShortKitModule';
 
+const SK_OVERLAY_TAG = '[ShortKit:OverlaySurface]';
+
 // Named registry — supports different overlay components per feed
 const _overlayRegistry = new Map<string, React.ComponentType<OverlayProps>>();
 
@@ -16,7 +18,9 @@ export function registerOverlayComponent(
   name: string,
   component: React.ComponentType<OverlayProps>,
 ) {
-  if (_overlayRegistry.has(name)) return;
+  if (_overlayRegistry.has(name)) {
+    return;
+  }
   _overlayRegistry.set(name, component);
 
   const moduleName = `ShortKitOverlay_${name}`;
@@ -27,6 +31,47 @@ export function registerOverlayComponent(
   });
 }
 
+/**
+ * Error boundary that catches crashes inside the overlay component.
+ * Without this, a crash in an isolated React surface is silent on Android.
+ */
+class OverlayErrorBoundary extends React.Component<
+  { surfaceId?: string; overlayName: string; children: React.ReactNode },
+  { error: Error | null }
+> {
+  state: { error: Error | null } = { error: null };
+
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: React.ErrorInfo) {
+    console.error(
+      `${SK_OVERLAY_TAG} CRASH in overlay '${this.props.overlayName}' (surfaceId=${this.props.surfaceId}):`,
+      error.message,
+      '\nComponent stack:',
+      info.componentStack,
+    );
+  }
+
+  render() {
+    if (this.state.error) {
+      // Render a visible red indicator in __DEV__ so it's obvious
+      if (__DEV__) {
+        return (
+          <View style={{ flex: 1, backgroundColor: 'rgba(255,0,0,0.3)', justifyContent: 'center', alignItems: 'center', padding: 20 }}>
+            <Text style={{ color: 'white', fontSize: 14, textAlign: 'center' }}>
+              {`Overlay '${this.props.overlayName}' crashed:\n${this.state.error.message}`}
+            </Text>
+          </View>
+        );
+      }
+      return null;
+    }
+    return this.props.children;
+  }
+}
+
 /** Raw props received from native appProperties (set once per item in configure()). */
 interface RawOverlaySurfaceProps {
   surfaceId?: string;
@@ -47,14 +92,9 @@ interface InnerProps extends RawOverlaySurfaceProps {
 /**
  * Subscribe to a native overlay event, filtered by surfaceId.
  *
- * iOS and Android new arch emit events through different paths:
- * - iOS: _eventEmitterCallback (codegen path) — only the codegen EventEmitter
- *   subscriptions (NativeShortKitModule.onXxx) receive these events.
- * - Android: getJSModule(RCTDeviceEventEmitter).emit() — only
- *   DeviceEventEmitter.addListener() receives these events (codegen
- *   EventEmitter subscriptions do NOT receive them on Android new arch).
- *
- * We branch per platform to use the path that actually delivers events.
+ * Both iOS and Android (new arch) emit events through the codegen
+ * EventEmitter path (mEventEmitterCallback / JSI direct channel).
+ * We subscribe via the codegen emitter method on the TurboModule.
  */
 function useOverlayEvent<T extends { surfaceId: string }>(
   eventName: string,
@@ -66,19 +106,11 @@ function useOverlayEvent<T extends { surfaceId: string }>(
 
     let sub: { remove: () => void } | undefined;
 
-    if (Platform.OS === 'ios') {
-      // iOS new arch: events come through the codegen EventEmitterCallback.
-      // Access the codegen emitter method by name on the TurboModule.
-      const emitter = NativeShortKitModule?.[eventName as keyof typeof NativeShortKitModule];
-      if (typeof emitter === 'function') {
-        sub = (emitter as (cb: (e: T) => void) => { remove: () => void })((e: T) => {
-          if (e.surfaceId !== surfaceId) return;
-          handler(e);
-        });
-      }
-    } else {
-      // Android new arch: events come through RCTDeviceEventEmitter.emit().
-      sub = DeviceEventEmitter.addListener(eventName, (e: T) => {
+    // Both platforms: events come through the codegen EventEmitterCallback.
+    // Access the codegen emitter method by name on the TurboModule.
+    const emitter = NativeShortKitModule?.[eventName as keyof typeof NativeShortKitModule];
+    if (typeof emitter === 'function') {
+      sub = (emitter as (cb: (e: T) => void) => { remove: () => void })((e: T) => {
         if (e.surfaceId !== surfaceId) return;
         handler(e);
       });
@@ -90,13 +122,24 @@ function useOverlayEvent<T extends { surfaceId: string }>(
 
 function ShortKitOverlaySurfaceInner(props: InnerProps) {
   const Component = _overlayRegistry.get(props.overlayName);
-  if (!Component) return null;
+  if (!Component) {
+    console.error(`${SK_OVERLAY_TAG} ShortKitOverlaySurfaceInner: Component NOT FOUND in registry for '${props.overlayName}'. Registered names: [${Array.from(_overlayRegistry.keys()).join(', ')}]`);
+    return null;
+  }
 
-  const item = useMemo(
-    () => (props.item ? deserializeContentItem(props.item) : null),
-    [props.item],
+  const [item, setItem] = useState(() =>
+    props.item ? deserializeContentItem(props.item) : null,
   );
 
+  // Sync item from props when surface is first mounted or remounted via updateInitProps
+  const prevPropsItemRef = React.useRef(props.item);
+  if (props.item !== prevPropsItemRef.current) {
+    prevPropsItemRef.current = props.item;
+    // Synchronous state update during render — React restarts with new state
+    // before committing, so stale frame is never painted.
+    setItem(props.item ? deserializeContentItem(props.item) : null);
+  }
+
   const sid = props.surfaceId;
 
   // Initialize state from surface properties (set once in configure()).
@@ -141,6 +184,24 @@ function ShortKitOverlaySurfaceInner(props: InnerProps) {
 
   // --- Event subscriptions (filtered by surfaceId) ---
 
+  // Item changed via event (not updateInitProps) — triggers React DIFF
+  // instead of full remount. Uses DeviceEventEmitter because this event
+  // is not in the TurboModule spec (avoids native codegen changes).
+  useEffect(() => {
+    if (!sid) return;
+    const { DeviceEventEmitter } = require('react-native');
+    const sub = DeviceEventEmitter.addListener('onOverlayItemChanged', (e: { surfaceId: string; item: string }) => {
+      if (e.surfaceId !== sid) return;
+      const newItem = e.item ? deserializeContentItem(e.item) : null;
+      if (newItem) setItem(newItem);
+      // Reset playback state for the new item
+      setIsActive(false);
+      setPlayerState('idle' as PlayerState);
+      setTime({ current: 0, duration: 0, buffered: 0 });
+    });
+    return () => sub.remove();
+  }, [sid]);
+
   useOverlayEvent<{ surfaceId: string; isActive: boolean }>(
     'onOverlayActiveChanged', sid,
     (e) => setIsActive(e.isActive),
@@ -175,31 +236,78 @@ function ShortKitOverlaySurfaceInner(props: InnerProps) {
     'onOverlayFeedScrollPhaseChanged', sid,
     (e) => {
       try {
-        setFeedScrollPhase(e.feedScrollPhase ? JSON.parse(e.feedScrollPhase) : null);
+        const next = e.feedScrollPhase ? JSON.parse(e.feedScrollPhase) : null;
+        // Stabilize object reference: only update state if the phase actually
+        // changed. Prevents unnecessary re-renders of memo'd overlay components
+        // that receive feedScrollPhase as a prop (new JSON.parse object !== old).
+        setFeedScrollPhase(prev => {
+          if (prev?.phase === next?.phase && prev?.fromId === next?.fromId) {
+            return prev;
+          }
+          return next;
+        });
       } catch {
         setFeedScrollPhase(null);
       }
     },
   );
 
-  useOverlayEvent<{ surfaceId: string; current: number; duration: number; buffered: number }>(
-    'onOverlayTimeUpdate', sid,
-    (e) => setTime({ current: e.current, duration: e.duration, buffered: e.buffered }),
-  );
+  // EXPERIMENT: time updates disabled to measure impact on swipe perf
+  // useOverlayEvent<{ surfaceId: string; current: number; duration: number; buffered: number }>(
+  //   'onOverlayTimeUpdate', sid,
+  //   (e) => setTime({ current: e.current, duration: e.duration, buffered: e.buffered }),
+  // );
+
+  // Batched full-state sync — replaces 7 individual events on swipe settle.
+  // All setState calls within one handler = one React render (auto-batched).
+  useOverlayEvent<{
+    surfaceId: string;
+    isActive: boolean;
+    playerState: string;
+    isMuted: boolean;
+    playbackRate: number;
+    captionsEnabled: boolean;
+    activeCue: string | null;
+    feedScrollPhase: string | null;
+  }>('onOverlayFullState', sid, (e) => {
+    setIsActive(e.isActive);
+    setPlayerState(e.playerState as PlayerState);
+    setIsMuted(e.isMuted);
+    setPlaybackRate(e.playbackRate);
+    setCaptionsEnabled(e.captionsEnabled);
+    try {
+      setActiveCue(e.activeCue ? JSON.parse(e.activeCue) : null);
+    } catch {
+      setActiveCue(null);
+    }
+    try {
+      const next = e.feedScrollPhase ? JSON.parse(e.feedScrollPhase) : null;
+      setFeedScrollPhase(prev => {
+        if (prev?.phase === next?.phase && prev?.fromId === next?.fromId) return prev;
+        return next;
+      });
+    } catch {
+      setFeedScrollPhase(null);
+    }
+  });
 
-  if (!item) return null;
+  if (!item) {
+    return null;
+  }
 
   return (
-    <Component
-      item={item}
-      isActive={isActive}
-      playerState={playerState}
-      time={time}
-      isMuted={isMuted}
-      playbackRate={playbackRate}
-      captionsEnabled={captionsEnabled}
-      activeCue={activeCue}
-      feedScrollPhase={feedScrollPhase}
-    />
+    <OverlayErrorBoundary surfaceId={sid} overlayName={props.overlayName}>
+      <Component
+        item={item}
+        isActive={isActive}
+        playerState={playerState}
+        time={time}
+        isMuted={isMuted}
+        playbackRate={playbackRate}
+        captionsEnabled={captionsEnabled}
+        activeCue={activeCue}
+        feedScrollPhase={feedScrollPhase}
+      />
+    </OverlayErrorBoundary>
   );
 }

package/src/ShortKitPlayer.tsx

@@ -17,11 +17,13 @@ import ShortKitPlayerView from './specs/ShortKitPlayerViewNativeComponent';
 export function ShortKitPlayer(props: ShortKitPlayerProps) {
   const { config, contentItem, active, style } = props;
 
+  const clickAction = config?.clickAction ?? 'feed';
+
   const serializedConfig = useMemo(() => {
     const cfg = config ?? {};
     return JSON.stringify({
       cornerRadius: cfg.cornerRadius ?? 12,
-      clickAction: cfg.clickAction ?? 'feed',
+      clickAction: clickAction,
       autoplay: cfg.autoplay ?? true,
       loop: cfg.loop ?? true,
       muteOnStart: cfg.muteOnStart ?? true,
@@ -31,20 +33,40 @@ export function ShortKitPlayer(props: ShortKitPlayerProps) {
           : { type: 'custom' }
         : 'none',
     });
-  }, [config]);
+  }, [config, clickAction]);
 
   const serializedItem = useMemo(() => {
     if (!contentItem) return undefined;
     return JSON.stringify(contentItem);
   }, [contentItem]);
 
+  // When clickAction is "none", the native view should not participate in
+  // Fabric's JS-side hit testing. Without this, Fabric on Android sees the
+  // native component as the touch target and never routes the touch to a
+  // parent Pressable — even though the native view returns false from
+  // dispatchTouchEvent. iOS doesn't need this because UIKit's responder
+  // chain bubbles unhandled touches automatically.
+  //
+  // "box-none" on the container means the container View itself is
+  // transparent to touches (passes through to parent), but children can
+  // still receive touches if needed. "none" on the native view means it
+  // is fully invisible to hit testing.
+  const nativeTouchPassthrough = clickAction === 'none';
+
   return (
-    <View style={[styles.container, style]}>
+    <View
+      style={[styles.container, style]}
+      pointerEvents={nativeTouchPassthrough ? 'box-none' : 'auto'}
+      onStartShouldSetResponder={() => {
+        return false;
+      }}
+    >
       <ShortKitPlayerView
         style={styles.player}
         config={serializedConfig}
         contentItem={serializedItem}
         active={active}
+        pointerEvents={nativeTouchPassthrough ? 'none' : 'auto'}
       />
     </View>
   );

package/src/ShortKitProvider.tsx

@@ -8,6 +8,7 @@ import type {
   ContentItem,
   FeedConfig,
   FeedFilter,
+  FeedInput,
   PlayerTime,
   PlayerState,
   CaptionTrack,
@@ -420,10 +421,11 @@ export function ShortKitProvider({
     }
   }, []);
 
-  const preloadFeedCmd = useCallback(async (config?: Partial<FeedConfig>): Promise<string> => {
+  const preloadFeedCmd = useCallback(async (config?: Partial<FeedConfig>, items?: FeedInput[]): Promise<string> => {
     if (!NativeShortKitModule) return '';
     const configJSON = config ? serializeFeedConfig(config as FeedConfig) : '{}';
-    return NativeShortKitModule.preloadFeed(configJSON);
+    const itemsJSON = items ? JSON.stringify(items) : null;
+    return NativeShortKitModule.preloadFeed(configJSON, itemsJSON);
   }, []);
 
   // -----------------------------------------------------------------------

package/src/index.ts

@@ -7,6 +7,7 @@ export { useShortKit } from './useShortKit';
 export type {
   FeedConfig,
   FeedHeight,
+  ScrollAxis,
   FeedSource,
   OverlayConfig,
   CarouselOverlayConfig,
@@ -42,4 +43,7 @@ export type {
   StoryboardTile,
 } from './types';
 export { ShortKitCommands } from './ShortKitCommands';
+export { default as NativeShortKitModule } from './specs/NativeShortKitModule';
+export { registerOverlayComponent } from './ShortKitOverlaySurface';
+export { registerCarouselOverlayComponent } from './ShortKitCarouselOverlaySurface';
 export type { OverlayProps, CarouselOverlayProps } from './types';

package/src/serialization.ts

@@ -27,6 +27,7 @@ export function serializeFeedConfig(config: FeedConfig): string {
 
   return JSON.stringify({
     feedHeight: JSON.stringify(config.feedHeight ?? { type: 'fullscreen' }),
+    scrollAxis: config.scrollAxis ?? 'vertical',
     overlay,
     carouselOverlay,
     surveyMode: JSON.stringify(config.surveyMode ?? 'none'),

package/src/specs/NativeShortKitModule.ts

@@ -108,6 +108,10 @@ type ContentTappedEvent = Readonly<{
   index: Int32;
 }>;
 
+type FeedReadyEvent = Readonly<{
+  feedId: string;
+}>;
+
 // --- Overlay per-surface event payload types ---
 
 type OverlayActiveEvent = Readonly<{
@@ -152,6 +156,17 @@ type OverlayTimeUpdateEvent = Readonly<{
   buffered: Double;
 }>;
 
+type OverlayFullStateEvent = Readonly<{
+  surfaceId: string;
+  isActive: boolean;
+  playerState: string;
+  isMuted: boolean;
+  playbackRate: Double;
+  captionsEnabled: boolean;
+  activeCue: string;
+  feedScrollPhase: string;
+}>;
+
 export interface Spec extends TurboModule {
   // --- Lifecycle ---
   initialize(
@@ -186,7 +201,7 @@ export interface Spec extends TurboModule {
   appendFeedItems(feedId: string, items: string): void;
   fetchContent(limit: Int32, filterJSON: string | null): Promise<string>;
   applyFilter(feedId: string, filterJSON: string | null): void;
-  preloadFeed(configJSON: string): Promise<string>;
+  preloadFeed(configJSON: string, itemsJSON: string | null): Promise<string>;
 
   // --- Storyboard / seek thumbnails ---
   prefetchStoryboard(playbackId: string): void;
@@ -212,6 +227,7 @@ export interface Spec extends TurboModule {
   readonly onDismiss: EventEmitter<DismissEvent>;
   readonly onRefreshRequested: EventEmitter<RefreshRequestedEvent>;
   readonly onDidFetchContentItems: EventEmitter<DidFetchContentItemsEvent>;
+  readonly onFeedReady: EventEmitter<FeedReadyEvent>;
 
   // --- Overlay per-surface events ---
   readonly onOverlayActiveChanged: EventEmitter<OverlayActiveEvent>;
@@ -222,6 +238,7 @@ export interface Spec extends TurboModule {
   readonly onOverlayActiveCueChanged: EventEmitter<OverlayActiveCueEvent>;
   readonly onOverlayFeedScrollPhaseChanged: EventEmitter<OverlayFeedScrollPhaseEvent>;
   readonly onOverlayTimeUpdate: EventEmitter<OverlayTimeUpdateEvent>;
+  readonly onOverlayFullState: EventEmitter<OverlayFullStateEvent>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>('ShortKitModule');