@shortkitsdk/react-native 0.2.24 → 0.2.26

package/ios/ShortKitSDK.xcframework/ios-arm64_x86_64-simulator/ShortKitSDK.framework/_CodeSignature/CodeResources

@@ -10,39 +10,39 @@
 		</data>
 		<key>Info.plist</key>
 		<data>
-		aVOP/OHkEUzNyBoUHTT2iiGJbu4=
+		Iq8WNAyualDO11/gg6nPxoT/uLo=
 		</data>
 		<key>Modules/ShortKitSDK.swiftmodule/arm64-apple-ios-simulator.abi.json</key>
 		<data>
-		mxcDambiFIzUbFTPfCTaKwjGz/8=
+		Gzr/etd10eddI2LBjZqt4DbbwAo=
 		</data>
 		<key>Modules/ShortKitSDK.swiftmodule/arm64-apple-ios-simulator.private.swiftinterface</key>
 		<data>
-		wayE2tftrhjvaEAekKB20ZGO36g=
+		SY4J8Ap5bvNmlGr2eHB/mIEc9/4=
 		</data>
 		<key>Modules/ShortKitSDK.swiftmodule/arm64-apple-ios-simulator.swiftdoc</key>
 		<data>
-		OXtQVstuyP3hqDsSczrvdpR/BZY=
+		Jifa8RGekCm+oLvj1vexV+qHBxg=
 		</data>
 		<key>Modules/ShortKitSDK.swiftmodule/arm64-apple-ios-simulator.swiftinterface</key>
 		<data>
-		wayE2tftrhjvaEAekKB20ZGO36g=
+		SY4J8Ap5bvNmlGr2eHB/mIEc9/4=
 		</data>
 		<key>Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.abi.json</key>
 		<data>
-		mxcDambiFIzUbFTPfCTaKwjGz/8=
+		Gzr/etd10eddI2LBjZqt4DbbwAo=
 		</data>
 		<key>Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.private.swiftinterface</key>
 		<data>
-		c5HZCcsGjJPhu5ppN3Wq4SsCx2A=
+		RSB+lYIOsHV+EHcf6nw6updgwoE=
 		</data>
 		<key>Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.swiftdoc</key>
 		<data>
-		IjquwfiAxSFG2n0IR/+e9HvnZCM=
+		4SaiyfqnnCuP3NHBedJ86U5WUvk=
 		</data>
 		<key>Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.swiftinterface</key>
 		<data>
-		c5HZCcsGjJPhu5ppN3Wq4SsCx2A=
+		RSB+lYIOsHV+EHcf6nw6updgwoE=
 		</data>
 		<key>Modules/module.modulemap</key>
 		<data>
@@ -66,56 +66,56 @@
 		<dict>
 			<key>hash2</key>
 			<data>
-			s3LSfH8aLgl3mic08rsi958gHLv6ImNC8MsZtFoy8u0=
+			isVaXgRh+uHcpvhnLI/Xw6vyUa6t68QJDw+sElYsnNw=
 			</data>
 		</dict>
 		<key>Modules/ShortKitSDK.swiftmodule/arm64-apple-ios-simulator.private.swiftinterface</key>
 		<dict>
 			<key>hash2</key>
 			<data>
-			cYm595F0j0GSGb/GBTR7QHYSuFeUw9ZTPc8F87PKzvA=
+			1/jxH+/lRA97UGj3ZA78cxyVLWeDthh0KFAHyutYAGs=
 			</data>
 		</dict>
 		<key>Modules/ShortKitSDK.swiftmodule/arm64-apple-ios-simulator.swiftdoc</key>
 		<dict>
 			<key>hash2</key>
 			<data>
-			9FsW2XMD0E0AiZ7mHDBgLg/OeCcSwB2BmWG3PuPqPwM=
+			1ZNQBox7b3AwcLy9/eOdX9J9kLPO6aiDoKklf4b+uDw=
 			</data>
 		</dict>
 		<key>Modules/ShortKitSDK.swiftmodule/arm64-apple-ios-simulator.swiftinterface</key>
 		<dict>
 			<key>hash2</key>
 			<data>
