@shortkitsdk/react-native 0.2.12 → 0.2.15

package/src/ShortKitOverlaySurface.tsx

@@ -161,6 +161,8 @@ function ShortKitOverlaySurfaceInner(props: InnerProps) {
   const [activeCue, setActiveCue] = useState<OverlayProps['activeCue']>(
     props.activeCue ? JSON.parse(props.activeCue) : null,
   );
+  // Track raw JSON string to avoid re-parsing unchanged cues
+  const lastActiveCueJsonRef = React.useRef<string | null>(props.activeCue ?? null);
   const [feedScrollPhase, setFeedScrollPhase] =
     useState<FeedScrollPhase | null>(
       props.feedScrollPhase ? JSON.parse(props.feedScrollPhase) : null,
@@ -176,7 +178,9 @@ function ShortKitOverlaySurfaceInner(props: InnerProps) {
     setIsMuted(props.isMuted ?? true);
     setPlaybackRate(props.playbackRate ?? 1);
     setCaptionsEnabled(props.captionsEnabled ?? false);
-    setActiveCue(props.activeCue ? JSON.parse(props.activeCue) : null);
+    const rawCue = props.activeCue ?? null;
+    lastActiveCueJsonRef.current = rawCue;
+    setActiveCue(rawCue ? JSON.parse(rawCue) : null);
     setFeedScrollPhase(
       props.feedScrollPhase ? JSON.parse(props.feedScrollPhase) : null,
     );
@@ -229,7 +233,12 @@ function ShortKitOverlaySurfaceInner(props: InnerProps) {
 
   useOverlayEvent<{ surfaceId: string; activeCue: string | null }>(
     'onOverlayActiveCueChanged', sid,
-    (e) => setActiveCue(e.activeCue ? JSON.parse(e.activeCue) : null),
+    (e) => {
+      const raw = e.activeCue ?? null;
+      if (raw === lastActiveCueJsonRef.current) return;
+      lastActiveCueJsonRef.current = raw;
+      setActiveCue(raw ? JSON.parse(raw) : null);
+    },
   );
 
   useOverlayEvent<{ surfaceId: string; feedScrollPhase: string | null }>(
@@ -252,11 +261,10 @@ function ShortKitOverlaySurfaceInner(props: InnerProps) {
     },
   );
 
-  // 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 }),
-  // );
+  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).
@@ -275,10 +283,15 @@ function ShortKitOverlaySurfaceInner(props: InnerProps) {
     setIsMuted(e.isMuted);
     setPlaybackRate(e.playbackRate);
     setCaptionsEnabled(e.captionsEnabled);
-    try {
-      setActiveCue(e.activeCue ? JSON.parse(e.activeCue) : null);
-    } catch {
-      setActiveCue(null);
+    // Only re-parse activeCue if the raw JSON string actually changed
+    const rawCue = e.activeCue ?? null;
+    if (rawCue !== lastActiveCueJsonRef.current) {
+      lastActiveCueJsonRef.current = rawCue;
+      try {
+        setActiveCue(rawCue ? JSON.parse(rawCue) : null);
+      } catch {
+        setActiveCue(null);
+      }
     }
     try {
       const next = e.feedScrollPhase ? JSON.parse(e.feedScrollPhase) : null;

package/src/ShortKitProvider.tsx

@@ -1,7 +1,7 @@
 import React, { useCallback, useEffect, useMemo, useReducer, useRef } from 'react';
 import { AppState } from 'react-native';
 import type { AppStateStatus } from 'react-native';
-import { ShortKitContext } from './ShortKitContext';
+import { ShortKitContext, ShortKitInitContext } from './ShortKitContext';
 import type { ShortKitContextValue } from './ShortKitContext';
 import type {
   ShortKitProviderProps,
@@ -500,6 +500,8 @@ export function ShortKitProvider({
   );
 
   return (
-    <ShortKitContext.Provider value={value}>{children}</ShortKitContext.Provider>
+    <ShortKitInitContext.Provider value={true}>
+      <ShortKitContext.Provider value={value}>{children}</ShortKitContext.Provider>
+    </ShortKitInitContext.Provider>
   );
 }

package/src/ShortKitVideoCarouselOverlaySurface.tsx

@@ -0,0 +1,156 @@
+import React, { useState, useEffect, useMemo } from 'react';
+import { AppRegistry } from 'react-native';
+import type { VideoCarouselOverlayProps, VideoCarouselItem, ContentItem, PlayerTime, PlayerState } from './types';
+import NativeShortKitModule from './specs/NativeShortKitModule';
+
+const _videoCarouselRegistry = new Map<string, React.ComponentType<VideoCarouselOverlayProps>>();
+
+/**
+ * Register a named video carousel overlay component for rendering inside feed cells.
+ * Called by ShortKitFeed on mount via useLayoutEffect.
+ * Idempotent — registering the same name twice is a no-op.
+ */
+export function registerVideoCarouselOverlayComponent(
+  name: string,
+  component: React.ComponentType<VideoCarouselOverlayProps>,
+) {
+  if (_videoCarouselRegistry.has(name)) return;
+  _videoCarouselRegistry.set(name, component);
+
+  const moduleName = `ShortKitVideoCarouselOverlay_${name}`;
+  AppRegistry.registerComponent(moduleName, () => {
+    return function NamedVideoCarouselSurface(props: RawProps) {
+      return <VideoCarouselSurfaceInner {...props} overlayName={name} />;
+    };
+  });
+}
+
+/** Subscribe to a named native event, filtered by surfaceId. */
+function useOverlayEvent<T extends { surfaceId: string }>(
+  eventName: string,
+  surfaceId: string | undefined,
+  handler: (event: T) => void,
+) {
+  useEffect(() => {
+    if (!surfaceId) return;
+
+    let sub: { remove: () => void } | undefined;
+    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);
+      });
+    }
+
+    return () => sub?.remove();
+  }, [surfaceId]);
+}
+
+interface RawProps {
+  surfaceId?: string;
+  carouselItem?: string;
+  activeVideo?: string;
+  activeVideoIndex?: number;
+  isActive?: boolean;
+  playerState?: string;
+  isMuted?: boolean;
+}
+
+interface InnerProps extends RawProps {
+  overlayName: string;
+}
+
+function VideoCarouselSurfaceInner(props: InnerProps) {
+  const Component = _videoCarouselRegistry.get(props.overlayName);
+  if (!Component) return null;
+
+  const sid = props.surfaceId;
+
+  // Playback state — initialized from surface props, updated via events
+  const [isActive, setIsActive] = useState(props.isActive ?? false);
+  const [playerState, setPlayerState] = useState<PlayerState>((props.playerState as PlayerState) ?? 'idle');
+  const [isMuted, setIsMuted] = useState(props.isMuted ?? true);
+  const [time, setTime] = useState<PlayerTime>({ current: 0, duration: 0, buffered: 0 });
+
+  // Batched full-state sync
+  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);
+  });
+
+  // Individual state updates
+  useOverlayEvent<{ surfaceId: string; playerState: string }>(
+    'onOverlayPlayerStateChanged', sid,
+    (e) => setPlayerState(e.playerState as PlayerState),
+  );
+
+  useOverlayEvent<{ surfaceId: string; isMuted: boolean }>(
+    'onOverlayMutedChanged', sid,
+    (e) => setIsMuted(e.isMuted),
+  );
+
+  // Time updates (250ms coalesced)
+  useOverlayEvent<{ surfaceId: string; current: number; duration: number; buffered: number }>(
+    'onOverlayTimeUpdate', sid,
+    (e) => setTime({ current: e.current, duration: e.duration, buffered: e.buffered }),
+  );
+
+  // Carousel item — from surface props (set once in configure())
+  const carouselItem: VideoCarouselItem | null = useMemo(() => {
+    if (!props.carouselItem) return null;
+    try { return JSON.parse(props.carouselItem); } catch { return null; }
+  }, [props.carouselItem]);
+
+  // Active video — initialized from surface props, updated via events on swipe
+  const initialActiveVideo: ContentItem | null = useMemo(() => {
+    if (!props.activeVideo) return null;
+    try { return JSON.parse(props.activeVideo); } catch { return null; }
+  }, [props.activeVideo]);
+
+  const [activeVideo, setActiveVideo] = useState<ContentItem | null>(initialActiveVideo);
+  const [activeVideoIndex, setActiveVideoIndex] = useState(props.activeVideoIndex ?? 0);
+
+  // Sync from props when surface is reconfigured (new carousel item)
+  useEffect(() => {
+    setActiveVideo(initialActiveVideo);
+    setActiveVideoIndex(props.activeVideoIndex ?? 0);
+  }, [initialActiveVideo]);
+
+  // Active video changes via event (no Fabric remount)
+  useOverlayEvent<{ surfaceId: string; activeVideo: string; activeVideoIndex: number }>(
+    'onVideoCarouselActiveVideoChanged', sid,
+    (e) => {
+      try {
+        setActiveVideo(JSON.parse(e.activeVideo));
+      } catch {
+        // ignore parse errors
+      }
+      setActiveVideoIndex(e.activeVideoIndex);
+    },
+  );
+
+  if (!carouselItem || !activeVideo) return null;
+
+  return (
+    <Component
+      carouselItem={carouselItem}
+      activeVideo={activeVideo}
+      activeVideoIndex={activeVideoIndex}
+      isActive={isActive}
+      time={time}
+      playerState={playerState}
+      isMuted={isMuted}
+    />
+  );
+}

