@shortkitsdk/react-native 0.2.31 → 0.2.33

package/ios/ShortKitWidgetNativeView.swift

@@ -31,11 +31,40 @@ import ShortKitSDK
     /// one is mounted simultaneously.
     @objc public var widgetId: String?
 
+    /// Mirrors `ShortKitWidgetViewController.active`. Hosts use this to
+    /// release the widget's pool tile when it shouldn't be playing
+    /// (e.g. inactive tab, scrolled off-screen). Defaults to `true` so
+    /// existing host integrations behave identically to before.
+    @objc public var active: Bool = true {
+        didSet {
+            guard active != oldValue else { return }
+            widgetVC?.active = active
+        }
+    }
+
+    /// JSON-serialized `FeedInput[]` used to seed the expanded feed when
+    /// a card is tapped and `clickAction == .feed`. See
+    /// `ShortKitWidgetProps.feedItems` in the JS layer for full
+    /// semantics. The parsed list is forwarded to the SDK via
+    /// `ShortKitWidgetViewController.setFeedItems(_:)`.
+    @objc public var feedItems: String? {
+        didSet {
+            guard feedItems != oldValue else { return }
+            applyFeedItems()
+        }
+    }
+
     // MARK: - Child VC
 
     private var widgetVC: ShortKitWidgetViewController?
     private var parsedConfig: WidgetConfig?
     private var parsedItems: [WidgetInput] = []
+    private var parsedFeedItems: [FeedInput] = []
+    /// Parsed feedMask mode pulled out of the serialized config JSON in
+    /// `applyConfig()`. Stored separately because the SDK's
+    /// `ShortKitWidgetViewController.feedMask` is a top-level property,
+    /// not part of `WidgetConfig`.
+    private var parsedFeedMask: FeedMaskMode = .none
 
     // MARK: - Lifecycle
 
@@ -49,7 +78,17 @@ import ShortKitSDK
     public override func willMove(toWindow newWindow: UIWindow?) {
         super.willMove(toWindow: newWindow)
         if newWindow == nil {
-            removeWidgetVC()
+            // The host UIView is leaving the window — typically a
+            // transient detach driven by `react-native-screens` when
+            // a tab blurs or a screen is pushed on top. We must NOT
+            // destroy the widget VC here; doing so causes the user
+            // to see the host's background through the widget on
+            // return, plus a fresh full reload of cards / players /
+            // HLS streams. Suspend instead: detach from the parent
+            // VC hierarchy + pause playback, but keep the VC and
+            // all its loaded state alive so we can re-attach in
+            // `didMoveToWindow` instantly.
+            suspendWidgetVC()
         }
     }
 
@@ -58,18 +97,62 @@ import ShortKitSDK
         widgetVC?.view.frame = bounds
     }
 
+    deinit {
+        // Final teardown when React truly unmounts the bridge UIView.
+        // The instance is going away, so it's safe to release the
+        // child VC's parent-chain references here. Without this, a
+        // suspended widget VC would leak (its parent VC still holds
+        // it as a child until the parent itself is deallocated).
+        destroyWidgetVC()
+    }
+
     // MARK: - VC Containment
 
     private func embedWidgetVCIfNeeded() {
-        guard widgetVC == nil else { return }
-        guard let sdk = ShortKitBridge.shared?.sdk else { return }
         guard let parentVC = findParentViewController() else { return }
 
+        // Re-attach a suspended VC. All loaded state — items, player
+        // pool checkouts, collection-view layout, scroll position —
+        // is preserved across a suspend/resume cycle, so the user
+        // sees the same widget reappear in place rather than a fresh
+        // load. Mirrors `ShortKitPlayerNativeView`.
+        if let vc = widgetVC {
+            parentVC.addChild(vc)
+            vc.view.frame = bounds
+            addSubview(vc.view)
+            vc.didMove(toParent: parentVC)
+            // Re-sync the active prop. While suspended we forced the
+            // VC inactive; restore whatever the JS prop currently says.
+            vc.active = active
+            return
+        }
+
+        // First mount — create a fresh VC.
+        guard let sdk = ShortKitBridge.shared?.sdk else { return }
+
         let widgetConfig = parsedConfig ?? WidgetConfig()
 
         // Pass items at construction so the VC never races the server fetch —
         // analogous to the feed's `feedItems` prop wiring.
         let vc = ShortKitWidgetViewController(shortKit: sdk, config: widgetConfig, items: parsedItems)
+        // Sync the active prop to the freshly-created VC. Without this, a
+        // widget that mounts already with active=false (e.g. on an
+        // unfocused tab) would still go through its initial-load path and
+        // start rotating before the prop change reaches it.
+        vc.active = active
+        // Forward the optional expanded-feed seed list. Set before view
+        // load so it's available the first time `openFeed()` runs —
+        // same ordering rationale as the player's bridge.
+        if !parsedFeedItems.isEmpty {
+            vc.setFeedItems(parsedFeedItems)
+        }
+        // Forward the optional host-supplied feed mask. The SDK's
+        // `feedMask` lives as a top-level VC property (not in
+        // WidgetConfig), so it has to be set after construction. The
+        // factory closure inside the mode is invoked by the SDK each
+        // time `openFeed()` fires — so each expansion gets its own
+        // FeedMaskHostView instance.
+        vc.feedMask = parsedFeedMask
         self.widgetVC = vc
 
         // Wire host-handleable card-tap callback. When the JS wrapper has
@@ -96,7 +179,25 @@ import ShortKitSDK
         vc.didMove(toParent: parentVC)
     }
 
