@shortkitsdk/react-native 0.2.24 → 0.2.26

package/src/specs/NativeShortKitModule.ts

@@ -96,6 +96,12 @@ type RefreshStateChangedEvent = Readonly<{
   progress: Double;
 }>;
 
+type RefreshStateChangedPerFeedEvent = Readonly<{
+  feedId: string;
+  status: string;
+  progress: Double;
+}>;
+
 type DidFetchContentItemsEvent = Readonly<{
   items: string; // JSON-serialized ContentItem[]
 }>;
@@ -109,6 +115,13 @@ type FeedReadyEvent = Readonly<{
   feedId: string;
 }>;
 
+type VideoCarouselCellTapEvent = Readonly<{
+  feedId: string;
+  id: string;
+  index: Int32;
+  pageIndex: Int32;
+}>;
+
 type DownloadStartedEvent = Readonly<{
   itemId: string;
 }>;
@@ -177,12 +190,38 @@ type CarouselActiveImageEvent = Readonly<{
   activeImageIndex: Int32;
 }>;
 
+type CarouselItemChangedEvent = Readonly<{
+  surfaceId: string;
+  item: string;              // JSON-serialized ImageCarouselItem (with local file:// URLs where cached)
+  isActive: boolean;
+  activeImageIndex: Int32;
+}>;
+
 type VideoCarouselActiveVideoEvent = Readonly<{
   surfaceId: string;
   activeVideo: string;
   activeVideoIndex: Int32;
 }>;
 