-			cYm595F0j0GSGb/GBTR7QHYSuFeUw9ZTPc8F87PKzvA=
+			1/jxH+/lRA97UGj3ZA78cxyVLWeDthh0KFAHyutYAGs=
 			</data>
 		</dict>
 		<key>Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.abi.json</key>
 		<dict>
 			<key>hash2</key>
 			<data>
-			s3LSfH8aLgl3mic08rsi958gHLv6ImNC8MsZtFoy8u0=
+			isVaXgRh+uHcpvhnLI/Xw6vyUa6t68QJDw+sElYsnNw=
 			</data>
 		</dict>
 		<key>Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.private.swiftinterface</key>
 		<dict>
 			<key>hash2</key>
 			<data>
-			QRoqxRRNskUOSMbf+RlD6fMBj0mmhgmOres7jwvebiQ=
+			LcZQmnn2zALd1t49D1Ky9DkTE/qLtiA/Y8X7G8X0tpA=
 			</data>
 		</dict>
 		<key>Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.swiftdoc</key>
 		<dict>
 			<key>hash2</key>
 			<data>
-			R1p/WNYI3bnLOrWsIezOXSJRZEwJ/t8FuoDZCBZQhHg=
+			rFL1rnzbA6I/ynZT99TT87vcqERbX/oj+lvvjIITisM=
 			</data>
 		</dict>
 		<key>Modules/ShortKitSDK.swiftmodule/x86_64-apple-ios-simulator.swiftinterface</key>
 		<dict>
 			<key>hash2</key>
 			<data>
-			QRoqxRRNskUOSMbf+RlD6fMBj0mmhgmOres7jwvebiQ=
+			LcZQmnn2zALd1t49D1Ky9DkTE/qLtiA/Y8X7G8X0tpA=
 			</data>
 		</dict>
 		<key>Modules/module.modulemap</key>

package/package.json

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

package/src/ShortKitCarouselOverlaySurface.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useEffect, useMemo } from 'react';
+import React, { useRef, useState, useEffect, useMemo } from 'react';
 import { AppRegistry } from 'react-native';
 import type { CarouselOverlayProps, ImageCarouselItem } from './types';
 import NativeShortKitModule from './specs/NativeShortKitModule';
