@shortkitsdk/react-native 0.2.0 → 0.2.2

package/src/ShortKitProvider.tsx

@@ -6,6 +6,8 @@ import type { ShortKitContextValue } from './ShortKitContext';
 import type {
   ShortKitProviderProps,
   ContentItem,
+  ImageCarouselItem,
+  CustomFeedItem,
   PlayerTime,
   PlayerState,
   CaptionTrack,
@@ -13,6 +15,7 @@ import type {
 } from './types';
 import {
   serializeFeedConfigForModule,
+  serializeCustomFeedItems,
   deserializePlayerState,
   deserializeContentItem,
   deserializePlayerTime,
@@ -34,10 +37,16 @@ interface State {
   activeCaptionTrack: CaptionTrack | null;
   activeCue: { text: string; startTime: number; endTime: number } | null;
   prefetchedAheadCount: number;
+  remainingContentCount: number;
   isActive: boolean;
   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 = {
@@ -51,10 +60,16 @@ const initialState: State = {
   activeCaptionTrack: null,
   activeCue: null,
   prefetchedAheadCount: 0,
+  remainingContentCount: 0,
   isActive: false,
   isTransitioning: false,
   lastOverlayTap: 0,
   lastOverlayDoubleTap: null,
+  currentCarouselItem: null,
+  nextCarouselItem: null,
+  isCarouselActive: false,
+  isCarouselTransitioning: false,
+  activeCellType: null,
 };
 
 type Action =
@@ -67,13 +82,20 @@ type Action =
   | { type: 'CAPTION_TRACK'; payload: CaptionTrack | null }
   | { type: 'CUE'; payload: { text: string; startTime: number; endTime: number } | null }
   | { type: 'PREFETCH_COUNT'; payload: number }
+  | { type: 'REMAINING_COUNT'; payload: number }
   | { type: 'OVERLAY_CONFIGURE'; payload: ContentItem }
   | { type: 'OVERLAY_ACTIVATE'; payload: ContentItem }
   | { type: 'OVERLAY_RESET' }
   | { 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) {
@@ -86,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':
@@ -108,10 +133,25 @@ function reducer(state: State, action: Action): State {
       return { ...state, activeCue: action.payload };
     case 'PREFETCH_COUNT':
       return { ...state, prefetchedAheadCount: action.payload };
+    case 'REMAINING_COUNT':
+      return { ...state, remainingContentCount: action.payload };
     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
@@ -133,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;
   }
@@ -145,6 +197,7 @@ function reducer(state: State, action: Action): State {
 export function ShortKitProvider({
   apiKey,
   config,
+  embedId,
   userId,
   clientAppName,
   clientAppVersion,
@@ -168,6 +221,7 @@ export function ShortKitProvider({
     NativeShortKitModule.initialize(
       apiKey,
       serializedConfig,
+      embedId,
       clientAppName,
       clientAppVersion,
       serializedDimensions,
@@ -245,6 +299,7 @@ export function ShortKitProvider({
       NativeShortKitModule.onCurrentItemChanged((event) => {
         const item: ContentItem = {
           id: event.id,
+          playbackId: event.playbackId,
           title: event.title,
           description: event.description,
           duration: event.duration,
@@ -327,6 +382,13 @@ export function ShortKitProvider({
       }),
     );
 
+    // Remaining content count
+    subscriptions.push(
+      NativeShortKitModule.onRemainingContentCountChanged((event) => {
+        dispatch({ type: 'REMAINING_COUNT', payload: event.count });
+      }),
+    );
+
     // Overlay lifecycle events
     subscriptions.push(
       NativeShortKitModule.onOverlayConfigure((event) => {
@@ -380,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.
@@ -450,6 +567,24 @@ export function ShortKitProvider({
     NativeShortKitModule?.clearUserId();
   }, []);
 
+  const setFeedItemsCmd = useCallback((items: CustomFeedItem[]) => {
+    NativeShortKitModule?.setFeedItems(serializeCustomFeedItems(items));
+  }, []);
+
+  const appendFeedItemsCmd = useCallback((items: CustomFeedItem[]) => {
+    NativeShortKitModule?.appendFeedItems(serializeCustomFeedItems(items));
+  }, []);
+
+  const fetchContentCmd = useCallback(async (limit: number = 10): Promise<ContentItem[]> => {
+    if (!NativeShortKitModule) return [];
+    const json = await NativeShortKitModule.fetchContent(limit);
+    try {
+      return JSON.parse(json) as ContentItem[];
+    } catch {
+      return [];
+    }
+  }, []);
+
   // -----------------------------------------------------------------------
   // Context value (memoized to avoid unnecessary re-renders)
   // -----------------------------------------------------------------------
@@ -466,6 +601,7 @@ export function ShortKitProvider({
       activeCaptionTrack: state.activeCaptionTrack,
       activeCue: state.activeCue,
       prefetchedAheadCount: state.prefetchedAheadCount,
+      remainingContentCount: state.remainingContentCount,
       isActive: state.isActive,
       isTransitioning: state.isTransitioning,
       lastOverlayTap: state.lastOverlayTap,
@@ -486,9 +622,22 @@ export function ShortKitProvider({
       setMaxBitrate,
       setUserId: setUserIdCmd,
       clearUserId: clearUserIdCmd,
+      setFeedItems: setFeedItemsCmd,
+      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,
@@ -501,10 +650,16 @@ export function ShortKitProvider({
       state.activeCaptionTrack,
       state.activeCue,
       state.prefetchedAheadCount,
+      state.remainingContentCount,
       state.isActive,
       state.isTransitioning,
       state.lastOverlayTap,
       state.lastOverlayDoubleTap,
+      state.activeCellType,
+      state.currentCarouselItem,
+      state.nextCarouselItem,
+      state.isCarouselActive,
+      state.isCarouselTransitioning,
       play,
       pause,
       seek,
@@ -519,7 +674,11 @@ export function ShortKitProvider({
       setMaxBitrate,
       setUserIdCmd,
       clearUserIdCmd,
+      setFeedItemsCmd,
+      appendFeedItemsCmd,
+      fetchContentCmd,
       config.overlay,
+      config.carouselOverlay,
     ],
   );
 

package/src/ShortKitWidget.tsx

@@ -0,0 +1,63 @@
+import React, { useContext, useMemo } from 'react';
+import { View, StyleSheet } from 'react-native';
+import type { ShortKitWidgetProps } from './types';
+import ShortKitWidgetView from './specs/ShortKitWidgetViewNativeComponent';
+import { ShortKitContext } from './ShortKitContext';
+
+/**
+ * Horizontal carousel widget component. Displays a row of video cards
+ * with automatic rotation. Wraps a native Fabric view.
+ *
+ * Must be rendered inside a `<ShortKitProvider>`.
+ */
+export function ShortKitWidget(props: ShortKitWidgetProps) {
+  const { config, items, style } = props;
+
+  const context = useContext(ShortKitContext);
+  if (!context) {
+    throw new Error('ShortKitWidget must be used within a ShortKitProvider');
+  }
+
+  const serializedConfig = useMemo(() => {
+    const cfg = config ?? {};
+    return JSON.stringify({
+      cardCount: cfg.cardCount ?? 3,
+      cardSpacing: cfg.cardSpacing ?? 8,
+      cornerRadius: cfg.cornerRadius ?? 12,
+      autoplay: cfg.autoplay ?? true,
+      muteOnStart: cfg.muteOnStart ?? true,
+      loop: cfg.loop ?? true,
+      rotationInterval: cfg.rotationInterval ?? 10000,
+      clickAction: cfg.clickAction ?? 'feed',
+      overlay: cfg.overlay
+        ? typeof cfg.overlay === 'string'
+          ? cfg.overlay
+          : { type: 'custom' }
+        : 'none',
+    });
+  }, [config]);
+
+  const serializedItems = useMemo(() => {
+    if (!items || items.length === 0) return undefined;
+    return JSON.stringify(items);
+  }, [items]);
+
+  return (
+    <View style={[styles.container, style]}>
+      <ShortKitWidgetView
+        style={styles.widget}
+        config={serializedConfig}
+        items={serializedItems}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    overflow: 'hidden',
+  },
+  widget: {
+    flex: 1,
+  },
+});

package/src/index.ts

@@ -1,15 +1,26 @@
 export { ShortKitProvider } from './ShortKitProvider';
 export { ShortKitFeed } from './ShortKitFeed';
+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,
+  PlayerClickAction,
+  WidgetConfig,
+
   ContentItem,
+  CarouselImage,
+  ImageCarouselItem,
+  CustomFeedItem,
   JSONValue,
   CaptionTrack,
   PlayerTime,
@@ -22,5 +33,8 @@ export type {
   ShortKitError,
   ShortKitProviderProps,
   ShortKitFeedProps,
+  ShortKitPlayerProps,
+  ShortKitWidgetProps,
   ShortKitPlayerState,
 } from './types';
+export type { ShortKitCarouselState } from './useShortKitCarousel';

package/src/serialization.ts

@@ -1,6 +1,7 @@
 import type {
   FeedConfig,
   ContentItem,
+  CustomFeedItem,
   PlayerState,
   PlayerTime,
 } from './types';
@@ -12,9 +13,10 @@ import type {
 export interface SerializedFeedConfig {
   feedHeight: string;
   overlay: string;
-  carouselMode: string;
+  carouselOverlay: string;
   surveyMode: string;
   muteOnStart: boolean;
+  feedSource: string;
 }
 
 /**
@@ -35,9 +37,14 @@ 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',
   };
 }
 
@@ -93,3 +100,10 @@ export function deserializePlayerTime(event: {
     buffered: event.buffered,
   };
 }
+
+/**
+ * Serialize CustomFeedItem[] to a JSON string for the bridge.
+ */
+export function serializeCustomFeedItems(items: CustomFeedItem[]): string {
+  return JSON.stringify(items);
+}

package/src/specs/NativeShortKitModule.ts

@@ -11,6 +11,7 @@ type PlayerStateEvent = Readonly<{
 
 type CurrentItemEvent = Readonly<{
   id: string;
+  playbackId?: string;
   title: string;
   description?: string;
   duration: Double;
@@ -77,6 +78,10 @@ type PrefetchedAheadCountEvent = Readonly<{
   count: Int32;
 }>;
 
+type RemainingContentCountEvent = Readonly<{
+  count: Int32;
+}>;
+
 type ErrorEvent = Readonly<{
   code: string;
   message: string;
@@ -112,6 +117,25 @@ type OverlayRestoreEvent = Readonly<{
   item: string; // JSON-serialized ContentItem
 }>;
 
+type ContentTappedEvent = Readonly<{
+  contentId: string;
+  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<{
@@ -124,6 +148,7 @@ export interface Spec extends TurboModule {
   initialize(
     apiKey: string,
     config: string, // JSON-serialized FeedConfig
+    embedId?: string,
     clientAppName?: string,
     clientAppVersion?: string,
     customDimensions?: string, // JSON-serialized Record<string, string>
@@ -148,6 +173,11 @@ export interface Spec extends TurboModule {
   sendContentSignal(signal: string): void;
   setMaxBitrate(bitrate: Double): void;
 
+  // --- Custom feed ---
+  setFeedItems(items: string): void;
+  appendFeedItems(items: string): void;
+  fetchContent(limit: Int32): Promise<string>;
+
   // --- Event emitters ---
   readonly onPlayerStateChanged: EventEmitter<PlayerStateEvent>;
   readonly onCurrentItemChanged: EventEmitter<CurrentItemEvent>;
@@ -161,6 +191,7 @@ export interface Spec extends TurboModule {
   readonly onFeedTransition: EventEmitter<FeedTransitionEvent>;
   readonly onFormatChange: EventEmitter<FormatChangeEvent>;
   readonly onPrefetchedAheadCountChanged: EventEmitter<PrefetchedAheadCountEvent>;
+  readonly onRemainingContentCountChanged: EventEmitter<RemainingContentCountEvent>;
   readonly onError: EventEmitter<ErrorEvent>;
   readonly onShareTapped: EventEmitter<ShareTappedEvent>;
   readonly onSurveyResponse: EventEmitter<SurveyResponseEvent>;
@@ -171,6 +202,12 @@ export interface Spec extends TurboModule {
   readonly onOverlayRestore: EventEmitter<OverlayRestoreEvent>;
   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/specs/ShortKitPlayerViewNativeComponent.ts

@@ -0,0 +1,13 @@
+import type { HostComponent, ViewProps } from 'react-native';
+import { codegenNativeComponent } from 'react-native';
+
+export interface NativeProps extends ViewProps {
+  config: string;
+  contentItem?: string;
+  active?: boolean;
+}
+
+export default codegenNativeComponent<NativeProps>(
+  'ShortKitPlayerView',
+  {},
+) as HostComponent<NativeProps>;

package/src/specs/ShortKitWidgetViewNativeComponent.ts

@@ -0,0 +1,12 @@
+import type { HostComponent, ViewProps } from 'react-native';
+import { codegenNativeComponent } from 'react-native';
+
+export interface NativeProps extends ViewProps {
+  config: string;
+  items?: string;
+}
+
+export default codegenNativeComponent<NativeProps>(
+  'ShortKitWidgetView',
+  {},
+) as HostComponent<NativeProps>;