+type VideoCarouselItemChangedEvent = Readonly<{
+  surfaceId: string;
+  carouselItem: string;         // JSON-serialized VideoCarouselItem
+  activeVideo: string | null;   // JSON-serialized ContentItem; null when item has no videos
+  activeVideoIndex: Int32;
+  isActive: boolean;
+  playerState: string;
+  isMuted: boolean;
+}>;
+
+type CarouselActiveVideoCompletedEvent = Readonly<{
+  surfaceId: string;
+  contentItem: string;          // JSON-serialized ContentItem
+  indexInCarousel: Int32;
+  carouselItem: string;          // JSON-serialized VideoCarouselItem
+  wasLast: boolean;
+  willAutoAdvance: boolean;
+}>;
+
 type OverlayFullStateEvent = Readonly<{
   surfaceId: string;
   isActive: boolean;
@@ -190,8 +229,20 @@ type OverlayFullStateEvent = Readonly<{
   isMuted: boolean;
   playbackRate: Double;
   captionsEnabled: boolean;
-  activeCue: string;
-  feedScrollPhase: string;
+  activeCue: string | null;
+  feedScrollPhase: string | null;
+}>;
+
+type OverlayItemChangedEvent = Readonly<{
+  surfaceId: string;
+  item: string; // JSON-serialized ContentItem
+  isActive: boolean;
+  playerState: string;
+  isMuted: boolean;
+  playbackRate: Double;
+  captionsEnabled: boolean;
+  activeCue: string | null;
+  feedScrollPhase: string | null;
 }>;
 
 export interface Spec extends TurboModule {
@@ -217,6 +268,9 @@ export interface Spec extends TurboModule {
   seekAndPlay(seconds: Double): void;
   skipToNext(): void;
   skipToPrevious(): void;
+  carouselNext(): boolean;
+  carouselPrevious(): boolean;
+  carouselSetActiveIndex(index: Int32): boolean;
   setMuted(muted: boolean): void;
   setPlaybackRate(rate: Double): void;
   setCaptionsEnabled(enabled: boolean): void;
@@ -225,7 +279,8 @@ export interface Spec extends TurboModule {
   setMaxBitrate(bitrate: Double): void;
 
   // --- Custom feed ---
-  setFeedItems(feedId: string, items: string): void;
+  setFeedItems(feedId: string, items: string, startAtId: string | null): void;
+  scrollFeedToItem(feedId: string, id: string, animated: boolean): void;
   appendFeedItems(feedId: string, items: string): void;
   fetchContent(limit: Int32, filterJSON: string | null): Promise<string>;
   applyFilter(feedId: string, filterJSON: string | null): void;
@@ -239,6 +294,10 @@ export interface Spec extends TurboModule {
   downloadVideo(itemId: string, mode: string): Promise<string>;
   cancelDownload(): void;
 
+  // --- Carousel accessors ---
+  getCarouselActiveIndex(): Int32;
+  getCarouselVideoCount(): Int32;
+
   // --- Event emitters ---
   readonly onPlayerStateChanged: EventEmitter<PlayerStateEvent>;
   readonly onCurrentItemChanged: EventEmitter<CurrentItemEvent>;
@@ -257,8 +316,10 @@ export interface Spec extends TurboModule {
   readonly onContentTapped: EventEmitter<ContentTappedEvent>;
   readonly onDismiss: EventEmitter<DismissEvent>;
   readonly onRefreshStateChanged: EventEmitter<RefreshStateChangedEvent>;
+  readonly onRefreshStateChangedPerFeed: EventEmitter<RefreshStateChangedPerFeedEvent>;
   readonly onDidFetchContentItems: EventEmitter<DidFetchContentItemsEvent>;
   readonly onFeedReady: EventEmitter<FeedReadyEvent>;
+  readonly onVideoCarouselCellTap: EventEmitter<VideoCarouselCellTapEvent>;
 
   // --- Overlay per-surface events ---
   readonly onOverlayActiveChanged: EventEmitter<OverlayActiveEvent>;
@@ -270,8 +331,12 @@ export interface Spec extends TurboModule {
   readonly onOverlayFeedScrollPhaseChanged: EventEmitter<OverlayFeedScrollPhaseEvent>;
   readonly onOverlayTimeUpdate: EventEmitter<OverlayTimeUpdateEvent>;
   readonly onOverlayFullState: EventEmitter<OverlayFullStateEvent>;
+  readonly onOverlayItemChanged: EventEmitter<OverlayItemChangedEvent>;
   readonly onCarouselActiveImageChanged: EventEmitter<CarouselActiveImageEvent>;
+  readonly onCarouselItemChanged: EventEmitter<CarouselItemChangedEvent>;
   readonly onVideoCarouselActiveVideoChanged: EventEmitter<VideoCarouselActiveVideoEvent>;
+  readonly onVideoCarouselItemChanged: EventEmitter<VideoCarouselItemChangedEvent>;
+  readonly onCarouselActiveVideoCompleted: EventEmitter<CarouselActiveVideoCompletedEvent>;
 
   // --- Download events ---
   readonly onDownloadStarted: EventEmitter<DownloadStartedEvent>;

package/src/specs/ShortKitFeedViewNativeComponent.ts

@@ -6,6 +6,17 @@ export interface NativeProps extends ViewProps {
   feedId?: string;
   startAtItemId?: string;
   preloadId?: string;
+  /**
+   * URL of a thumbnail already rendered/cached on the host side (e.g. the
+   * grid tile the user tapped to open this feed). When expo-image or FastImage
+   * is used on iOS, SDK fetches the decoded UIImage from SDWebImage's memory
+   * cache and paints it onto the first cell with zero network and zero
+   * latency. Falls back to network fetch for non-SDWebImage clients.
+   */
+  seedThumbnailUrl?: string;
+  /** JSON-serialized FeedInput[] for initial custom-feed items at mount time. */
+  feedItemsJSON?: string;
+  active?: boolean;
 }
 
 export default codegenNativeComponent<NativeProps>(

package/src/types.ts

@@ -113,6 +113,8 @@ export interface VideoCarouselItem {
   articleUrl?: string;
 }
 
+export type ContentOrigin = 'ios_upload' | 'other';
+
 /**
  * Per-slide input for a VideoCarouselInput. Mirrors the `{ type: 'video' }`
  * FeedInput variant — host apps pass a playback ID and the SDK constructs
@@ -120,6 +122,7 @@ export interface VideoCarouselItem {
  */
 export interface VideoCarouselVideoInput {
   playbackId: string;
+  origin?: ContentOrigin;
   fallbackUrl?: string;
 }
 
@@ -142,7 +145,7 @@ export interface VideoCarouselInput {
 }
 
 export type FeedInput =
-  | { type: 'video'; playbackId: string; fallbackUrl?: string }
+  | { type: 'video'; playbackId: string; origin?: ContentOrigin; fallbackUrl?: string }
   | { type: 'imageCarousel'; item: ImageCarouselItem }
   | { type: 'videoCarousel'; item: VideoCarouselInput };
 
@@ -300,6 +303,45 @@ export interface ShortKitFeedProps {
   style?: ViewStyle;
   /** Item ID to scroll to on initial load. */
   startAtItemId?: string;
+  /**
+   * URL of the thumbnail already displayed in your UI (e.g. the grid tile
+   * the user just tapped). If your app uses expo-image or FastImage, the SDK
+   * will extract the already-decoded UIImage from SDWebImage's memory cache
+   * and paint it on the first feed cell with zero network overhead — closing
+   * the black-frame gap before video playback begins.
+   *
+   * Falls back silently (no extra network beyond the existing fallback) for
+   * apps on React Native's core <Image> or other image libraries.
+   */
+  seedThumbnailUrl?: string;
+  /**
+   * Initial feed items for custom feed mode (`feedSource: 'custom'`).
+   *
+   * Items are delivered to the native view as construction-time props so the
+   * SDK renders the first cell on the very first run-loop tick — no
+   * ref-attach race, no async bridge hop, no loading-state flash.
+   *
+   * Use for supplying known items at mount (e.g. a cached last-watched
+   * video). For post-mount updates (pagination, refresh), use the imperative
+   * `setFeedItems()` / `appendFeedItems()` methods on the ref.
+   *
+   * When both `feedItems` and `preloadId` are set, `preloadId` takes
+   * precedence (it carries prefetched HLS manifests / segment 0).
+   */
+  feedItems?: FeedInput[];
+  /**
+   * Whether the feed is the active/focused surface. When `false`, the SDK
+   * suspends playback and yields players so an adjacent feed (e.g. another
+   * tab) can use them without cross-surface contamination.
+   *
+   * Pass `useIsFocused()` from React Navigation. When omitted, the SDK
+   * infers suspension from UIKit's `willMove(toWindow:)` lifecycle —
+   * which works for push/pop navigation but NOT for tab/pager navigation
+   * where the view stays in the window hierarchy.
+   *
+   * @default true
+   */
+  active?: boolean;
   onLoop?: (event: LoopEvent) => void;
   onFeedTransition?: (event: FeedTransitionEvent) => void;
   onFormatChange?: (event: FormatChangeEvent) => void;
@@ -316,6 +358,26 @@ export interface ShortKitFeedProps {
   /** Called once when this feed has loaded content and assigned a player
    *  to the first cell. Use to dismiss a splash screen or loading overlay. */
   onFeedReady?: () => void;
+  /** Called when the active video in a video carousel completes playback. */
+  onCarouselActiveVideoCompleted?: (event: {
+    surfaceId: string;
+    contentItem: ContentItem;
+    indexInCarousel: number;
+    carouselItem: VideoCarouselItem;
+    wasLast: boolean;
+    willAutoAdvance: boolean;
+  }) => void;
+  /**
+   * Fires when the user taps a video-carousel cell without triggering the
+   * cell's horizontal pan. Use with `useShortKit().setMuted(...)` to
+   * implement tap-to-mute on video-carousel overlays. Single-video and
+   * image-carousel cells don't need this — JS `<Pressable>` works for them.
+   */
+  onVideoCarouselCellTap?: (event: {
+    id: string;
+    index: number;
+    pageIndex: number;
+  }) => void;
 }
 
 /**
@@ -323,8 +385,25 @@ export interface ShortKitFeedProps {
  * Obtained via `ref` on `<ShortKitFeed>`.
  */
 export interface ShortKitFeedHandle {
-  /** Replace all items in this feed instance. */
-  setFeedItems: (items: FeedInput[]) => void;
+  /**
+   * Replace the feed's items atomically.
+   *
+   * @param items   The new feed contents.
+   * @param options Optional. `startAt` specifies the item id to focus after
+   *                the items apply. Overrides the `startAtItemId` prop for
+   *                this call only — the prop's value is preserved for
+   *                subsequent calls that omit this option.
+   */
+  setFeedItems: (items: FeedInput[], options?: { startAt?: string }) => void;
+
+  /**
+   * Imperatively scroll the feed to the item with the given id. Silently
+   * no-ops if the id is not in the current items. Call after `onFeedReady`
+   * for the initial mount; for an atomic set-and-scroll, use
+   * `setFeedItems(items, { startAt })` instead.
+   */
+  scrollToItem: (id: string, options?: { animated?: boolean }) => void;
+
   /** Append items to this feed instance. */
   appendFeedItems: (items: FeedInput[]) => void;
   /** Apply a content filter to this feed instance. Pass null to clear. */
@@ -382,6 +461,9 @@ export interface ShortKitWidgetProps {
 
 // --- Hook Return Types ---
 
+export type { ShortKitCarouselState } from './useShortKitCarousel';
+
+
 export interface ShortKitPlayerState {
   playerState: PlayerState;
   currentItem: ContentItem | null;

package/src/useShortKitCarousel.ts

@@ -0,0 +1,80 @@
+import { useCallback, useEffect, useState } from 'react';
+import NativeShortKitModule from './specs/NativeShortKitModule';
+import { ShortKitCommands } from './ShortKitCommands';
+import type { VideoCarouselItem } from './types';
+
+export interface ShortKitCarouselState {
+  /** Index of the currently active video in the carousel, or null if no carousel is active. */
+  activeIndex: number | null;
+  /** Number of videos in the active carousel item, or 0 if none. */
+  videoCount: number;
+  /** The active carousel item, or null if no carousel is active. */
+  activeCarouselItem: VideoCarouselItem | null;
+  /** Advance to the next video in the carousel. Returns true if the command was dispatched. */
+  next: () => boolean;
+  /** Go back to the previous video in the carousel. Returns true if the command was dispatched. */
+  previous: () => boolean;
+  /** Jump to a specific index in the carousel. Returns true if the command was dispatched. */
+  setActiveIndex: (index: number) => boolean;
+}
+
+/**
+ * Hook to access video carousel state and commands.
+ *
+ * Subscribes to `onVideoCarouselItemChanged` and
+ * `onVideoCarouselActiveVideoChanged` from the native TurboModule and surfaces
+ * carousel state as reactive values. The imperative commands (`next`,
+ * `previous`, `setActiveIndex`) delegate to `ShortKitCommands`.
+ *
+ * Does not require a `<ShortKitProvider>` — it subscribes directly to native
+ * events and is suitable for use inside overlay components.
+ */
+export function useShortKitCarousel(): ShortKitCarouselState {
+  const [activeIndex, setActiveIndexState] = useState<number | null>(() => {
+    const v = NativeShortKitModule?.getCarouselActiveIndex?.() ?? -1;
+    return v < 0 ? null : v;
+  });
+  const [activeCarouselItem, setActiveCarouselItem] = useState<VideoCarouselItem | null>(null);
+
+  useEffect(() => {
+    if (!NativeShortKitModule) return;
+    const subItem = NativeShortKitModule.onVideoCarouselItemChanged((e: any) => {
+      try {
+        const item = e.carouselItem
+          ? (JSON.parse(e.carouselItem) as VideoCarouselItem)
+          : null;
+        setActiveCarouselItem(item);
+        setActiveIndexState(
+          typeof e.activeVideoIndex === 'number' ? e.activeVideoIndex : null,
+        );
+      } catch {
+        // ignore parse errors
+      }
+    });
+    const subIdx = NativeShortKitModule.onVideoCarouselActiveVideoChanged((e: any) => {
+      setActiveIndexState(
+        typeof e.activeVideoIndex === 'number' ? e.activeVideoIndex : null,
+      );
+    });
+    return () => {
+      subItem?.remove?.();
+      subIdx?.remove?.();
+    };
+  }, []);
+
+  const next = useCallback(() => ShortKitCommands.carouselNext(), []);
+  const previous = useCallback(() => ShortKitCommands.carouselPrevious(), []);
+  const setActiveIndex = useCallback(
+    (i: number) => ShortKitCommands.carouselSetActiveIndex(i),
+    [],
+  );
+
+  return {
+    activeIndex,
+    videoCount: activeCarouselItem?.videos?.length ?? 0,
+    activeCarouselItem,
+    next,
+    previous,
+    setActiveIndex,
+  };
+}