package/src/ShortKitWidget.tsx

@@ -2,7 +2,7 @@ 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';
+import { ShortKitInitContext } from './ShortKitContext';
 
 /**
  * Horizontal carousel widget component. Displays a row of video cards
@@ -13,8 +13,8 @@ import { ShortKitContext } from './ShortKitContext';
 export function ShortKitWidget(props: ShortKitWidgetProps) {
   const { config, items, style } = props;
 
-  const context = useContext(ShortKitContext);
-  if (!context) {
+  const isInitialized = useContext(ShortKitInitContext);
+  if (!isInitialized) {
     throw new Error('ShortKitWidget must be used within a ShortKitProvider');
   }
 

package/src/index.ts

@@ -11,6 +11,7 @@ export type {
   FeedSource,
   OverlayConfig,
   CarouselOverlayConfig,
+  VideoCarouselOverlayConfig,
   SurveyMode,
 
   PlayerConfig,
@@ -20,6 +21,7 @@ export type {
   ContentItem,
   CarouselImage,
   ImageCarouselItem,
+  VideoCarouselItem,
   FeedInput,
   JSONValue,
   CaptionTrack,
@@ -39,6 +41,7 @@ export type {
   ShortKitPlayerProps,
   ShortKitWidgetProps,
   ShortKitPlayerState,
+  ShortKitRefreshState,
   StoryboardData,
   StoryboardTile,
 } from './types';
@@ -46,4 +49,5 @@ 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';
+export { registerVideoCarouselOverlayComponent } from './ShortKitVideoCarouselOverlaySurface';
+export type { OverlayProps, CarouselOverlayProps, VideoCarouselOverlayProps } from './types';

package/src/serialization.ts

@@ -25,11 +25,18 @@ export function serializeFeedConfig(config: FeedConfig): string {
     return JSON.stringify({ type: 'custom', name: raw.name });
   })();
 
+  const videoCarouselOverlay = (() => {
+    const raw = config.videoCarouselOverlay ?? 'none';
+    if (typeof raw === 'string') return JSON.stringify(raw);
+    return JSON.stringify({ type: 'custom', name: raw.name });
+  })();
+
   return JSON.stringify({
     feedHeight: JSON.stringify(config.feedHeight ?? { type: 'fullscreen' }),
     scrollAxis: config.scrollAxis ?? 'vertical',
     overlay,
     carouselOverlay,
+    videoCarouselOverlay,
     surveyMode: JSON.stringify(config.surveyMode ?? 'none'),
     muteOnStart: config.muteOnStart ?? true,
     feedSource: config.feedSource ?? 'algorithmic',

package/src/specs/NativeShortKitModule.ts

@@ -91,7 +91,10 @@ type RemainingContentCountEvent = Readonly<{
 
 type DismissEvent = Readonly<{}>;
 
-type RefreshRequestedEvent = Readonly<{}>;
+type RefreshStateChangedEvent = Readonly<{
+  status: string;
+  progress: Double;
+}>;
 
 type DidFetchContentItemsEvent = Readonly<{
   items: string; // JSON-serialized ContentItem[]
@@ -156,6 +159,17 @@ type OverlayTimeUpdateEvent = Readonly<{
   buffered: Double;
 }>;
 
+type CarouselActiveImageEvent = Readonly<{
+  surfaceId: string;
+  activeImageIndex: Int32;
+}>;
+
+type VideoCarouselActiveVideoEvent = Readonly<{
+  surfaceId: string;
+  activeVideo: string;
+  activeVideoIndex: Int32;
+}>;
+
 type OverlayFullStateEvent = Readonly<{
   surfaceId: string;
   isActive: boolean;
@@ -225,7 +239,7 @@ export interface Spec extends TurboModule {
   readonly onSurveyResponse: EventEmitter<SurveyResponseEvent>;
   readonly onContentTapped: EventEmitter<ContentTappedEvent>;
   readonly onDismiss: EventEmitter<DismissEvent>;
-  readonly onRefreshRequested: EventEmitter<RefreshRequestedEvent>;
+  readonly onRefreshStateChanged: EventEmitter<RefreshStateChangedEvent>;
   readonly onDidFetchContentItems: EventEmitter<DidFetchContentItemsEvent>;
   readonly onFeedReady: EventEmitter<FeedReadyEvent>;
 
@@ -239,6 +253,8 @@ export interface Spec extends TurboModule {
   readonly onOverlayFeedScrollPhaseChanged: EventEmitter<OverlayFeedScrollPhaseEvent>;
   readonly onOverlayTimeUpdate: EventEmitter<OverlayTimeUpdateEvent>;
   readonly onOverlayFullState: EventEmitter<OverlayFullStateEvent>;
+  readonly onCarouselActiveImageChanged: EventEmitter<CarouselActiveImageEvent>;
+  readonly onVideoCarouselActiveVideoChanged: EventEmitter<VideoCarouselActiveVideoEvent>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>('ShortKitModule');

package/src/types.ts

@@ -15,16 +15,24 @@ export interface FeedFilter {
 
 export type CaptionSource = 'embedded' | 'external' | 'generated';
 
+export type ShortKitRefreshState =
+  | { status: 'idle' }
+  | { status: 'pulling'; progress: number }
+  | { status: 'triggered' }
+  | { status: 'refreshing' };
+
 export interface FeedConfig {
   feedHeight?: FeedHeight;
   scrollAxis?: ScrollAxis;
   overlay?: OverlayConfig;
   carouselOverlay?: CarouselOverlayConfig;
+  videoCarouselOverlay?: VideoCarouselOverlayConfig;
   surveyMode?: SurveyMode;
   muteOnStart?: boolean;
   feedSource?: FeedSource;
   autoplay?: boolean;
   filter?: FeedFilter;
+  pullToRefreshEnabled?: boolean;
 }
 
 export type FeedHeight =
@@ -41,6 +49,10 @@ export type CarouselOverlayConfig =
   | 'none'
   | { type: 'custom'; name: string; component: React.ComponentType<CarouselOverlayProps> };
 
+export type VideoCarouselOverlayConfig =
+  | 'none'
+  | { type: 'custom'; name: string; component: React.ComponentType<VideoCarouselOverlayProps> };
+
 export type SurveyMode =
   | 'none'
   | { type: 'template'; name: 'default' };
@@ -81,9 +93,20 @@ export interface ImageCarouselItem {
   articleUrl?: string;
 }
 
+export interface VideoCarouselItem {
+  id: string;
+  videos: ContentItem[];
+  title?: string;
+  description?: string;
+  author?: string;
+  section?: string;
+  articleUrl?: string;
+}
+
 export type FeedInput =
   | { type: 'video'; playbackId: string; fallbackUrl?: string }
-  | { type: 'imageCarousel'; item: ImageCarouselItem };
+  | { type: 'imageCarousel'; item: ImageCarouselItem }
+  | { type: 'videoCarousel'; item: VideoCarouselItem };
 
 export type JSONValue =
   | string
@@ -195,6 +218,28 @@ export interface OverlayProps {
 export interface CarouselOverlayProps {
   /** The carousel item for this cell. */
   item: ImageCarouselItem;
