@shortkitsdk/react-native 0.2.11 → 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.11",
+  "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/ShortKitContext.ts

@@ -3,6 +3,7 @@ import type {
   ContentItem,
   FeedConfig,
   FeedFilter,
+  FeedInput,
   PlayerTime,
   PlayerState,
   CaptionTrack,
@@ -45,7 +46,7 @@ export interface ShortKitContextValue {
   fetchContent: (limit?: number, filter?: FeedFilter) => Promise<ContentItem[]>;
 
   // Preload
-  preloadFeed: (config?: Partial<FeedConfig>) => Promise<string>;
+  preloadFeed: (config?: Partial<FeedConfig>, items?: FeedInput[]) => Promise<string>;
 
   // Storyboard / seek thumbnails
   prefetchStoryboard: (playbackId: string) => void;

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 => {
@@ -41,6 +42,7 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
     onRefreshRequested,
     onDidFetchContentItems,
     onRemainingContentCountChange,
+    onFeedReady,
   } = props;
 
   const context = useContext(ShortKitContext);
@@ -79,6 +81,19 @@ export const ShortKitFeed = forwardRef<ShortKitFeedHandle, ShortKitFeedProps>(
     return () => subscription.remove();
   }, [feedId, onRemainingContentCountChange]);
 
+  // Subscribe to per-feed ready event
+  useEffect(() => {
+    if (!NativeShortKitModule || !onFeedReady) return;
+
+    const subscription = NativeShortKitModule.onFeedReady((event) => {
+      if (event.feedId === feedId) {
+        onFeedReady();
+      }
+    });
+
+    return () => subscription.remove();
+  }, [feedId, onFeedReady]);
+
   // Register overlay components before native view mounts.
   // useLayoutEffect fires after commit but before paint — before
   // didMoveToWindow/onAttachedToWindow on the native view.
@@ -89,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

@@ -1,9 +1,11 @@
-import React, { useEffect, useMemo, useState } from 'react';
-import { AppRegistry, DeviceEventEmitter, Platform } from 'react-native';
+import React, { useEffect, useState } from 'react';
+import { AppRegistry, View, Text } from 'react-native';
 import type { OverlayProps, PlayerState, PlayerTime, FeedScrollPhase } from './types';
 import { deserializeContentItem } from './serialization';
 import NativeShortKitModule from './specs/NativeShortKitModule';
 
+const SK_OVERLAY_TAG = '[ShortKit:OverlaySurface]';
+
 // Named registry — supports different overlay components per feed
 const _overlayRegistry = new Map<string, React.ComponentType<OverlayProps>>();
 
@@ -16,7 +18,9 @@ export function registerOverlayComponent(
   name: string,
   component: React.ComponentType<OverlayProps>,
 ) {
-  if (_overlayRegistry.has(name)) return;
+  if (_overlayRegistry.has(name)) {
+    return;
+  }
   _overlayRegistry.set(name, component);
 
   const moduleName = `ShortKitOverlay_${name}`;
@@ -27,6 +31,47 @@ export function registerOverlayComponent(
   });
 }
 
