@shortkitsdk/react-native 0.2.24 → 0.2.25

package/src/ShortKitFeed.tsx

@@ -33,6 +33,7 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
     preloadId,
     style,
     startAtItemId,
+    seedThumbnailUrl,
     onLoop,
     onFeedTransition,
     onFormatChange,
@@ -42,6 +43,7 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
     onDidFetchContentItems,
     onRemainingContentCountChange,
     onFeedReady,
+    onCarouselActiveVideoCompleted,
   } = props;
 
   const isInitialized = useContext(ShortKitInitContext);
@@ -49,13 +51,6 @@ 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;
@@ -204,6 +199,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 +231,7 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
     onDismiss,
     onRefreshStateChanged,
     onDidFetchContentItems,
+    onCarouselActiveVideoCompleted,
   ]);
 
   // ---------------------------------------------------------------------------
@@ -230,6 +245,7 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
         feedId={feedId}
         startAtItemId={startAtItemId}
         preloadId={preloadId}
+        seedThumbnailUrl={seedThumbnailUrl}
       />
     </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/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);
 }

package/src/specs/NativeShortKitModule.ts

@@ -177,12 +177,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 +216,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 +255,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;
@@ -239,6 +280,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>;
@@ -270,8 +315,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,14 @@ 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;
 }
 
 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,17 @@ 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;
   onLoop?: (event: LoopEvent) => void;
   onFeedTransition?: (event: FeedTransitionEvent) => void;
   onFormatChange?: (event: FormatChangeEvent) => void;
@@ -316,6 +330,15 @@ 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;
 }
 
 /**
@@ -382,6 +405,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,
+  };
+}