@shortkitsdk/react-native 0.2.1 → 0.2.3

package/ios/ShortKitSDK.xcframework/ios-arm64-simulator/ShortKitSDK.framework/Modules/module.modulemap

@@ -0,0 +1,4 @@
+framework module ShortKitSDK {
+    header "ShortKitSDK-Swift.h"
+    export *
+}

package/ios/ShortKitWidgetNativeView.swift

@@ -1,5 +1,5 @@
 import UIKit
-import ShortKit
+import ShortKitSDK
 
 /// Fabric native view wrapping `ShortKitWidgetViewController` for use as
 /// a horizontal video carousel in React Native.

package/package.json

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

package/src/CarouselOverlayManager.tsx

@@ -0,0 +1,71 @@
+import React, { useContext, useMemo } from 'react';
+import { View, StyleSheet } from 'react-native';
+import type { CarouselOverlayConfig } from './types';
+import { ShortKitContext } from './ShortKitContext';
+import type { ShortKitContextValue } from './ShortKitContext';
+
+interface CarouselOverlayManagerProps {
+  carouselOverlay: CarouselOverlayConfig;
+}
+
+/**
+ * Internal component that renders TWO instances of the developer's custom
+ * carousel overlay component — one for the current cell and one for the next.
+ *
+ * Works identically to `OverlayManager` but for image carousel cells.
+ * The native side finds these views by their `nativeID` and applies
+ * scroll-tracking transforms so each overlay moves with its respective
+ * carousel cell during swipe transitions.
+ */
+export function CarouselOverlayManager({ carouselOverlay }: CarouselOverlayManagerProps) {
+  if (
+    carouselOverlay === 'none' ||
+    typeof carouselOverlay === 'string' ||
+    carouselOverlay.type !== 'custom' ||
+    !('component' in carouselOverlay)
+  ) {
+    return null;
+  }
+
+  const CarouselComponent = carouselOverlay.component;
+
+  return (
+    <>
+      <View style={StyleSheet.absoluteFill} nativeID="carousel-overlay-current" pointerEvents="box-none">
+        <CarouselComponent />
+      </View>
+      <View style={StyleSheet.absoluteFill} nativeID="carousel-overlay-next" pointerEvents="box-none">
+        <NextCarouselOverlayProvider>
+          <CarouselComponent />
+        </NextCarouselOverlayProvider>
+      </View>
+    </>
+  );
+}
+
+/**
+ * Wraps children with a modified ShortKitContext where `currentCarouselItem`
+ * is set to the provider's `nextCarouselItem`.
+ */
+function NextCarouselOverlayProvider({ children }: { children: React.ReactNode }) {
+  const context = useContext(ShortKitContext);
+
+  const nextValue: ShortKitContextValue | null = useMemo(() => {
+    if (!context) return null;
+
+    return {
+      ...context,
+      currentCarouselItem: context.nextCarouselItem,
+      isCarouselActive: context.nextCarouselItem != null,
+      isCarouselTransitioning: false,
+    };
+  }, [context]);
+
+  if (!nextValue) return <>{children}</>;
+
+  return (
+    <ShortKitContext.Provider value={nextValue}>
+      {children}
+    </ShortKitContext.Provider>
+  );
+}

package/src/ShortKitContext.ts