@@ -31,6 +31,12 @@ function useOverlayEvent<T extends { surfaceId: string }>(
   surfaceId: string | undefined,
   handler: (event: T) => void,
 ) {
+  // Ref-based handler capture so the subscription always calls the latest
+  // closure. Effect depends on [eventName, surfaceId] only — re-subscribing
+  // on every render would churn native subscriptions.
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
   useEffect(() => {
     if (!surfaceId) return;
 
@@ -39,12 +45,12 @@ function useOverlayEvent<T extends { surfaceId: string }>(
     if (typeof emitter === 'function') {
       sub = (emitter as (cb: (e: T) => void) => { remove: () => void })((e: T) => {
         if (e.surfaceId !== surfaceId) return;
-        handler(e);
+        handlerRef.current(e);
       });
     }
 
     return () => sub?.remove();
-  }, [surfaceId]);
+  }, [eventName, surfaceId]);
 }
 
 interface RawCarouselSurfaceProps {
@@ -87,21 +93,43 @@ function CarouselSurfaceInner(props: InnerProps) {
     (e) => setActiveImageIndex(e.activeImageIndex),
   );
 
-  const item: ImageCarouselItem | null = useMemo(() => {
-    if (!props.item) {
-      return null;
-    }
+  // Initial item — from surface props (set once on first mount).
+  const initialItem: ImageCarouselItem | null = useMemo(() => {
+    if (!props.item) return null;
+    try { return JSON.parse(props.item); } catch { return null; }
+  }, [props.item]);
+
+  // Subsequent item changes arrive via event — React diff instead of a full
+  // Fabric remount on cell reuse. Payload also resets isActive/activeImageIndex.
+  const [eventItem, setEventItem] = useState<ImageCarouselItem | null>(null);
+  useOverlayEvent<{
+    surfaceId: string;
+    item: string;
+    isActive: boolean;
+    activeImageIndex: number;
+  }>('onCarouselItemChanged', sid, (e) => {
     try {
-      return JSON.parse(props.item);
+      setEventItem(JSON.parse(e.item));
     } catch {
-      return null;
+      setEventItem(null);
     }
-  }, [props.item]);
+    setIsActive(e.isActive);
+    setActiveImageIndex(e.activeImageIndex);
+  });
+
+  // Prefer event-sourced item (set after first item change) over the initial
+  // props-sourced value. Initial mount still uses props; all subsequent
+  // transitions are event-driven.
+  const item = eventItem ?? initialItem;
 
   if (!item) return null;
 
   return (
+    // key={item.id} preserves "fresh mount per item" for the user's component
+    // — their local state resets cleanly across items — while the SDK wrapper
+    // above stays mounted and keeps its bridge event subscriptions alive.
     <Component
+      key={item.id}
       item={item}
       isActive={isActive}
       activeImageIndex={activeImageIndex}

package/src/ShortKitCommands.ts

@@ -14,6 +14,10 @@ export const ShortKitCommands = {
   seekAndPlay: (seconds: number) => NativeShortKitModule?.seekAndPlay(seconds),
   skipToNext: () => NativeShortKitModule?.skipToNext(),
   skipToPrevious: () => NativeShortKitModule?.skipToPrevious(),
+  carouselNext: (): boolean => NativeShortKitModule?.carouselNext() ?? false,
+  carouselPrevious: (): boolean => NativeShortKitModule?.carouselPrevious() ?? false,
+  carouselSetActiveIndex: (index: number): boolean =>
+    NativeShortKitModule?.carouselSetActiveIndex(index) ?? false,
   setMuted: (muted: boolean) => NativeShortKitModule?.setMuted(muted),
   setPlaybackRate: (rate: number) => NativeShortKitModule?.setPlaybackRate(rate),
   setCaptionsEnabled: (enabled: boolean) =>

package/src/ShortKitFeed.tsx

@@ -31,8 +31,11 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
   const {
     config,
     preloadId,
+    feedItems,
+    active,
     style,
     startAtItemId,
+    seedThumbnailUrl,
     onLoop,
     onFeedTransition,
     onFormatChange,
@@ -42,6 +45,8 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
     onDidFetchContentItems,
     onRemainingContentCountChange,
     onFeedReady,
+    onCarouselActiveVideoCompleted,
+    onVideoCarouselCellTap,
   } = props;
 
   const isInitialized = useContext(ShortKitInitContext);
@@ -49,21 +54,21 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
     throw new Error('ShortKitFeed must be used within a ShortKitProvider');
   }
 
-  // ⚡ TEMP — remove after verifying. Should only log on mount, not on every swipe/time update.
-  const renderCount = useRef(0);
-  renderCount.current++;
-  if (renderCount.current <= 3 || renderCount.current % 100 === 0) {
-    console.log(`[SK:Feed] render #${renderCount.current}`);
-  }
-
   // Stable feed instance ID — survives re-renders and React fast refresh
   const feedIdRef = useRef(generateFeedId());
   const feedId = feedIdRef.current;
 
   // Expose per-feed imperative methods on the ref
   useImperativeHandle(ref, () => ({
-    setFeedItems: (items: FeedInput[]) => {
-      NativeShortKitModule?.setFeedItems(feedId, serializeFeedInputs(items));
+    setFeedItems: (items: FeedInput[], options?: { startAt?: string }) => {
+      NativeShortKitModule?.setFeedItems(
+        feedId,
+        serializeFeedInputs(items),
+        options?.startAt ?? null,
+      );
+    },
+    scrollToItem: (id: string, options?: { animated?: boolean }) => {
+      NativeShortKitModule?.scrollFeedToItem(feedId, id, options?.animated ?? false);
     },
     appendFeedItems: (items: FeedInput[]) => {
       NativeShortKitModule?.appendFeedItems(feedId, serializeFeedInputs(items));
@@ -100,6 +105,23 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
     return () => subscription.remove();
   }, [feedId, onFeedReady]);
 
+  // Subscribe to per-feed video-carousel cell-tap events
+  useEffect(() => {
+    if (!NativeShortKitModule || !onVideoCarouselCellTap) return;
+
+    const subscription = NativeShortKitModule.onVideoCarouselCellTap((event) => {
+      if (event.feedId === feedId) {
+        onVideoCarouselCellTap({
+          id: event.id,
+          index: event.index,
+          pageIndex: event.pageIndex,
+        });
+      }
+    });
+
+    return () => subscription.remove();
+  }, [feedId, onVideoCarouselCellTap]);
+
   // Register overlay components before native view mounts.
   // useLayoutEffect fires after commit but before paint — before
   // didMoveToWindow/onAttachedToWindow on the native view.
@@ -120,6 +142,13 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
     [config],
   );
 
+  // Serialize feedItems once — only the initial value matters (mount-time
+  // prop). Post-mount item updates use the imperative ref methods.
+  const feedItemsJSON = useMemo(
+    () => (feedItems && feedItems.length > 0 ? serializeFeedInputs(feedItems) : undefined),
+    [feedItems],
+  );
+
   // ---------------------------------------------------------------------------
   // Subscribe to feed-level events and forward to callback props
   // ---------------------------------------------------------------------------
@@ -181,7 +210,10 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
 
     if (onRefreshStateChanged) {
       subscriptions.push(
-        NativeShortKitModule.onRefreshStateChanged((event) => {
+        NativeShortKitModule.onRefreshStateChangedPerFeed((event) => {
+          // Filter to this feed instance — prevents other feeds' refresh
+          // events from triggering this consumer's refresh handler.
+          if (event.feedId !== feedId && event.feedId !== '') return;
           const state: ShortKitRefreshState =
             event.status === 'pulling'
               ? { status: 'pulling', progress: event.progress }
@@ -204,6 +236,25 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
       );
     }
 
+    if (onCarouselActiveVideoCompleted) {
+      subscriptions.push(
+        NativeShortKitModule.onCarouselActiveVideoCompleted((event) => {
+          try {
+            onCarouselActiveVideoCompleted({
+              surfaceId: event.surfaceId,
+              contentItem: JSON.parse(event.contentItem),
+              indexInCarousel: event.indexInCarousel,
+              carouselItem: JSON.parse(event.carouselItem),
+              wasLast: event.wasLast,
+              willAutoAdvance: event.willAutoAdvance,
+            });
+          } catch (err) {
+            console.warn('[ShortKit] failed to parse onCarouselActiveVideoCompleted', err);
+          }
+        }),
+      );
+    }
+
     return () => {
       for (const sub of subscriptions) {
         sub.remove();
@@ -217,6 +268,7 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
     onDismiss,
     onRefreshStateChanged,
     onDidFetchContentItems,
+    onCarouselActiveVideoCompleted,
   ]);
 
   // ---------------------------------------------------------------------------
@@ -230,6 +282,9 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
         feedId={feedId}
         startAtItemId={startAtItemId}
         preloadId={preloadId}
+        seedThumbnailUrl={seedThumbnailUrl}
+        feedItemsJSON={feedItemsJSON}
+        active={active}
       />
     </View>
   );

package/src/ShortKitOverlaySurface.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useState } from 'react';
+import React, { useEffect, useRef, useState } from 'react';
 import { AppRegistry, View, Text } from 'react-native';
 import type { OverlayProps, PlayerState, PlayerTime, FeedScrollPhase } from './types';
 import { deserializeContentItem } from './serialization';
@@ -101,6 +101,12 @@ function useOverlayEvent<T extends { surfaceId: string }>(
   surfaceId: string | undefined,
   handler: (event: T) => void,
 ) {
+  // Stash the latest handler in a ref so the subscription below always calls
+  // the current closure. The effect deliberately depends on [eventName, surfaceId]
+  // only — re-subscribing on every render would churn native subscriptions.
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
   useEffect(() => {
     if (!surfaceId) return;
 
@@ -112,12 +118,12 @@ function useOverlayEvent<T extends { surfaceId: string }>(
     if (typeof emitter === 'function') {
       sub = (emitter as (cb: (e: T) => void) => { remove: () => void })((e: T) => {
         if (e.surfaceId !== surfaceId) return;
-        handler(e);
+        handlerRef.current(e);
       });
     }
 
     return () => sub?.remove();
-  }, [surfaceId]);
+  }, [eventName, surfaceId]);
 }
 
 function ShortKitOverlaySurfaceInner(props: InnerProps) {
@@ -131,12 +137,12 @@ function ShortKitOverlaySurfaceInner(props: InnerProps) {
     props.item ? deserializeContentItem(props.item) : null,
   );
 
-  // Sync item from props when surface is first mounted or remounted via updateInitProps
+  // Sync item from props when surface is first mounted or remounted via updateInitProps.
+  // Synchronous setState during render — React restarts with new state before
+  // committing, so the stale frame is never painted.
   const prevPropsItemRef = React.useRef(props.item);
   if (props.item !== prevPropsItemRef.current) {
     prevPropsItemRef.current = props.item;
-    // Synchronous state update during render — React restarts with new state
-    // before committing, so stale frame is never painted.
     setItem(props.item ? deserializeContentItem(props.item) : null);
   }
 
@@ -188,23 +194,45 @@ function ShortKitOverlaySurfaceInner(props: InnerProps) {
 
   // --- Event subscriptions (filtered by surfaceId) ---
 
-  // Item changed via event (not updateInitProps) — triggers React DIFF
-  // instead of full remount. Uses DeviceEventEmitter because this event
-  // is not in the TurboModule spec (avoids native codegen changes).
-  useEffect(() => {
-    if (!sid) return;
-    const { DeviceEventEmitter } = require('react-native');
-    const sub = DeviceEventEmitter.addListener('onOverlayItemChanged', (e: { surfaceId: string; item: string }) => {
-      if (e.surfaceId !== sid) return;
-      const newItem = e.item ? deserializeContentItem(e.item) : null;
-      if (newItem) setItem(newItem);
-      // Reset playback state for the new item
-      setIsActive(false);
-      setPlayerState('idle' as PlayerState);
-      setTime({ current: 0, duration: 0, buffered: 0 });
-    });
-    return () => sub.remove();
-  }, [sid]);
+  // Item changed via event — triggers React DIFF instead of a full Fabric
+  // remount. Now a first-class codegen event (see NativeShortKitModule.ts),
+  // which routes through the JSI EventEmitterCallback on both platforms.
+  // Payload carries full initial state to match what pushInitialProperties()
+  // would have set, avoiding any stale-state window before activatePlayback().
+  useOverlayEvent<{
+    surfaceId: string;
+    item: string;
+    isActive: boolean;
+    playerState: string;
+    isMuted: boolean;
+    playbackRate: number;
+    captionsEnabled: boolean;
+    activeCue: string | null;
+    feedScrollPhase: string | null;
+  }>('onOverlayItemChanged', sid, (e) => {
+    const newItem = e.item ? deserializeContentItem(e.item) : null;
+    if (newItem) setItem(newItem);
+    // Apply ALL initial state — matches the old setProperties() behavior.
+    setIsActive(e.isActive);
+    setPlayerState(e.playerState as PlayerState);
+    setIsMuted(e.isMuted);
+    setPlaybackRate(e.playbackRate);
+    setCaptionsEnabled(e.captionsEnabled);
+    setTime({ current: 0, duration: 0, buffered: 0 });
+    const rawCue = e.activeCue ?? null;
+    lastActiveCueJsonRef.current = rawCue;
+    try {
+      setActiveCue(rawCue ? JSON.parse(rawCue) : null);
+    } catch {
+      setActiveCue(null);
+    }
+    try {
+      const next = e.feedScrollPhase ? JSON.parse(e.feedScrollPhase) : null;
+      setFeedScrollPhase(next);
+    } catch {
+      setFeedScrollPhase(null);
+    }
+  });
 
   useOverlayEvent<{ surfaceId: string; isActive: boolean }>(
     'onOverlayActiveChanged', sid,
@@ -310,7 +338,15 @@ function ShortKitOverlaySurfaceInner(props: InnerProps) {
 
   return (
     <OverlayErrorBoundary surfaceId={sid} overlayName={props.overlayName}>
+      {/*
+        key={item.id} preserves the legacy "fresh mount per item" contract
+        for the user's overlay component (their local useState/useRef reset
+        cleanly across items). The SDK wrapper above stays mounted, so
+        bridge event subscriptions and SDK-side state survive cell reuse
+        instead of churning on every swipe.
+      */}
       <Component
+        key={item.id}
         item={item}
         isActive={isActive}
         playerState={playerState}

package/src/ShortKitProvider.tsx

@@ -19,6 +19,7 @@ import type {
 } from './types';
 import {
   serializeFeedConfig,
+  serializeFeedInputs,
   deserializePlayerState,
   deserializeContentItem,
   deserializePlayerTime,
@@ -466,7 +467,7 @@ export function ShortKitProvider({
   const preloadFeedCmd = useCallback(async (config?: Partial<FeedConfig>, items?: FeedInput[]): Promise<string> => {
     if (!NativeShortKitModule) return '';
     const configJSON = config ? serializeFeedConfig(config as FeedConfig) : '{}';
-    const itemsJSON = items ? JSON.stringify(items) : null;
+    const itemsJSON = items ? serializeFeedInputs(items) : null;
     return NativeShortKitModule.preloadFeed(configJSON, itemsJSON);
   }, []);
 

package/src/ShortKitVideoCarouselOverlaySurface.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useEffect, useMemo } from 'react';
+import React, { useRef, useState, useEffect, useMemo } from 'react';
 import { AppRegistry } from 'react-native';
 import type { VideoCarouselOverlayProps, VideoCarouselItem, ContentItem, PlayerTime, PlayerState } from './types';
 import NativeShortKitModule from './specs/NativeShortKitModule';
@@ -31,6 +31,12 @@ function useOverlayEvent<T extends { surfaceId: string }>(
   surfaceId: string | undefined,
   handler: (event: T) => void,
 ) {
+  // Ref-based handler capture so the subscription always calls the latest
+  // closure. Effect depends on [eventName, surfaceId] only — re-subscribing
+  // on every render would churn native subscriptions.
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
   useEffect(() => {
     if (!surfaceId) return;
 
@@ -39,12 +45,12 @@ function useOverlayEvent<T extends { surfaceId: string }>(
     if (typeof emitter === 'function') {
       sub = (emitter as (cb: (e: T) => void) => { remove: () => void })((e: T) => {
         if (e.surfaceId !== surfaceId) return;
-        handler(e);
+        handlerRef.current(e);
       });
     }
 
     return () => sub?.remove();
-  }, [surfaceId]);
+  }, [eventName, surfaceId]);
 }
 
 interface RawProps {
@@ -140,11 +146,51 @@ function VideoCarouselSurfaceInner(props: InnerProps) {
     },
   );
 
-  if (!carouselItem || !activeVideo) return null;
+  // Carousel item itself changes via event — React diff instead of a full
+  // Fabric remount on cell reuse. Payload carries full initial state to match
+  // the old setProperties() path.
+  const [eventCarouselItem, setEventCarouselItem] = useState<VideoCarouselItem | null>(null);
+  useOverlayEvent<{
+    surfaceId: string;
+    carouselItem: string;
+    activeVideo: string;
+    activeVideoIndex: number;
+    isActive: boolean;
+    playerState: string;
+    isMuted: boolean;
+  }>('onVideoCarouselItemChanged', sid, (e) => {
+    try {
+      setEventCarouselItem(JSON.parse(e.carouselItem));
+    } catch {
+      setEventCarouselItem(null);
+    }
+    try {
+      setActiveVideo(e.activeVideo ? JSON.parse(e.activeVideo) : null);
+    } catch {
+      setActiveVideo(null);
+    }
+    setActiveVideoIndex(e.activeVideoIndex);
+    setIsActive(e.isActive);
+    setPlayerState(e.playerState as PlayerState);
+    setIsMuted(e.isMuted);
+    setTime({ current: 0, duration: 0, buffered: 0 });
+  });
+
+  // Prefer the event-sourced carousel item (set after first item change) over
+  // the initial props-sourced value. The initial mount still goes through
+  // props, but all subsequent item transitions are event-driven.
+  const effectiveCarouselItem = eventCarouselItem ?? carouselItem;
+
+  if (!effectiveCarouselItem || !activeVideo) return null;
 
   return (
+    // key={effectiveCarouselItem.id} preserves the legacy "fresh mount per
+    // carousel item" contract for the user's component — their local state
+    // resets cleanly across items — while the SDK wrapper above stays mounted
+    // and keeps its bridge event subscriptions alive.
     <Component
-      carouselItem={carouselItem}
+      key={effectiveCarouselItem.id}
+      carouselItem={effectiveCarouselItem}
       activeVideo={activeVideo}
       activeVideoIndex={activeVideoIndex}
       isActive={isActive}

package/src/index.ts

@@ -4,6 +4,7 @@ export { ShortKitPlayer } from './ShortKitPlayer';
 export { ShortKitWidget } from './ShortKitWidget';
 export { useShortKitPlayer } from './useShortKitPlayer';
 export { useShortKit } from './useShortKit';
+export { useShortKitCarousel } from './useShortKitCarousel';
 export type {
   FeedConfig,
   FeedHeight,
@@ -40,6 +41,7 @@ export type {
   ShortKitPlayerProps,
   ShortKitWidgetProps,
   ShortKitPlayerState,
+  ShortKitCarouselState,
   ShortKitRefreshState,
   StoryboardData,
   StoryboardTile,

package/src/serialization.ts

@@ -4,6 +4,7 @@ import type {
   FeedInput,
   PlayerState,
   PlayerTime,
+  VideoCarouselVideoInput,
 } from './types';
 
 /**
@@ -88,9 +89,44 @@ export function deserializePlayerTime(event: {
   };
 }
 
+/**
+ * Serialize a single VideoCarouselVideoInput slide for the bridge.
+ * Always emits `origin` (defaults to 'other') for a consistent native shape.
+ */
+function serializeVideoCarouselSlide(
+  slide: VideoCarouselVideoInput,
+): Record<string, unknown> {
+  return {
+    playbackId: slide.playbackId,
+    origin: slide.origin ?? 'other',
+    ...(slide.fallbackUrl != null ? { fallbackUrl: slide.fallbackUrl } : {}),
+  };
+}
+
 /**
  * Serialize FeedInput[] to a JSON string for the bridge.
+ * For video items, `origin` is included and defaults to 'other' when omitted.
  */
 export function serializeFeedInputs(items: FeedInput[]): string {
-  return JSON.stringify(items);
+  const serialized = items.map((input) => {
+    if (input.type === 'video') {
+      return {
+        type: 'video',
+        playbackId: input.playbackId,
+        origin: input.origin ?? 'other',
+        ...(input.fallbackUrl != null ? { fallbackUrl: input.fallbackUrl } : {}),
+      };
+    }
+    if (input.type === 'videoCarousel') {
+      return {
+        type: 'videoCarousel',
+        item: {
+          ...input.item,
+          videos: input.item.videos.map(serializeVideoCarouselSlide),
+        },
+      };
+    }
+    return input;
+  });
+  return JSON.stringify(serialized);
 }