-    private func removeWidgetVC() {
+    /// Detach the widget VC from the parent VC + view hierarchy
+    /// without destroying it. Called when the bridge UIView leaves
+    /// the window (typically a `react-native-screens` tab blur).
+    /// All of the widget's loaded state is preserved so the
+    /// re-attach in `embedWidgetVCIfNeeded` can be instant. Pause
+    /// playback so the SDK pool tiles aren't held while suspended.
+    private func suspendWidgetVC() {
+        guard let vc = widgetVC else { return }
+        vc.active = false
+        vc.willMove(toParent: nil)
+        vc.view.removeFromSuperview()
+        vc.removeFromParent()
+        // Keep widgetVC reference — re-attached in embedWidgetVCIfNeeded.
+    }
+
+    /// Full teardown — called from `deinit` when React unmounts the
+    /// native view, and from `applyConfig` when the config string
+    /// changes and we need to rebuild the VC from scratch.
+    private func destroyWidgetVC() {
         guard let vc = widgetVC else { return }
         vc.willMove(toParent: nil)
         vc.view.removeFromSuperview()
@@ -109,12 +210,37 @@ import ShortKitSDK
     private func applyConfig() {
         guard let json = config else { return }
         parsedConfig = Self.parseWidgetConfig(json)
+        // FeedMask is stored as a sibling field in the serialized
+        // config JSON; extract it here so it's available when the VC
+        // gets (re)constructed in embedWidgetVCIfNeeded.
+        parsedFeedMask = Self.extractFeedMask(json)
         if widgetVC != nil {
-            removeWidgetVC()
+            destroyWidgetVC()
             embedWidgetVCIfNeeded()
         }
     }
 
+    /// Pulls the `feedMask` field out of the raw config JSON without
+    /// re-parsing the rest of `WidgetConfig`. Returns `.none` if the
+    /// JSON is malformed or omits `feedMask`. Mirrors how the
+    /// equivalent value is read on `ShortKitPlayerNativeView`.
+    private static func extractFeedMask(_ json: String) -> FeedMaskMode {
+        guard let data = json.data(using: .utf8),
+              let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+            return .none
+        }
+        // The serializer emits feedMask either as the string "none" or
+        // as a {type, name} object — both arrive nested as a sub-JSON
+        // value (not stringified again, unlike feedConfig).
+        if let mask = obj["feedMask"] {
+            if let data = try? JSONSerialization.data(withJSONObject: mask),
+               let json = String(data: data, encoding: .utf8) {
+                return ShortKitBridge.parseFeedMask(json)
+            }
+        }
+        return .none
+    }
+
     private func applyItems() {
         parsedItems = items.flatMap { Self.parseWidgetInputs($0) } ?? []
         // Post-mount updates: push items through the public API.
@@ -123,6 +249,18 @@ import ShortKitSDK
         }
     }
 