@@ -1,12 +1,14 @@
 import { createContext } from 'react';
 import type {
   ContentItem,
+  ImageCarouselItem,
   CustomFeedItem,
   PlayerTime,
   PlayerState,
   CaptionTrack,
   ContentSignal,
   OverlayConfig,
+  CarouselOverlayConfig,
 } from './types';
 
 export interface ShortKitContextValue {
@@ -48,9 +50,20 @@ export interface ShortKitContextValue {
   appendFeedItems: (items: CustomFeedItem[]) => void;
   fetchContent: (limit?: number) => Promise<ContentItem[]>;
 
+  // Carousel overlay state
+  currentCarouselItem: ImageCarouselItem | null;
+  nextCarouselItem: ImageCarouselItem | null;
+  isCarouselActive: boolean;
+  isCarouselTransitioning: boolean;
+
+  // Active cell type — used by overlay managers to show/hide
+  activeCellType: 'video' | 'carousel' | null;
+
   // Internal — used by ShortKitFeed to render custom overlays
   /** @internal */
   _overlayConfig: OverlayConfig;
+  /** @internal */
+  _carouselOverlayConfig: CarouselOverlayConfig;
 }
 
 export const ShortKitContext = createContext<ShortKitContextValue | null>(null);

package/src/ShortKitFeed.tsx

@@ -4,6 +4,7 @@ import type { ShortKitFeedProps } from './types';
 import ShortKitFeedView from './specs/ShortKitFeedViewNativeComponent';
 import NativeShortKitModule from './specs/NativeShortKitModule';
 import { OverlayManager } from './OverlayManager';
+import { CarouselOverlayManager } from './CarouselOverlayManager';
 import { ShortKitContext } from './ShortKitContext';
 import { deserializeContentItem } from './serialization';
 
@@ -38,6 +39,7 @@ export function ShortKitFeed(props: ShortKitFeedProps) {
   }
 
   const overlayConfig = context._overlayConfig;
+  const carouselOverlayConfig = context._carouselOverlayConfig;
 
   // ---------------------------------------------------------------------------
   // Subscribe to feed-level events and forward to callback props
@@ -143,6 +145,7 @@ export function ShortKitFeed(props: ShortKitFeedProps) {
         config="{}"
       />
       <OverlayManager overlay={overlayConfig} />
+      <CarouselOverlayManager carouselOverlay={carouselOverlayConfig} />
     </View>
   );
 }

package/src/ShortKitProvider.tsx

