@shortkitsdk/react-native 0.2.12 → 0.2.14

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

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

package/package.json

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

package/src/ShortKitCarouselOverlaySurface.tsx

@@ -1,6 +1,7 @@
-import React, { useMemo } from 'react';
+import React, { useState, useEffect, useMemo } from 'react';
 import { AppRegistry } from 'react-native';
 import type { CarouselOverlayProps, ImageCarouselItem } from './types';
+import NativeShortKitModule from './specs/NativeShortKitModule';
 
 const _carouselRegistry = new Map<string, React.ComponentType<CarouselOverlayProps>>();
 
@@ -24,7 +25,30 @@ export function registerCarouselOverlayComponent(
   });
 }
 
+/** 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 RawCarouselSurfaceProps {
+  surfaceId?: string;
   item?: string;
 }
 
@@ -38,6 +62,31 @@ function CarouselSurfaceInner(props: InnerProps) {
     return null;
   }
 
+  const sid = props.surfaceId;
+
+  const [isActive, setIsActive] = useState(false);
+  const [activeImageIndex, setActiveImageIndex] = useState(0);
+
+  // isActive delivered via onOverlayFullState (same event as video overlay)
+  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);
+  });
+
+  // activeImageIndex delivered via dedicated event
+  useOverlayEvent<{ surfaceId: string; activeImageIndex: number }>(
+    'onCarouselActiveImageChanged', sid,
+    (e) => setActiveImageIndex(e.activeImageIndex),
+  );
+
   const item: ImageCarouselItem | null = useMemo(() => {
     if (!props.item) {
       return null;
@@ -51,5 +100,11 @@ function CarouselSurfaceInner(props: InnerProps) {
 
   if (!item) return null;
 
-  return <Component item={item} />;
+  return (
+    <Component
+      item={item}
+      isActive={isActive}
+      activeImageIndex={activeImageIndex}
+    />
+  );
 }

package/src/ShortKitFeed.tsx

@@ -7,6 +7,7 @@ import { ShortKitContext } from './ShortKitContext';
 import { deserializeContentItem, serializeFeedConfig, serializeFeedInputs } from './serialization';
 import { registerOverlayComponent } from './ShortKitOverlaySurface';
 import { registerCarouselOverlayComponent } from './ShortKitCarouselOverlaySurface';
+import { registerVideoCarouselOverlayComponent } from './ShortKitVideoCarouselOverlaySurface';
 
 function generateFeedId(): string {
   return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
@@ -103,7 +104,10 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
     if (config?.carouselOverlay && config.carouselOverlay !== 'none') {
       registerCarouselOverlayComponent(config.carouselOverlay.name, config.carouselOverlay.component);
     }
-  }, [config?.overlay, config?.carouselOverlay]);
+    if (config?.videoCarouselOverlay && config.videoCarouselOverlay !== 'none') {
+      registerVideoCarouselOverlayComponent(config.videoCarouselOverlay.name, config.videoCarouselOverlay.component);
+    }
+  }, [config?.overlay, config?.carouselOverlay, config?.videoCarouselOverlay]);
 
   const serializedConfig = useMemo(
     () => (config ? serializeFeedConfig(config) : '{}'),

package/src/ShortKitOverlaySurface.tsx

@@ -252,11 +252,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).

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/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,
@@ -46,4 +48,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

@@ -156,6 +156,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;
@@ -239,6 +250,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

@@ -20,6 +20,7 @@ export interface FeedConfig {
   scrollAxis?: ScrollAxis;
   overlay?: OverlayConfig;
   carouselOverlay?: CarouselOverlayConfig;
+  videoCarouselOverlay?: VideoCarouselOverlayConfig;
   surveyMode?: SurveyMode;
   muteOnStart?: boolean;
   feedSource?: FeedSource;
@@ -41,6 +42,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 +86,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 +211,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 ---