+    private func applyFeedItems() {
+        // Empty / nil JSON ⇒ clear the host seed.
+        guard let json = feedItems,
+              let items = ShortKitBridge.parseFeedInputs(json) else {
+            parsedFeedItems = []
+            widgetVC?.setFeedItems([])
+            return
+        }
+        parsedFeedItems = items
+        widgetVC?.setFeedItems(items)
+    }
+
     // MARK: - Parsing
 
     private static func parseWidgetConfig(_ json: String) -> WidgetConfig {
@@ -138,6 +276,13 @@ import ShortKitSDK
         let muteOnStart = obj["muteOnStart"] as? Bool ?? true
         let loop = obj["loop"] as? Bool ?? true
         let rotationInterval = obj["rotationInterval"] as? TimeInterval ?? 10000
+        let previewDuration = obj["previewDuration"] as? TimeInterval ?? 5
+        let playbackMode: WidgetPlaybackMode
+        switch obj["playbackMode"] as? String {
+        case "allVisibleSimultaneous": playbackMode = .allVisibleSimultaneous
+        case "singleVisibleRotating": playbackMode = .singleVisibleRotating
+        default: playbackMode = .singleVisibleRotating
+        }
 
         let clickAction: PlayerClickAction
         switch obj["clickAction"] as? String {
@@ -180,7 +325,9 @@ import ShortKitSDK
             clickAction: clickAction,
             cardOverlay: overlayMode,
             feedConfig: feedConfig,
-            filter: filter
+            filter: filter,
+            playbackMode: playbackMode,
+            previewDuration: previewDuration
         )
     }
 

package/ios/ShortKitWidgetNativeViewManager.mm

@@ -24,5 +24,7 @@ RCT_EXPORT_MODULE(ShortKitWidgetView)
 RCT_EXPORT_VIEW_PROPERTY(config, NSString)
 RCT_EXPORT_VIEW_PROPERTY(items, NSString)
 RCT_EXPORT_VIEW_PROPERTY(widgetId, NSString)
+RCT_EXPORT_VIEW_PROPERTY(active, BOOL)
+RCT_EXPORT_VIEW_PROPERTY(feedItems, NSString)
 
 @end

package/package.json

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

package/src/ShortKitCommands.ts

@@ -32,7 +32,17 @@ export const ShortKitCommands = {
     NativeShortKitModule?.prefetchStoryboard(playbackId),
   getStoryboardData: (playbackId: string): Promise<string | null> =>
     NativeShortKitModule?.getStoryboardData(playbackId) ?? Promise.resolve(null),
-  downloadVideo: (itemId: string, mode: 'nonInterruptive' | 'interruptive' = 'nonInterruptive'): Promise<string> =>
-    NativeShortKitModule?.downloadVideo(itemId, mode) ?? Promise.reject(new Error('ShortKit not initialized')),
+  downloadVideo: (
+    itemId: string,
+    options?: {
+      mode?: 'interruptive' | 'nonInterruptive';
+      overlayMode?: 'none' | 'static' | 'deterministic';
+    }
+  ): Promise<string> => {
+    const mode = options?.mode ?? 'nonInterruptive';
+    const overlayMode = options?.overlayMode ?? 'none';
+    return NativeShortKitModule?.downloadVideo(itemId, mode, overlayMode)
+      ?? Promise.reject(new Error('ShortKit not initialized'));
+  },
   cancelDownload: () => NativeShortKitModule?.cancelDownload(),
 } as const;

package/src/ShortKitContext.ts

@@ -55,7 +55,13 @@ export interface ShortKitContextValue {
 
   // Download
   downloadState: DownloadState;
-  downloadVideo: (itemId: string, mode?: 'nonInterruptive' | 'interruptive') => Promise<string>;
+  downloadVideo: (
+    itemId: string,
+    options?: {
+      mode?: 'interruptive' | 'nonInterruptive';
+      overlayMode?: 'none' | 'static' | 'deterministic';
+    }
+  ) => Promise<string>;
   cancelDownload: () => void;
 }
 

package/src/ShortKitFeedMaskSurface.tsx