+  /** Whether this carousel cell is the active (on-screen) cell. */
+  isActive: boolean;
+  /** Index of the currently visible image within the carousel. */
+  activeImageIndex: number;
+}
+
+/** Props passed to video carousel overlay components rendered inside feed cells. */
+export interface VideoCarouselOverlayProps {
+  /** The video carousel item for this cell. */
+  carouselItem: VideoCarouselItem;
+  /** The currently active video within the carousel. */
+  activeVideo: ContentItem;
+  /** Index of the currently active video within the carousel. */
+  activeVideoIndex: number;
+  /** Whether this carousel cell is the active (on-screen) cell. */
+  isActive: boolean;
+  /** Current playback time for the active video. */
+  time: PlayerTime;
+  /** Current player state for the active video. */
+  playerState: PlayerState;
+  /** Whether audio is muted. */
+  isMuted: boolean;
 }
 
 // --- Provider Props ---
@@ -227,8 +272,8 @@ export interface ShortKitFeedProps {
   onContentTapped?: (contentId: string, index: number) => void;
   /** Called when the user dismisses the feed (swipe-down or back gesture). */
   onDismiss?: () => void;
-  /** Called when the user pulls to refresh in custom feed mode. */
-  onRefreshRequested?: () => void;
+  /** Called when the pull-to-refresh state changes. */
+  onRefreshStateChanged?: (state: ShortKitRefreshState) => void;
   /** Called when the SDK fetches content items from the algorithmic feed.
    *  Use to pre-fetch your own metadata for the given items. */
   onDidFetchContentItems?: (items: ContentItem[]) => void;

package/ios/{ShortKitSDK.xcframework.bak → ShortKitSDK.xcframework.dev-backup}/Info.plist

@@ -8,7 +8,7 @@
 			<key>BinaryPath</key>
 			<string>ShortKitSDK.framework/ShortKitSDK</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64-simulator</string>
+			<string>ios-arm64</string>
 			<key>LibraryPath</key>
 			<string>ShortKitSDK.framework</string>
 			<key>SupportedArchitectures</key>
@@ -17,14 +17,12 @@
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
-			<key>SupportedPlatformVariant</key>
-			<string>simulator</string>
 		</dict>
 		<dict>
 			<key>BinaryPath</key>
 			<string>ShortKitSDK.framework/ShortKitSDK</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64</string>
+			<string>ios-arm64-simulator</string>
 			<key>LibraryPath</key>
 			<string>ShortKitSDK.framework</string>
 			<key>SupportedArchitectures</key>
@@ -33,6 +31,8 @@
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
+			<key>SupportedPlatformVariant</key>
+			<string>simulator</string>
 		</dict>
 	</array>
 	<key>CFBundlePackageType</key>