@shortkitsdk/react-native 0.2.32 → 0.2.33

package/package.json

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

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/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>(

package/src/types.ts

@@ -52,6 +52,35 @@ export type VideoCarouselOverlayConfig =
   | 'none'
   | { type: 'custom'; name: string; component: React.ComponentType<VideoCarouselOverlayProps> };
 
+/**
+ * Custom feed mask config for `<ShortKitPlayer>` / `<ShortKitWidget>`.
+ *
+ * When set to `{type: 'custom', name, component}`, the SDK presents the
+ * expanded feed embedded inside the host-supplied React component rather
+ * than full-screen. The mask renders chrome (e.g. a footer pill) AROUND
+ * the feed; the feed itself occupies the `<ShortKitFeedRegion>` placeholder
+ * the host puts somewhere in the mask's tree.
+ *
+ * iOS only. On Android the prop is currently a no-op.
+ */
+export type FeedMaskConfig =
+  | 'none'
+  | { type: 'custom'; name: string; component: React.ComponentType<FeedMaskProps> };
+
+/**
+ * Props passed to the host-supplied feed mask component as the user pages
+ * through the expanded feed. Mirrors a subset of `OverlayProps` —
+ * additional fields (playback state, time, etc.) can be added later.
+ */
+export interface FeedMaskProps {
+  /** The currently-active feed item. Re-renders the mask when paging. */
+  item: ContentItem;
+  /** Active item's index in the feed, when known. */
+  activeIndex?: number;
+  /** Total feed length, when known (paginated feeds may grow). */
+  totalCount?: number;
+}
+
 // --- Data Models ---
 
 export interface ContentItem {
@@ -438,6 +467,12 @@ export interface PlayerConfig {
   muteOnStart?: boolean;
   overlay?: OverlayConfig;
   feedConfig?: FeedConfig;
+  /**
+   * Optional feed mask. When `{type: 'custom', ...}`, the SDK embeds the
+   * expanded feed inside the host's React component instead of presenting
+   * full-screen. iOS only. See `FeedMaskConfig` for full semantics.
+   */
+  feedMask?: FeedMaskConfig;
 }
 
 // --- Widget Config ---
@@ -454,6 +489,24 @@ export interface WidgetConfig {
   overlay?: OverlayConfig;
   filter?: FeedFilter;
   feedConfig?: FeedConfig;
+  /**
+   * Optional feed mask, same shape as `PlayerConfig.feedMask`. iOS only.
+   */
+  feedMask?: FeedMaskConfig;
+  /**
+   * How the widget schedules preview playback across cells.
+   * - `'singleVisibleRotating'` (default): one visible card plays at a
+   *   time using an HLS Instant Clip; advances to the next visible card
+   *   on natural EOS, wrapping at the end. Off-screen cards never play.
+   * - `'allVisibleSimultaneous'`: every visible card plays simultaneously,
+   *   hard-capped at 3. Each card loops its own preview in place.
+   */
+  playbackMode?: 'singleVisibleRotating' | 'allVisibleSimultaneous';
+  /**
+   * Length of the looping preview window in seconds. Used to construct the
+   * Mux Instant Clip URL for each card. Defaults to 5.
+   */
+  previewDuration?: number;
 }
 
 /**
@@ -473,6 +526,22 @@ export interface ShortKitPlayerProps {
    *  returns to thumbnail-only mode without tearing down the view. Defaults to
    *  the value of `config.autoplay` (which itself defaults to `true`). */
   active?: boolean;
+  /**
+   * Optional list of items used to seed the expanded feed when the user
+   * taps the player and `config.clickAction === 'feed'`. The inline
+   * player's own `contentItem` is automatically prepended (deduped by
+   * playback ID), so the modal-zoom transition lands on the inline
+   * clip and the host's items follow.
+   *
+   * Combine with `config.feedConfig.feedSource`:
+   *   - `'algorithmic'` (default) → expanded feed plays the seeded
+   *     items, then continues paginating via `/v1/feed`.
+   *   - `'custom'` → expanded feed plays only the seeded items and
+   *     stops at the end (closed list).
+   *
+   * Has no effect when `clickAction !== 'feed'`.
+   */
+  feedItems?: FeedInput[];
   style?: ViewStyle;
   onTap?: () => void;
 }
@@ -499,6 +568,32 @@ export interface ShortKitWidgetProps {
    * regardless (per-cell mute toggle runs alongside `onCardTap`).
    */
   onCardTap?: (playbackId: string, index: number) => void;
+  /**
+   * Whether the widget is currently allowed to play. Defaults to `true`.
+   * When `false`, the widget stops its rotation timer and deactivates
+   * whichever card was active — releasing its tile back to the SDK
+   * player pool. Use this for viewport-aware playback orchestration
+   * (e.g. tab-focus gating: `active={isFocused}`). Mirrors
+   * `<ShortKitFeed>`'s same-named prop.
+   */
+  active?: boolean;
+  /**
+   * Optional list of items used to seed the expanded feed when the user
+   * taps a card and `config.clickAction === 'feed'`. The widget's own
+   * `items` (the carousel cards) are automatically prepended (deduped
+   * by playback ID), so the modal-zoom transition lands on the tapped
+   * clip and the host's items follow.
+   *
+   * Combine with `config.feedConfig.feedSource`:
+   *   - `'algorithmic'` (default) → expanded feed plays the seeded
+   *     items, then continues paginating via `/v1/feed`.
+   *   - `'custom'` → expanded feed plays only the seeded items and
+   *     stops at the end (closed list).
+   *
+   * Has no effect when `clickAction !== 'feed'`. Mirrors the
+   * `feedItems` prop on `<ShortKitPlayer>`.
+   */
+  feedItems?: FeedInput[];
   style?: ViewStyle;
 }