@@ -0,0 +1,132 @@
+import React from 'react';
+import { AppRegistry, View, Text } from 'react-native';
+import type { FeedMaskProps, ContentItem } from './types';
+import { deserializeContentItem } from './serialization';
+
+const SK_MASK_TAG = '[ShortKit:FeedMaskSurface]';
+
+// Named registry — supports different mask components per host site.
+const _maskRegistry = new Map<string, React.ComponentType<FeedMaskProps>>();
+
+/**
+ * Register a named feed-mask component for rendering around the
+ * expanded feed. Called by `<ShortKitPlayer>` / `<ShortKitWidget>` on
+ * mount via `useLayoutEffect` whenever `config.feedMask` is set with
+ * `type: 'custom'`. Idempotent — registering the same name twice is
+ * a no-op.
+ */
+export function registerFeedMaskComponent(
+  name: string,
+  component: React.ComponentType<FeedMaskProps>,
+) {
+  if (_maskRegistry.has(name)) {
+    return;
+  }
+  _maskRegistry.set(name, component);
+
+  const moduleName = `ShortKitFeedMask_${name}`;
+  AppRegistry.registerComponent(moduleName, () => {
+    return function NamedFeedMaskSurface(props: RawFeedMaskSurfaceProps) {
+      return <ShortKitFeedMaskSurfaceInner {...props} maskName={name} />;
+    };
+  });
+}
+
+/**
+ * Error boundary mirrors the overlay-surface boundary so a crash in
+ * the mask component doesn't bring down the SDK's modal presentation.
+ */
+class FeedMaskErrorBoundary extends React.Component<
+  { maskName: 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_MASK_TAG} CRASH in mask '${this.props.maskName}':`,
+      error.message,
+      '\nComponent stack:',
+      info.componentStack,
+    );
+  }
+
+  render() {
+    if (this.state.error) {
+      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' }}>
+              {`Mask '${this.props.maskName}' crashed:\n${this.state.error.message}`}
+            </Text>
+          </View>
+        );
+      }
+      // Production fallback: render an empty view so the SDK still
+      // has a usable feedRegion via the embed slot the host inserts
+      // (which they no longer do, since the mask crashed). The SDK's
+      // placeholder UIView keeps the feed visible.
+      return null;
+    }
+    return this.props.children;
+  }
+}
+
+/**
+ * Raw props pushed in by the native bridge (`FeedMaskHostView`)
+ * via `SKFabricSurfaceWrapper.setProperties`. Item arrives serialized
+ * as a JSON string; everything else is a primitive.
+ */
+interface RawFeedMaskSurfaceProps {
+  /** Serialized `ContentItem`. JSON-stringified by the bridge. */
+  item?: string;
+  /** Active item's index in the feed, when known. */
+  activeIndex?: number;
+  /** Total feed length, when known. */
+  totalCount?: number;
+}
+
+interface InnerProps extends RawFeedMaskSurfaceProps {
+  maskName: string;
+}
+
+function ShortKitFeedMaskSurfaceInner(props: InnerProps) {
+  const Component = _maskRegistry.get(props.maskName);
+  if (!Component) {
+    if (__DEV__) {
+      console.warn(
+        `${SK_MASK_TAG} mask '${props.maskName}' is not registered — did you set config.feedMask?`,
+      );
+    }
+    return null;
+  }
+
+  let item: ContentItem | null = null;
+  if (props.item) {
+    try {
+      item = deserializeContentItem(props.item);
+    } catch (e) {
+      console.warn(`${SK_MASK_TAG} failed to deserialize item:`, e);
+    }
+  }
+
+  // No item to render around → render nothing yet. The SDK will push
+  // a configure() with the active item shortly after expansion.
+  if (!item) {
+    return null;
+  }
+
+  return (
+    <FeedMaskErrorBoundary maskName={props.maskName}>
+      <Component
+        item={item}
+        activeIndex={props.activeIndex}
+        totalCount={props.totalCount}
+      />
+    </FeedMaskErrorBoundary>
+  );
+}

package/src/ShortKitPlayer.tsx

@@ -6,6 +6,7 @@ import { serializePlayerConfig } from './serialization';
 import { registerOverlayComponent } from './ShortKitOverlaySurface';
 import { registerCarouselOverlayComponent } from './ShortKitCarouselOverlaySurface';
 import { registerVideoCarouselOverlayComponent } from './ShortKitVideoCarouselOverlaySurface';
+import { registerFeedMaskComponent } from './ShortKitFeedMaskSurface';
 
 /**
  * Single-video player component. Displays one video with thumbnail fallback
@@ -19,7 +20,7 @@ import { registerVideoCarouselOverlayComponent } from './ShortKitVideoCarouselOv
  * app's responsibility.
  */
 export function ShortKitPlayer(props: ShortKitPlayerProps) {
-  const { config, contentItem, active, style } = props;
+  const { config, contentItem, active, feedItems, style } = props;
 
   const clickAction = config?.clickAction ?? 'feed';
 
@@ -39,7 +40,10 @@ export function ShortKitPlayer(props: ShortKitPlayerProps) {
         registerVideoCarouselOverlayComponent(fc.videoCarouselOverlay.name, fc.videoCarouselOverlay.component);
       }
     }
-  }, [config?.overlay, config?.feedConfig]);
+    if (config?.feedMask && config.feedMask !== 'none') {
+      registerFeedMaskComponent(config.feedMask.name, config.feedMask.component);
+    }
+  }, [config?.overlay, config?.feedConfig, config?.feedMask]);
 
   const serializedConfig = useMemo(() => {
     return serializePlayerConfig(config ?? {});
@@ -50,6 +54,14 @@ export function ShortKitPlayer(props: ShortKitPlayerProps) {
     return JSON.stringify(contentItem);
   }, [contentItem]);
 
+  // Serialize the optional expanded-feed seed list. Empty/undefined ⇒
+  // pass `undefined` so the native side falls through to the legacy
+  // single-item behavior (preload built from `self.items`).
+  const serializedFeedItems = useMemo(() => {
+    if (!feedItems || feedItems.length === 0) return undefined;
+    return JSON.stringify(feedItems);
+  }, [feedItems]);
+
   // 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
@@ -76,6 +88,7 @@ export function ShortKitPlayer(props: ShortKitPlayerProps) {
         config={serializedConfig}
         contentItem={serializedItem}
         active={active}
+        feedItems={serializedFeedItems}
         pointerEvents={nativeTouchPassthrough ? 'none' : 'auto'}
       />
     </View>

package/src/ShortKitWidget.tsx

@@ -8,6 +8,7 @@ import { serializeWidgetConfig } from './serialization';
 import { registerOverlayComponent } from './ShortKitOverlaySurface';
 import { registerCarouselOverlayComponent } from './ShortKitCarouselOverlaySurface';
 import { registerVideoCarouselOverlayComponent } from './ShortKitVideoCarouselOverlaySurface';
+import { registerFeedMaskComponent } from './ShortKitFeedMaskSurface';
 
 // Local UUID generator. We don't pull in a runtime dep just for this; a
 // timestamp + random suffix is more than unique enough to disambiguate
@@ -23,7 +24,7 @@ function generateWidgetId(): string {
  * Must be rendered inside a `<ShortKitProvider>`.
  */
 export function ShortKitWidget(props: ShortKitWidgetProps) {
-  const { config, items, onCardTap, style } = props;
+  const { config, items, onCardTap, active, feedItems, style } = props;
 
   const isInitialized = useContext(ShortKitInitContext);
   if (!isInitialized) {
@@ -69,7 +70,10 @@ export function ShortKitWidget(props: ShortKitWidgetProps) {
         registerVideoCarouselOverlayComponent(fc.videoCarouselOverlay.name, fc.videoCarouselOverlay.component);
       }
     }
-  }, [config?.overlay, config?.feedConfig]);
+    if (config?.feedMask && config.feedMask !== 'none') {
+      registerFeedMaskComponent(config.feedMask.name, config.feedMask.component);
+    }
+  }, [config?.overlay, config?.feedConfig, config?.feedMask]);
 
   // Subscribe to the global widget-card-tap event, filtered to this
   // instance's widgetId.
@@ -93,6 +97,14 @@ export function ShortKitWidget(props: ShortKitWidgetProps) {
     return JSON.stringify(items);
   }, [items]);
 
+  // Serialize the optional expanded-feed seed list. Empty/undefined ⇒
+  // pass `undefined` so the native side falls through to the legacy
+  // behavior (preload built from `self.items` — the carousel cards).
+  const serializedFeedItems = useMemo(() => {
+    if (!feedItems || feedItems.length === 0) return undefined;
+    return JSON.stringify(feedItems);
+  }, [feedItems]);
+
   return (
     <View style={[styles.container, style]}>
       <ShortKitWidgetView
@@ -100,6 +112,8 @@ export function ShortKitWidget(props: ShortKitWidgetProps) {
         config={serializedConfig}
         items={serializedItems}
         widgetId={widgetId}
+        active={active}
+        feedItems={serializedFeedItems}
       />
     </View>
   );

package/src/index.ts

@@ -52,4 +52,11 @@ export { default as NativeShortKitModule } from './specs/NativeShortKitModule';
 export { registerOverlayComponent } from './ShortKitOverlaySurface';
 export { registerCarouselOverlayComponent } from './ShortKitCarouselOverlaySurface';
 export { registerVideoCarouselOverlayComponent } from './ShortKitVideoCarouselOverlaySurface';
-export type { OverlayProps, CarouselOverlayProps, VideoCarouselOverlayProps } from './types';
+export { registerFeedMaskComponent } from './ShortKitFeedMaskSurface';
+export type {
+  OverlayProps,
+  CarouselOverlayProps,
+  VideoCarouselOverlayProps,
+  FeedMaskProps,
+  FeedMaskConfig,
+} from './types';

package/src/serialization.ts

@@ -2,6 +2,7 @@ import type {
   FeedConfig,
   ContentItem,
   FeedInput,
+  FeedMaskConfig,
   PlayerState,
   PlayerTime,
   WidgetConfig,
@@ -139,6 +140,16 @@ function serializeOverlay(overlay: OverlayConfig | undefined): string | { type:
   return { type: 'custom', name: overlay.name };
 }
 
+/**
+ * FeedMask serialization mirrors the overlay path: only the name
+ * crosses the bridge — the JS-side registry maps the name back to
+ * the React component at mount time inside `FeedMaskHostView`.
+ */
+function serializeFeedMask(mask: FeedMaskConfig | undefined): string | { type: 'custom'; name: string } {
+  if (!mask || mask === 'none') return 'none';
+  return { type: 'custom', name: mask.name };
+}
+
 export function serializeWidgetConfig(config: WidgetConfig): string {
   const cfg = config ?? {};
   return JSON.stringify({
@@ -153,6 +164,9 @@ export function serializeWidgetConfig(config: WidgetConfig): string {
     overlay: serializeOverlay(cfg.overlay),
     filter: cfg.filter ? JSON.stringify(cfg.filter) : undefined,
     feedConfig: cfg.feedConfig ? serializeFeedConfig(cfg.feedConfig) : undefined,
+    feedMask: serializeFeedMask(cfg.feedMask),
+    playbackMode: cfg.playbackMode ?? 'singleVisibleRotating',
+    previewDuration: cfg.previewDuration ?? 5,
   });
 }
 
@@ -166,5 +180,6 @@ export function serializePlayerConfig(config: PlayerConfig): string {
     muteOnStart: cfg.muteOnStart ?? true,
     overlay: serializeOverlay(cfg.overlay),
     feedConfig: cfg.feedConfig ? serializeFeedConfig(cfg.feedConfig) : undefined,
+    feedMask: serializeFeedMask(cfg.feedMask),
   });
 }

package/src/specs/NativeShortKitModule.ts

@@ -140,6 +140,7 @@ type DownloadStartedEvent = Readonly<{
 type DownloadProgressEvent = Readonly<{
   itemId: string;
   progress: number;
+  phase: 'downloading' | 'compositing' | 'finalizing';
 }>;
 
 type DownloadCompletedEvent = Readonly<{
@@ -306,7 +307,7 @@ export interface Spec extends TurboModule {
   getStoryboardData(playbackId: string): Promise<string>;
 
   // --- Download ---
-  downloadVideo(itemId: string, mode: string): Promise<string>;
+  downloadVideo(itemId: string, mode: string, overlayMode: string): Promise<string>;
   cancelDownload(): void;
 
   // --- Carousel accessors ---

package/src/specs/ShortKitPlayerViewNativeComponent.ts

@@ -5,6 +5,13 @@ export interface NativeProps extends ViewProps {
   config: string;
   contentItem?: string;
   active?: boolean;
+  /**
+   * Serialized JSON of the host-provided expanded-feed seed list.
+   * See `ShortKitPlayerProps.feedItems` for semantics. Sent as a
+   * string to keep the prop primitive (Codegen-friendly) — the
+   * native bridge parses + hydrates into `[ContentItem]`.
+   */
+  feedItems?: string;
 }
 
 export default codegenNativeComponent<NativeProps>(

package/src/specs/ShortKitWidgetViewNativeComponent.ts

@@ -10,6 +10,21 @@ export interface NativeProps extends ViewProps {
    * `<ShortKitWidget>` when multiple widgets are mounted.
    */
   widgetId?: string;
+  /**
+   * Whether the widget is currently allowed to play. Defaults to true on
+   * the native side. Hosts use this to release the widget's pool tile
+   * when it shouldn't be playing (inactive tab, scrolled off-screen,
+   * etc.) so other surfaces can claim the tile cleanly. Mirrors
+   * `<ShortKitFeed>`'s `active` prop.
+   */
+  active?: boolean;
+  /**
+   * Serialized JSON of the host-provided expanded-feed seed list.
+   * See `ShortKitWidgetProps.feedItems` for semantics. Sent as a
+   * string to keep the prop primitive (Codegen-friendly) — the
+   * native bridge parses + hydrates into `[FeedInput]`.
+   */
+  feedItems?: string;
 }
 
 export default codegenNativeComponent<NativeProps>(