+/**
+ * Error boundary that catches crashes inside the overlay component.
+ * Without this, a crash in an isolated React surface is silent on Android.
+ */
+class OverlayErrorBoundary extends React.Component<
+  { surfaceId?: string; overlayName: string; children: React.ReactNode },
+  { error: Error | null }
+> {
+  state: { error: Error | null } = { error: null };
+
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: React.ErrorInfo) {
+    console.error(
+      `${SK_OVERLAY_TAG} CRASH in overlay '${this.props.overlayName}' (surfaceId=${this.props.surfaceId}):`,
+      error.message,
+      '\nComponent stack:',
+      info.componentStack,
+    );
+  }
+
+  render() {
+    if (this.state.error) {
+      // Render a visible red indicator in __DEV__ so it's obvious
+      if (__DEV__) {
+        return (
+          <View style={{ flex: 1, backgroundColor: 'rgba(255,0,0,0.3)', justifyContent: 'center', alignItems: 'center', padding: 20 }}>
+            <Text style={{ color: 'white', fontSize: 14, textAlign: 'center' }}>
+              {`Overlay '${this.props.overlayName}' crashed:\n${this.state.error.message}`}
+            </Text>
+          </View>
+        );
+      }
+      return null;
+    }
+    return this.props.children;
+  }
+}
+
 /** Raw props received from native appProperties (set once per item in configure()). */
 interface RawOverlaySurfaceProps {
   surfaceId?: string;
@@ -47,14 +92,9 @@ interface InnerProps extends RawOverlaySurfaceProps {
 /**
  * Subscribe to a native overlay event, filtered by surfaceId.
  *
- * iOS and Android new arch emit events through different paths:
- * - iOS: _eventEmitterCallback (codegen path) — only the codegen EventEmitter
- *   subscriptions (NativeShortKitModule.onXxx) receive these events.
- * - Android: getJSModule(RCTDeviceEventEmitter).emit() — only
- *   DeviceEventEmitter.addListener() receives these events (codegen
- *   EventEmitter subscriptions do NOT receive them on Android new arch).
- *
- * We branch per platform to use the path that actually delivers events.
+ * Both iOS and Android (new arch) emit events through the codegen
+ * EventEmitter path (mEventEmitterCallback / JSI direct channel).
+ * We subscribe via the codegen emitter method on the TurboModule.
  */
 function useOverlayEvent<T extends { surfaceId: string }>(
   eventName: string,
@@ -66,19 +106,11 @@ function useOverlayEvent<T extends { surfaceId: string }>(
 
     let sub: { remove: () => void } | undefined;
 
-    if (Platform.OS === 'ios') {
-      // iOS new arch: events come through the codegen EventEmitterCallback.
-      // Access the codegen emitter method by name on the TurboModule.
-      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);
-        });
-      }
-    } else {
-      // Android new arch: events come through RCTDeviceEventEmitter.emit().
-      sub = DeviceEventEmitter.addListener(eventName, (e: T) => {
+    // Both platforms: events come through the codegen EventEmitterCallback.
+    // Access the codegen emitter method by name on the TurboModule.
+    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);
       });
@@ -90,13 +122,24 @@ function useOverlayEvent<T extends { surfaceId: string }>(
 
 function ShortKitOverlaySurfaceInner(props: InnerProps) {
   const Component = _overlayRegistry.get(props.overlayName);
-  if (!Component) return null;
+  if (!Component) {
+    console.error(`${SK_OVERLAY_TAG} ShortKitOverlaySurfaceInner: Component NOT FOUND in registry for '${props.overlayName}'. Registered names: [${Array.from(_overlayRegistry.keys()).join(', ')}]`);
+    return null;
+  }
 
-  const item = useMemo(
-    () => (props.item ? deserializeContentItem(props.item) : null),
-    [props.item],
+  const [item, setItem] = useState(() =>
+    props.item ? deserializeContentItem(props.item) : null,
   );
 
+  // Sync item from props when surface is first mounted or remounted via updateInitProps
+  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);
+  }
+
   const sid = props.surfaceId;
 
   // Initialize state from surface properties (set once in configure()).
@@ -141,6 +184,24 @@ 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]);
+
   useOverlayEvent<{ surfaceId: string; isActive: boolean }>(
     'onOverlayActiveChanged', sid,
     (e) => setIsActive(e.isActive),
@@ -175,7 +236,16 @@ function ShortKitOverlaySurfaceInner(props: InnerProps) {
     'onOverlayFeedScrollPhaseChanged', sid,
     (e) => {
       try {
-        setFeedScrollPhase(e.feedScrollPhase ? JSON.parse(e.feedScrollPhase) : null);
+        const next = e.feedScrollPhase ? JSON.parse(e.feedScrollPhase) : null;
+        // Stabilize object reference: only update state if the phase actually
+        // changed. Prevents unnecessary re-renders of memo'd overlay components
+        // that receive feedScrollPhase as a prop (new JSON.parse object !== old).
+        setFeedScrollPhase(prev => {
+          if (prev?.phase === next?.phase && prev?.fromId === next?.fromId) {
+            return prev;
+          }
+          return next;
+        });
       } catch {
         setFeedScrollPhase(null);
       }
@@ -187,19 +257,56 @@ function ShortKitOverlaySurfaceInner(props: InnerProps) {
     (e) => setTime({ current: e.current, duration: e.duration, buffered: e.buffered }),
   );
 
-  if (!item) return null;
+  // Batched full-state sync — replaces 7 individual events on swipe settle.
+  // All setState calls within one handler = one React render (auto-batched).
+  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);
+    setPlaybackRate(e.playbackRate);
+    setCaptionsEnabled(e.captionsEnabled);
+    try {
+      setActiveCue(e.activeCue ? JSON.parse(e.activeCue) : null);
+    } catch {
+      setActiveCue(null);
+    }
+    try {
+      const next = e.feedScrollPhase ? JSON.parse(e.feedScrollPhase) : null;
+      setFeedScrollPhase(prev => {
+        if (prev?.phase === next?.phase && prev?.fromId === next?.fromId) return prev;
+        return next;
+      });
+    } catch {
+      setFeedScrollPhase(null);
+    }
+  });
+
+  if (!item) {
+    return null;
+  }
 
   return (
-    <Component
-      item={item}
-      isActive={isActive}
-      playerState={playerState}
-      time={time}
-      isMuted={isMuted}
-      playbackRate={playbackRate}
-      captionsEnabled={captionsEnabled}
-      activeCue={activeCue}
-      feedScrollPhase={feedScrollPhase}
-    />
+    <OverlayErrorBoundary surfaceId={sid} overlayName={props.overlayName}>
+      <Component
+        item={item}
+        isActive={isActive}
+        playerState={playerState}
+        time={time}
+        isMuted={isMuted}
+        playbackRate={playbackRate}
+        captionsEnabled={captionsEnabled}
+        activeCue={activeCue}
+        feedScrollPhase={feedScrollPhase}
+      />
+    </OverlayErrorBoundary>
   );
 }