@@ -6,6 +6,7 @@ import type { ShortKitContextValue } from './ShortKitContext';
 import type {
   ShortKitProviderProps,
   ContentItem,
+  ImageCarouselItem,
   CustomFeedItem,
   PlayerTime,
   PlayerState,
@@ -41,6 +42,11 @@ interface State {
   isTransitioning: boolean;
   lastOverlayTap: number;
   lastOverlayDoubleTap: { x: number; y: number; id: number } | null;
+  currentCarouselItem: ImageCarouselItem | null;
+  nextCarouselItem: ImageCarouselItem | null;
+  isCarouselActive: boolean;
+  isCarouselTransitioning: boolean;
+  activeCellType: 'video' | 'carousel' | null;
 }
 
 const initialState: State = {
@@ -59,6 +65,11 @@ const initialState: State = {
   isTransitioning: false,
   lastOverlayTap: 0,
   lastOverlayDoubleTap: null,
+  currentCarouselItem: null,
+  nextCarouselItem: null,
+  isCarouselActive: false,
+  isCarouselTransitioning: false,
+  activeCellType: null,
 };
 
 type Action =
@@ -78,7 +89,13 @@ type Action =
   | { type: 'OVERLAY_FADE_OUT' }
   | { type: 'OVERLAY_RESTORE' }
   | { type: 'OVERLAY_TAP' }
-  | { type: 'OVERLAY_DOUBLE_TAP'; payload: { x: number; y: number } };
+  | { type: 'OVERLAY_DOUBLE_TAP'; payload: { x: number; y: number } }
+  | { type: 'ACTIVE_CELL_TYPE'; payload: 'video' | 'carousel' }
+  | { type: 'CAROUSEL_OVERLAY_CONFIGURE'; payload: ImageCarouselItem }
+  | { type: 'CAROUSEL_OVERLAY_ACTIVATE'; payload: ImageCarouselItem }
+  | { type: 'CAROUSEL_OVERLAY_RESET' }
+  | { type: 'CAROUSEL_OVERLAY_FADE_OUT' }
+  | { type: 'CAROUSEL_OVERLAY_RESTORE' };
 
 function reducer(state: State, action: Action): State {
   switch (action.type) {
@@ -91,10 +108,13 @@ function reducer(state: State, action: Action): State {
         action.payload === 'paused' ||
         action.payload === 'buffering' ||
         action.payload === 'seeking';
+      const becameActive = !state.isActive && isPlaybackActive;
       return {
         ...state,
         playerState: action.payload,
         isActive: state.isActive || isPlaybackActive,
+        // First playback means a video cell is active (initial load)
+        activeCellType: becameActive ? 'video' : state.activeCellType,
       };
     }
     case 'CURRENT_ITEM':
@@ -118,7 +138,20 @@ function reducer(state: State, action: Action): State {
     case 'OVERLAY_CONFIGURE':
       return { ...state, nextItem: action.payload };
     case 'OVERLAY_ACTIVATE':
-      return { ...state, currentItem: action.payload, isActive: true };
+      // Reset time/cue/transition state to prevent stale playback data from
+      // the previous cell flashing on the new cell's overlay.
+      // Note: nextItem is NOT cleared here — the native-side deferred-configure
+      // (ShortKitOverlayBridge) already prevents handleSwipe from polluting it.
+      // Clearing it would cause overlay-next to unmount its content ~80ms before
+      // the page settle swaps overlays, creating a visible dim-layer gap.
+      return {
+        ...state,
+        currentItem: action.payload,
+        isActive: true,
+        time: { current: 0, duration: action.payload.duration, buffered: 0 },
+        activeCue: null,
+        isTransitioning: false,
+      };
     case 'OVERLAY_RESET':
       // Don't set isActive = false — the overlay stays mounted during
       // transitions. In the native SDK each cell has its own overlay
@@ -140,6 +173,18 @@ function reducer(state: State, action: Action): State {
           id: (state.lastOverlayDoubleTap?.id ?? 0) + 1,
         },
       };
+    case 'ACTIVE_CELL_TYPE':
+      return { ...state, activeCellType: action.payload };
+    case 'CAROUSEL_OVERLAY_CONFIGURE':
+      return { ...state, nextCarouselItem: action.payload };
+    case 'CAROUSEL_OVERLAY_ACTIVATE':
+      return { ...state, currentCarouselItem: action.payload, isCarouselActive: true };
+    case 'CAROUSEL_OVERLAY_RESET':
+      return { ...state, isCarouselTransitioning: false };
+    case 'CAROUSEL_OVERLAY_FADE_OUT':
+      return { ...state, isCarouselTransitioning: true };
+    case 'CAROUSEL_OVERLAY_RESTORE':
+      return { ...state, isCarouselTransitioning: false };
     default:
       return state;
   }
@@ -397,6 +442,61 @@ export function ShortKitProvider({
       }),
     );
 
+    // Feed transition — track active cell type
+    subscriptions.push(
+      NativeShortKitModule.onFeedTransition((event) => {
+        if (event.phase === 'ended') {
+          // toItem is null when the destination cell is non-video (carousel, survey, ad)
+          const isVideo = event.toItem != null;
+          dispatch({
+            type: 'ACTIVE_CELL_TYPE',
+            payload: isVideo ? 'video' : 'carousel',
+          });
+        }
+      }),
+    );
+
+    // Carousel overlay lifecycle events
+    subscriptions.push(
+      NativeShortKitModule.onCarouselOverlayConfigure((event) => {
+        try {
+          const item = JSON.parse(event.item) as ImageCarouselItem;
+          dispatch({ type: 'CAROUSEL_OVERLAY_CONFIGURE', payload: item });
+        } catch {
+          // Ignore malformed JSON
+        }
+      }),
+    );
+
+    subscriptions.push(
+      NativeShortKitModule.onCarouselOverlayActivate((event) => {
+        try {
+          const item = JSON.parse(event.item) as ImageCarouselItem;
+          dispatch({ type: 'CAROUSEL_OVERLAY_ACTIVATE', payload: item });
+        } catch {
+          // Ignore malformed JSON
+        }
+      }),
+    );
+
+    subscriptions.push(
+      NativeShortKitModule.onCarouselOverlayReset((_event) => {
+        dispatch({ type: 'CAROUSEL_OVERLAY_RESET' });
+      }),
+    );
+
+    subscriptions.push(
+      NativeShortKitModule.onCarouselOverlayFadeOut((_event) => {
+        dispatch({ type: 'CAROUSEL_OVERLAY_FADE_OUT' });
+      }),
+    );
+
+    subscriptions.push(
+      NativeShortKitModule.onCarouselOverlayRestore((_event) => {
+        dispatch({ type: 'CAROUSEL_OVERLAY_RESTORE' });
+      }),
+    );
+
     // Note: Feed-level callback events (onDidLoop, onFeedTransition,
     // onShareTapped, etc.) are subscribed by the ShortKitFeed component
     // (Task 11), not here. The provider only manages state-driving events.
@@ -526,8 +626,18 @@ export function ShortKitProvider({
       appendFeedItems: appendFeedItemsCmd,
       fetchContent: fetchContentCmd,
 
+      // Active cell type
+      activeCellType: state.activeCellType,
+
+      // Carousel overlay state
+      currentCarouselItem: state.currentCarouselItem,
+      nextCarouselItem: state.nextCarouselItem,
+      isCarouselActive: state.isCarouselActive,
+      isCarouselTransitioning: state.isCarouselTransitioning,
+
       // Internal — consumed by ShortKitFeed to pass to OverlayManager
       _overlayConfig: config.overlay ?? 'none',
+      _carouselOverlayConfig: config.carouselOverlay ?? 'none',
     }),
     [
       state.playerState,
@@ -545,6 +655,11 @@ export function ShortKitProvider({
       state.isTransitioning,
       state.lastOverlayTap,
       state.lastOverlayDoubleTap,
+      state.activeCellType,
+      state.currentCarouselItem,
+      state.nextCarouselItem,
+      state.isCarouselActive,
+      state.isCarouselTransitioning,
       play,
       pause,
       seek,
@@ -563,6 +678,7 @@ export function ShortKitProvider({
       appendFeedItemsCmd,
       fetchContentCmd,
       config.overlay,
+      config.carouselOverlay,
     ],
   );
 

package/src/index.ts

@@ -4,12 +4,13 @@ export { ShortKitPlayer } from './ShortKitPlayer';
 export { ShortKitWidget } from './ShortKitWidget';
 export { useShortKitPlayer } from './useShortKitPlayer';
 export { useShortKit } from './useShortKit';
+export { useShortKitCarousel } from './useShortKitCarousel';
 export type {
   FeedConfig,
   FeedHeight,
   FeedSource,
   OverlayConfig,
-  CarouselMode,
+  CarouselOverlayConfig,
   SurveyMode,
 
   PlayerConfig,
@@ -36,3 +37,4 @@ export type {
   ShortKitWidgetProps,
   ShortKitPlayerState,
 } from './types';
+export type { ShortKitCarouselState } from './useShortKitCarousel';

package/src/serialization.ts

@@ -13,7 +13,7 @@ import type {
 export interface SerializedFeedConfig {
   feedHeight: string;
   overlay: string;
-  carouselMode: string;
+  carouselOverlay: string;
   surveyMode: string;
   muteOnStart: boolean;
   feedSource: string;
@@ -37,7 +37,11 @@ export function serializeFeedConfig(config: FeedConfig): SerializedFeedConfig {
   return {
     feedHeight: JSON.stringify(config.feedHeight ?? { type: 'fullscreen' }),
     overlay,
-    carouselMode: JSON.stringify(config.carouselMode ?? 'none'),
+    carouselOverlay: (() => {
+      const raw = config.carouselOverlay ?? 'none';
+      if (typeof raw === 'string') return JSON.stringify(raw);
+      return JSON.stringify({ type: 'custom' });
+    })(),
     surveyMode: JSON.stringify(config.surveyMode ?? 'none'),
     muteOnStart: config.muteOnStart ?? true,
     feedSource: config.feedSource ?? 'algorithmic',

package/src/specs/NativeShortKitModule.ts

@@ -122,6 +122,20 @@ type ContentTappedEvent = Readonly<{
   index: Int32;
 }>;
 
+type CarouselOverlayConfigureEvent = Readonly<{
+  item: string; // JSON-serialized ImageCarouselItem
+}>;
+
+type CarouselOverlayActivateEvent = Readonly<{
+  item: string; // JSON-serialized ImageCarouselItem
+}>;
+
+type CarouselOverlayResetEvent = Readonly<{}>;
+
+type CarouselOverlayFadeOutEvent = Readonly<{}>;
+
+type CarouselOverlayRestoreEvent = Readonly<{}>;
+
 type OverlayTapEvent = Readonly<{}>;
 
 type OverlayDoubleTapEvent = Readonly<{
@@ -189,6 +203,11 @@ export interface Spec extends TurboModule {
   readonly onOverlayTap: EventEmitter<OverlayTapEvent>;
   readonly onOverlayDoubleTap: EventEmitter<OverlayDoubleTapEvent>;
   readonly onContentTapped: EventEmitter<ContentTappedEvent>;
+  readonly onCarouselOverlayConfigure: EventEmitter<CarouselOverlayConfigureEvent>;
+  readonly onCarouselOverlayActivate: EventEmitter<CarouselOverlayActivateEvent>;
+  readonly onCarouselOverlayReset: EventEmitter<CarouselOverlayResetEvent>;
+  readonly onCarouselOverlayFadeOut: EventEmitter<CarouselOverlayFadeOutEvent>;
+  readonly onCarouselOverlayRestore: EventEmitter<CarouselOverlayRestoreEvent>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>('ShortKitModule');

package/src/types.ts

@@ -7,7 +7,7 @@ export type FeedSource = 'algorithmic' | 'custom';
 export interface FeedConfig {
   feedHeight?: FeedHeight;
   overlay?: OverlayConfig;
-  carouselMode?: CarouselMode;
+  carouselOverlay?: CarouselOverlayConfig;
   surveyMode?: SurveyMode;
   muteOnStart?: boolean;
   feedSource?: FeedSource;
@@ -21,9 +21,9 @@ export type OverlayConfig =
   | 'none'
   | { type: 'custom'; component: React.ComponentType };
 
-export type CarouselMode =
+export type CarouselOverlayConfig =
   | 'none'
-  | { type: 'template'; name: 'default' };
+  | { type: 'custom'; component: React.ComponentType };
 
 export type SurveyMode =
   | 'none'
@@ -212,6 +212,7 @@ export interface ShortKitPlayerState {
   playerState: PlayerState;
   currentItem: ContentItem | null;
   nextItem: ContentItem | null;
+  activeCellType: 'video' | 'carousel' | null;
   time: PlayerTime;
   isMuted: boolean;
   playbackRate: number;

package/src/useShortKitCarousel.ts

@@ -0,0 +1,29 @@
+import { useContext } from 'react';
+import { ShortKitContext } from './ShortKitContext';
+import type { ImageCarouselItem } from './types';
+
+export interface ShortKitCarouselState {
+  currentCarouselItem: ImageCarouselItem | null;
+  isCarouselActive: boolean;
+  isCarouselTransitioning: boolean;
+}
+
+/**
+ * Hook to access carousel overlay state from the nearest ShortKitProvider.
+ *
+ * Use this inside a custom carousel overlay component to get the current
+ * `ImageCarouselItem` data (images, title, description, etc.).
+ *
+ * Must be used within a `<ShortKitProvider>`.
+ */
+export function useShortKitCarousel(): ShortKitCarouselState {
+  const context = useContext(ShortKitContext);
+  if (!context) {
+    throw new Error('useShortKitCarousel must be used within a ShortKitProvider');
+  }
+  return {
+    currentCarouselItem: context.currentCarouselItem,
+    isCarouselActive: context.isCarouselActive,
+    isCarouselTransitioning: context.isCarouselTransitioning,
+  };
+}

package/src/useShortKitPlayer.ts

@@ -16,12 +16,20 @@ export function useShortKitPlayer(): ShortKitPlayerState {
     throw new Error('useShortKitPlayer must be used within a ShortKitProvider');
   }
 
-  // Return only player-related state and commands (exclude SDK operations
-  // and internal fields)
+  // Return only player-related state and commands (exclude SDK operations,
+  // carousel state, and internal fields)
   const {
     setUserId: _setUserId,
     clearUserId: _clearUserId,
+    setFeedItems: _setFeedItems,
+    appendFeedItems: _appendFeedItems,
+    fetchContent: _fetchContent,
+    currentCarouselItem: _currentCarouselItem,
+    nextCarouselItem: _nextCarouselItem,
+    isCarouselActive: _isCarouselActive,
+    isCarouselTransitioning: _isCarouselTransitioning,
     _overlayConfig: _overlay,
+    _carouselOverlayConfig: _carouselOverlay,
     ...playerState
   } = context;