package/src/ShortKitPlayer.tsx

@@ -17,11 +17,13 @@ import ShortKitPlayerView from './specs/ShortKitPlayerViewNativeComponent';
 export function ShortKitPlayer(props: ShortKitPlayerProps) {
   const { config, contentItem, active, style } = props;
 
+  const clickAction = config?.clickAction ?? 'feed';
+
   const serializedConfig = useMemo(() => {
     const cfg = config ?? {};
     return JSON.stringify({
       cornerRadius: cfg.cornerRadius ?? 12,
-      clickAction: cfg.clickAction ?? 'feed',
+      clickAction: clickAction,
       autoplay: cfg.autoplay ?? true,
       loop: cfg.loop ?? true,
       muteOnStart: cfg.muteOnStart ?? true,
@@ -31,20 +33,40 @@ export function ShortKitPlayer(props: ShortKitPlayerProps) {
           : { type: 'custom' }
         : 'none',
     });
-  }, [config]);
+  }, [config, clickAction]);
 
   const serializedItem = useMemo(() => {
     if (!contentItem) return undefined;
     return JSON.stringify(contentItem);
   }, [contentItem]);
 
+  // When clickAction is "none", the native view should not participate in
+  // Fabric's JS-side hit testing. Without this, Fabric on Android sees the
+  // native component as the touch target and never routes the touch to a
+  // parent Pressable — even though the native view returns false from
+  // dispatchTouchEvent. iOS doesn't need this because UIKit's responder
+  // chain bubbles unhandled touches automatically.
+  //
+  // "box-none" on the container means the container View itself is
+  // transparent to touches (passes through to parent), but children can
+  // still receive touches if needed. "none" on the native view means it
+  // is fully invisible to hit testing.
+  const nativeTouchPassthrough = clickAction === 'none';
+
   return (
-    <View style={[styles.container, style]}>
+    <View
+      style={[styles.container, style]}
+      pointerEvents={nativeTouchPassthrough ? 'box-none' : 'auto'}
+      onStartShouldSetResponder={() => {
+        return false;
+      }}
+    >
       <ShortKitPlayerView
         style={styles.player}
         config={serializedConfig}
         contentItem={serializedItem}
         active={active}
+        pointerEvents={nativeTouchPassthrough ? 'none' : 'auto'}
       />
     </View>
   );

package/src/ShortKitProvider.tsx

@@ -8,6 +8,7 @@ import type {
   ContentItem,
   FeedConfig,
   FeedFilter,
+  FeedInput,
   PlayerTime,
   PlayerState,
   CaptionTrack,
@@ -420,10 +421,11 @@ export function ShortKitProvider({
     }
   }, []);
 
-  const preloadFeedCmd = useCallback(async (config?: Partial<FeedConfig>): Promise<string> => {
+  const preloadFeedCmd = useCallback(async (config?: Partial<FeedConfig>, items?: FeedInput[]): Promise<string> => {
     if (!NativeShortKitModule) return '';
     const configJSON = config ? serializeFeedConfig(config as FeedConfig) : '{}';
-    return NativeShortKitModule.preloadFeed(configJSON);
+    const itemsJSON = items ? JSON.stringify(items) : null;
+    return NativeShortKitModule.preloadFeed(configJSON, itemsJSON);
   }, []);
 
   // -----------------------------------------------------------------------

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}
+    />
+  );
+}