@xhub-reels/sdk 0.2.11 → 0.2.13

package/dist/index.d.cts

@@ -443,6 +443,7 @@ declare class PlayerEngine {
     private circuitResetTimer;
     private watchTimeInterval;
     private lastStatus;
+    private _destroyed;
     constructor(config?: PlayerConfig, analytics?: IAnalytics, logger?: ILogger);
     /**
      * Load a video and prepare for playback.
@@ -498,11 +499,14 @@ declare class FeedManager {
     private inFlightRequests;
     /** LRU tracking: itemId → lastAccessTime */
     private accessOrder;
+    /** Idempotency guard for destroy() */
+    private _destroyed;
     /** Prefetch cache — instance-scoped (not static) */
     private prefetchCache;
     constructor(dataSource: IDataSource, config?: FeedConfig, logger?: ILogger);
     getDataSource(): IDataSource;
     setDataSource(dataSource: IDataSource, reset?: boolean): void;
+    setInitialItems(items: ContentItem[]): void;
     prefetch(ttlMs?: number): Promise<void>;
     hasPrefetchCache(): boolean;
     clearPrefetchCache(): void;
@@ -556,6 +560,8 @@ declare class OptimisticManager {
     private likeDebounceTimers;
     /** Pending like direction: contentId → final intended state */
     private pendingLikeState;
+    /** Idempotency guard for destroy() */
+    private _destroyed;
     constructor(interaction: Partial<IInteraction>, logger?: ILogger);
     /**
      * Debounced like toggle — prevents rapid API spam on double-tap.
@@ -626,6 +632,7 @@ declare class ResourceGovernor {
     private readonly logger?;
     private focusDebounceTimer;
     private networkUnsubscribe?;
+    private _destroyed;
     constructor(config?: ResourceConfig, videoLoader?: IVideoLoader, network?: INetworkAdapter, logger?: ILogger);
     activate(): Promise<void>;
     deactivate(): void;
@@ -658,6 +665,103 @@ declare class ResourceGovernor {
     private recalculate;
 }
 
+/**
+ * NavigationManager — Owns the open/close lifecycle of the SDK reels viewer.
+ *
+ * Framework-agnostic class (zustand/vanilla) mirroring FeedManager /
+ * ResourceGovernor / PlayerEngine conventions. It is the single source of
+ * truth for "is the reels viewer open, and at which index".
+ *
+ * WHY THIS EXISTS:
+ * Previously the host app owned the modal entirely (via onThumbnailClick).
+ * That meant the SDK could not warm a video before the host mounted
+ * <ReelsFeed>, producing the "poster stuck ~3s" stall. By owning the
+ * open/close phase, the SDK can:
+ *   1. mount <ReelsFeed> early (hidden behind the animating container),
+ *   2. prewarm the focused video DURING the open animation,
+ *   3. reveal an already-decoded first frame → no poster stall.
+ *
+ * PHASE MODEL (state machine):
+ *   closed  → opening : open(index) called (e.g. from a thumbnail tap)
+ *   opening → open    : ReelsModal finished its enter animation
+ *   open    → closing : close() called
+ *   closing → closed  : ReelsModal finished its exit animation
+ *
+ * Invalid transitions are dropped (see isValidNavTransition). This mirrors
+ * the PlayerEngine state-machine discipline used elsewhere in the SDK.
+ *
+ * The component layer (ReelsModal) drives the animation timing and calls
+ * `setPhase('open')` / `setPhase('closed')` when its Web Animations API
+ * transitions finish. NavigationManager itself holds no timers tied to
+ * animation — it only holds a safety fallback timer so a missing/janky
+ * animationend can never strand the phase forever.
+ */
+
+type NavigationPhase = 'closed' | 'opening' | 'open' | 'closing';
+interface NavigationState {
+    /** Current lifecycle phase of the reels viewer. */
+    phase: NavigationPhase;
+    /**
+     * Index the viewer was opened at. Held through the whole open lifecycle
+     * (opening → open → closing) and cleared back to null only once fully
+     * closed. ReelsModal mounts <ReelsFeed> whenever this is non-null so the
+     * feed can warm during `opening`.
+     */
+    openIndex: number | null;
+}
+interface NavigationConfig {
+    /**
+     * Safety fallback (ms). If the component never reports its enter/exit
+     * animation finished, the manager force-advances the phase so the viewer
+     * can never get stuck in `opening`/`closing`. Set generously above the
+     * real animation duration. Default: 1200.
+     */
+    phaseTimeoutMs?: number;
+}
+declare const DEFAULT_NAVIGATION_CONFIG: Required<NavigationConfig>;
+declare function isValidNavTransition(from: NavigationPhase, to: NavigationPhase): boolean;
+declare class NavigationManager {
+    readonly store: StoreApi<NavigationState>;
+    private readonly config;
+    private readonly logger?;
+    /** Fallback timer guarding against a missing animationend report. */
+    private phaseTimer;
+    private _destroyed;
+    constructor(config?: NavigationConfig, logger?: ILogger);
+    /**
+     * Open the reels viewer at `index`. Safe to call from a thumbnail click
+     * handler — it transitions into `opening`, at which point ReelsModal mounts
+     * <ReelsFeed> hidden and begins prewarming.
+     *
+     * Calling open() while already open/opening just retargets the index
+     * (e.g. user taps a different thumbnail before the animation settles).
+     */
+    open(index: number): void;
+    /**
+     * Begin closing the viewer. ReelsModal animates out then calls
+     * `setPhase('closed')`. Idempotent if already closing/closed.
+     */
+    close(): void;
+    /**
+     * Report an animation-driven phase change from the component layer.
+     * Invalid transitions are dropped. When reaching `closed`, openIndex is
+     * cleared so <ReelsFeed> unmounts.
+     */
+    setPhase(next: NavigationPhase): void;
+    getPhase(): NavigationPhase;
+    getOpenIndex(): number | null;
+    isOpen(): boolean;
+    /** Whether <ReelsFeed> should be mounted (any non-closed phase). */
+    shouldMount(): boolean;
+    destroy(): void;
+    /**
+     * Apply a guarded phase transition. Returns true if it was applied.
+     * Manages the fallback timer for transient phases (opening/closing).
+     */
+    private transition;
+    private clearPhaseTimer;
+}
+
 /**
  * Player State Machine — Guarded transitions
  *
@@ -776,15 +880,20 @@ interface SDKContextValue {
     playerEngine: PlayerEngine;
     resourceGovernor: ResourceGovernor;
     optimisticManager: OptimisticManager;
+    navigationManager: NavigationManager;
     adapters: Required<Omit<SDKAdapters, 'dataSource'>> & Pick<SDKAdapters, 'dataSource'>;
 }
 interface ReelsProviderProps {
     children: ReactNode;
     adapters: SDKAdapters;
+    /** Seed initial items into feedManager */
+    initialItems?: ContentItem[];
     /** Enable verbose logging (default: false) */
     debug?: boolean;
+    /** Config for the owned reels viewer open/close lifecycle (used by ReelsModal) */
+    navigationConfig?: NavigationConfig;
 }
-declare function ReelsProvider({ children, adapters, debug }: ReelsProviderProps): react_jsx_runtime.JSX.Element;
+declare function ReelsProvider({ children, adapters, initialItems, debug, navigationConfig, }: ReelsProviderProps): react_jsx_runtime.JSX.Element;
 declare function useSDK(): SDKContextValue;
 
 declare function ReelsFeed({ renderOverlay, renderActions, renderPauseAction, renderLoading, renderEmpty, renderError: _renderError, showFps, loadMoreThreshold, onSlotChange, gestureConfig, snapConfig, initialMuted, onAutoplayBlocked, }: ReelsFeedProps): string | number | bigint | boolean | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<react.ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null | undefined;
@@ -809,12 +918,97 @@ interface ReelsFeedThumbnailProps {
     wrap?: boolean;
     /** Enable click → update focused index on ReelsProvider before host reacts. Default: true. */
     setFocusOnClick?: boolean;
-    /** Prefetch metadata for this slot on pointer enter. Off by default. */
+    /**
+     * Open the SDK-owned <ReelsModal> on click (calls NavigationManager.open).
+     * This is the recommended path — the SDK controls modal timing and prewarms
+     * the video during the open animation, eliminating the "poster stuck ~3s"
+     * stall. Requires a <ReelsModal> mounted under the same <ReelsProvider>.
+     *
+     * Leave false (default) to keep the headless behaviour where the host owns
+     * the modal and reacts via `onThumbnailClick`.
+     *
+     * @default false
+     */
+    openOnClick?: boolean;
+    /**
+     * Prefetch HLS metadata for this slot on pointer enter (desktop hover).
+     * Useless on mobile WebView (no hover) — use `prewarmOnClick` there.
+     * Off by default.
+     */
     prefetchOnHover?: boolean;
+    /**
+     * Prefetch HLS metadata for the tapped slot synchronously on click, inside
+     * the tap gesture. This is the mobile-friendly counterpart to
+     * `prefetchOnHover` and starts buffering the instant the user taps — before
+     * any modal mounts. Recommended for mobile WebView. Default: true.
+     */
+    prewarmOnClick?: boolean;
     /** Key override — useful when host renders multiple lists from the same feed. */
     getKey?: (item: ContentItem, index: number) => string;
 }
-declare function ReelsFeedThumbnail({ renderThumbnail, onThumbnailClick, renderLoading, renderEmpty, renderError, className, wrap, setFocusOnClick, prefetchOnHover, getKey, }: ReelsFeedThumbnailProps): react_jsx_runtime.JSX.Element | null;
+declare function ReelsFeedThumbnail({ renderThumbnail, onThumbnailClick, renderLoading, renderEmpty, renderError, className, wrap, setFocusOnClick, openOnClick, prefetchOnHover, prewarmOnClick, getKey, }: ReelsFeedThumbnailProps): react_jsx_runtime.JSX.Element | null;
+
+interface ReelsModalAnimationConfig {
+    /** Enter/exit duration in ms (default: 300) */
+    duration?: number;
+    /** CSS easing (default: 'cubic-bezier(0.22, 1, 0.36, 1)') */
+    easing?: string;
+    /**
+     * Panel travel direction:
+     * - 'up'   (default): slides up from the bottom edge (bottom-sheet drawer)
+     * - 'down': slides down from the top edge
+     * - 'fade': no translate, opacity only
+     */
+    direction?: 'up' | 'down' | 'fade';
+}
+/** State handed to render-prop customisation callbacks. */
+interface ReelsModalRenderState {
+    phase: NavigationPhase;
+    openIndex: number | null;
+    /** Begin closing the viewer (runs the exit animation). */
+    close: () => void;
+}
+interface ReelsModalProps {
+    /** Props forwarded to the inner <ReelsFeed> (render callbacks, initialMuted, etc.). */
+    feedProps?: ReelsFeedProps;
+    /** Enter/exit animation overrides. Defaults applied when omitted. */
+    animationConfig?: ReelsModalAnimationConfig;
+    /**
+     * Custom backdrop visual. Rendered inside the SDK-owned backdrop layer,
+     * whose opacity the SDK animates. If omitted, a semi-transparent black
+     * backdrop is used. Return null to suppress the default visual.
+     */
+    renderBackdrop?: (state: ReelsModalRenderState) => ReactNode;
+    /**
+     * Custom close affordance, rendered above <ReelsFeed> inside the panel.
+     * If omitted, a top-right ✕ button is shown. Return null to hide it
+     * (e.g. when the host relies on swipe-to-dismiss or its own chrome).
+     */
+    renderCloseButton?: (state: ReelsModalRenderState) => ReactNode;
+    /** Fired when the enter animation completes (viewer fully open). */
+    onOpen?: (index: number | null) => void;
+    /** Fired when the exit animation completes (viewer fully closed). */
+    onClose?: () => void;
+    /** Close when the backdrop is clicked. Default: true. */
+    closeOnBackdropClick?: boolean;
+    /** Close when Escape is pressed. Default: true. */
+    closeOnEscape?: boolean;
+    /** Lock body scroll while open. Default: true. */
+    lockBodyScroll?: boolean;
+    /**
+     * How many slots to prewarm on open. `prewarmForward` items ahead of the
+     * focused index plus 1 behind get an immediate preloadMetadata() call so
+     * buffering starts in the same tick as the tap. Default: 2.
+     */
+    prewarmForward?: number;
+    /** className on the sliding panel element. */
+    className?: string;
+    /** z-index for the modal root. Default: 1000. */
+    zIndex?: number;
+    /** Portal target. Default: document.body. */
+    portalTarget?: HTMLElement | null;
+}
+declare function ReelsModal({ feedProps, animationConfig, renderBackdrop, renderCloseButton, onOpen, onClose, closeOnBackdropClick, closeOnEscape, lockBodyScroll, prewarmForward, className, zIndex, portalTarget, }: ReelsModalProps): react.ReactPortal | null;
 
 /**
  * useHls — React hook for hls.js lifecycle management (3-Tier buffer support)
@@ -1001,6 +1195,30 @@ declare function useResource(): {
     getTier: (index: number) => 3 | 1 | 2 | 4 | null;
 };
 
+/**
+ * useNavigation — React hook for NavigationManager
+ *
+ * Subscribes to the reels viewer open/close lifecycle via useSyncExternalStore.
+ * Mirrors the useResource / useFeed selector pattern — no Zustand React bindings.
+ *
+ * Primary consumers:
+ * - ReelsModal: reads `phase` / `openIndex` to mount + animate the viewer,
+ *   and calls `setPhase` when its enter/exit animation finishes.
+ * - ReelsFeedThumbnail: calls `open(index)` on click when `openOnClick` is set.
+ * - Host app: can read `isOpen` / call `close()` to drive its own chrome.
+ */
+
+declare function useNavigationSelector<T>(selector: (state: NavigationState) => T): T;
+declare function useNavigation(): {
+    phase: NavigationPhase;
+    openIndex: number | null;
+    isOpen: boolean;
+    shouldMount: boolean;
+    open: (index: number) => void;
+    close: () => void;
+    setPhase: (next: NavigationPhase) => void;
+};
+
 /**
  * Mock adapters for development and testing
  */
@@ -1201,4 +1419,4 @@ declare class HttpError extends Error {
     constructor(status: number, message: string, body?: string | undefined);
 }
 
-export { type Article, type ArticleImage, type Author, type BufferTier, type CommentItem, type CommentPage, type ContentItem, type ContentStats, DEFAULT_FEED_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, type FeedConfig, type FeedError, FeedManager, type FeedPage, type FeedState, HttpDataSource, type HttpDataSourceConfig, HttpError, type IAnalytics, type ICommentAdapter, type IDataSource, type IInteraction, type ILogger, type INetworkAdapter, type ISessionStorage, type IVideoLoader, type InteractionState, type LogLevel, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, type NetworkType, OptimisticManager, type PauseSlotActions, type PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PointerGestureConfig, type PreloadResult, type PreloadStatus, ReelsFeed, type ReelsFeedProps, ReelsFeedThumbnail, type ReelsFeedThumbnailProps, ReelsProvider, type ReelsProviderProps, type ResourceConfig, ResourceGovernor, type ResourceState, type SDKAdapters, type SDKContextValue, type SlotActions, type SnapTarget, type UseHlsOptions, type UseHlsReturn, VALID_TRANSITIONS, type VideoItem, type VideoQuality, VideoSlot, type VideoSource, canPause, canPlay, canSeek, isArticle, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };
+export { type Article, type ArticleImage, type Author, type BufferTier, type CommentItem, type CommentPage, type ContentItem, type ContentStats, DEFAULT_FEED_CONFIG, DEFAULT_NAVIGATION_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, type FeedConfig, type FeedError, FeedManager, type FeedPage, type FeedState, HttpDataSource, type HttpDataSourceConfig, HttpError, type IAnalytics, type ICommentAdapter, type IDataSource, type IInteraction, type ILogger, type INetworkAdapter, type ISessionStorage, type IVideoLoader, type InteractionState, type LogLevel, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, type NavigationConfig, NavigationManager, type NavigationPhase, type NavigationState, type NetworkType, OptimisticManager, type PauseSlotActions, type PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PointerGestureConfig, type PreloadResult, type PreloadStatus, ReelsFeed, type ReelsFeedProps, ReelsFeedThumbnail, type ReelsFeedThumbnailProps, ReelsModal, type ReelsModalAnimationConfig, type ReelsModalProps, type ReelsModalRenderState, ReelsProvider, type ReelsProviderProps, type ResourceConfig, ResourceGovernor, type ResourceState, type SDKAdapters, type SDKContextValue, type SlotActions, type SnapTarget, type UseHlsOptions, type UseHlsReturn, VALID_TRANSITIONS, type VideoItem, type VideoQuality, VideoSlot, type VideoSource, canPause, canPlay, canSeek, isArticle, isValidNavTransition, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, useNavigation, useNavigationSelector, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };

package/dist/index.d.ts

@@ -443,6 +443,7 @@ declare class PlayerEngine {
     private circuitResetTimer;
     private watchTimeInterval;
     private lastStatus;
+    private _destroyed;
     constructor(config?: PlayerConfig, analytics?: IAnalytics, logger?: ILogger);
     /**
      * Load a video and prepare for playback.
@@ -498,11 +499,14 @@ declare class FeedManager {
     private inFlightRequests;
     /** LRU tracking: itemId → lastAccessTime */
     private accessOrder;
+    /** Idempotency guard for destroy() */
+    private _destroyed;
     /** Prefetch cache — instance-scoped (not static) */
     private prefetchCache;
     constructor(dataSource: IDataSource, config?: FeedConfig, logger?: ILogger);
     getDataSource(): IDataSource;
     setDataSource(dataSource: IDataSource, reset?: boolean): void;
+    setInitialItems(items: ContentItem[]): void;
     prefetch(ttlMs?: number): Promise<void>;
     hasPrefetchCache(): boolean;
     clearPrefetchCache(): void;
@@ -556,6 +560,8 @@ declare class OptimisticManager {
     private likeDebounceTimers;
     /** Pending like direction: contentId → final intended state */
     private pendingLikeState;
+    /** Idempotency guard for destroy() */
+    private _destroyed;
     constructor(interaction: Partial<IInteraction>, logger?: ILogger);
     /**
      * Debounced like toggle — prevents rapid API spam on double-tap.
@@ -626,6 +632,7 @@ declare class ResourceGovernor {
     private readonly logger?;
     private focusDebounceTimer;
     private networkUnsubscribe?;
+    private _destroyed;
     constructor(config?: ResourceConfig, videoLoader?: IVideoLoader, network?: INetworkAdapter, logger?: ILogger);
     activate(): Promise<void>;
     deactivate(): void;
@@ -658,6 +665,103 @@ declare class ResourceGovernor {
     private recalculate;
 }
 
+/**
+ * NavigationManager — Owns the open/close lifecycle of the SDK reels viewer.
+ *
+ * Framework-agnostic class (zustand/vanilla) mirroring FeedManager /
+ * ResourceGovernor / PlayerEngine conventions. It is the single source of
+ * truth for "is the reels viewer open, and at which index".
+ *
+ * WHY THIS EXISTS:
+ * Previously the host app owned the modal entirely (via onThumbnailClick).
+ * That meant the SDK could not warm a video before the host mounted
+ * <ReelsFeed>, producing the "poster stuck ~3s" stall. By owning the
+ * open/close phase, the SDK can:
+ *   1. mount <ReelsFeed> early (hidden behind the animating container),
+ *   2. prewarm the focused video DURING the open animation,
+ *   3. reveal an already-decoded first frame → no poster stall.
+ *
+ * PHASE MODEL (state machine):
+ *   closed  → opening : open(index) called (e.g. from a thumbnail tap)
+ *   opening → open    : ReelsModal finished its enter animation
+ *   open    → closing : close() called
+ *   closing → closed  : ReelsModal finished its exit animation
+ *
+ * Invalid transitions are dropped (see isValidNavTransition). This mirrors
+ * the PlayerEngine state-machine discipline used elsewhere in the SDK.
+ *
+ * The component layer (ReelsModal) drives the animation timing and calls
+ * `setPhase('open')` / `setPhase('closed')` when its Web Animations API
+ * transitions finish. NavigationManager itself holds no timers tied to
+ * animation — it only holds a safety fallback timer so a missing/janky
+ * animationend can never strand the phase forever.
+ */
+
+type NavigationPhase = 'closed' | 'opening' | 'open' | 'closing';
+interface NavigationState {
+    /** Current lifecycle phase of the reels viewer. */
+    phase: NavigationPhase;
+    /**
+     * Index the viewer was opened at. Held through the whole open lifecycle
+     * (opening → open → closing) and cleared back to null only once fully
+     * closed. ReelsModal mounts <ReelsFeed> whenever this is non-null so the
+     * feed can warm during `opening`.
+     */
+    openIndex: number | null;
+}
+interface NavigationConfig {
+    /**
+     * Safety fallback (ms). If the component never reports its enter/exit
+     * animation finished, the manager force-advances the phase so the viewer
+     * can never get stuck in `opening`/`closing`. Set generously above the
+     * real animation duration. Default: 1200.
+     */
+    phaseTimeoutMs?: number;
+}
+declare const DEFAULT_NAVIGATION_CONFIG: Required<NavigationConfig>;
+declare function isValidNavTransition(from: NavigationPhase, to: NavigationPhase): boolean;
+declare class NavigationManager {
+    readonly store: StoreApi<NavigationState>;
+    private readonly config;
+    private readonly logger?;
+    /** Fallback timer guarding against a missing animationend report. */
+    private phaseTimer;
+    private _destroyed;
+    constructor(config?: NavigationConfig, logger?: ILogger);
+    /**
+     * Open the reels viewer at `index`. Safe to call from a thumbnail click
+     * handler — it transitions into `opening`, at which point ReelsModal mounts
+     * <ReelsFeed> hidden and begins prewarming.
+     *
+     * Calling open() while already open/opening just retargets the index
+     * (e.g. user taps a different thumbnail before the animation settles).
+     */
+    open(index: number): void;
+    /**
+     * Begin closing the viewer. ReelsModal animates out then calls
+     * `setPhase('closed')`. Idempotent if already closing/closed.
+     */
+    close(): void;
+    /**
+     * Report an animation-driven phase change from the component layer.
+     * Invalid transitions are dropped. When reaching `closed`, openIndex is
+     * cleared so <ReelsFeed> unmounts.
+     */
+    setPhase(next: NavigationPhase): void;
+    getPhase(): NavigationPhase;
+    getOpenIndex(): number | null;
+    isOpen(): boolean;
+    /** Whether <ReelsFeed> should be mounted (any non-closed phase). */
+    shouldMount(): boolean;
+    destroy(): void;
+    /**
+     * Apply a guarded phase transition. Returns true if it was applied.
+     * Manages the fallback timer for transient phases (opening/closing).
+     */
+    private transition;
+    private clearPhaseTimer;
+}
+
 /**
  * Player State Machine — Guarded transitions
  *
@@ -776,15 +880,20 @@ interface SDKContextValue {
     playerEngine: PlayerEngine;
     resourceGovernor: ResourceGovernor;
     optimisticManager: OptimisticManager;
+    navigationManager: NavigationManager;
     adapters: Required<Omit<SDKAdapters, 'dataSource'>> & Pick<SDKAdapters, 'dataSource'>;
 }
 interface ReelsProviderProps {
     children: ReactNode;
     adapters: SDKAdapters;
+    /** Seed initial items into feedManager */
+    initialItems?: ContentItem[];
     /** Enable verbose logging (default: false) */
     debug?: boolean;
+    /** Config for the owned reels viewer open/close lifecycle (used by ReelsModal) */
+    navigationConfig?: NavigationConfig;
 }
-declare function ReelsProvider({ children, adapters, debug }: ReelsProviderProps): react_jsx_runtime.JSX.Element;
+declare function ReelsProvider({ children, adapters, initialItems, debug, navigationConfig, }: ReelsProviderProps): react_jsx_runtime.JSX.Element;
 declare function useSDK(): SDKContextValue;
 
 declare function ReelsFeed({ renderOverlay, renderActions, renderPauseAction, renderLoading, renderEmpty, renderError: _renderError, showFps, loadMoreThreshold, onSlotChange, gestureConfig, snapConfig, initialMuted, onAutoplayBlocked, }: ReelsFeedProps): string | number | bigint | boolean | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<react.ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null | undefined;
@@ -809,12 +918,97 @@ interface ReelsFeedThumbnailProps {
     wrap?: boolean;
     /** Enable click → update focused index on ReelsProvider before host reacts. Default: true. */
     setFocusOnClick?: boolean;
-    /** Prefetch metadata for this slot on pointer enter. Off by default. */
+    /**
+     * Open the SDK-owned <ReelsModal> on click (calls NavigationManager.open).
+     * This is the recommended path — the SDK controls modal timing and prewarms
+     * the video during the open animation, eliminating the "poster stuck ~3s"
+     * stall. Requires a <ReelsModal> mounted under the same <ReelsProvider>.
+     *
+     * Leave false (default) to keep the headless behaviour where the host owns
+     * the modal and reacts via `onThumbnailClick`.
+     *
+     * @default false
+     */
+    openOnClick?: boolean;
+    /**
+     * Prefetch HLS metadata for this slot on pointer enter (desktop hover).
+     * Useless on mobile WebView (no hover) — use `prewarmOnClick` there.
+     * Off by default.
+     */
     prefetchOnHover?: boolean;
+    /**
+     * Prefetch HLS metadata for the tapped slot synchronously on click, inside
+     * the tap gesture. This is the mobile-friendly counterpart to
+     * `prefetchOnHover` and starts buffering the instant the user taps — before
+     * any modal mounts. Recommended for mobile WebView. Default: true.
+     */
+    prewarmOnClick?: boolean;
     /** Key override — useful when host renders multiple lists from the same feed. */
     getKey?: (item: ContentItem, index: number) => string;
 }
-declare function ReelsFeedThumbnail({ renderThumbnail, onThumbnailClick, renderLoading, renderEmpty, renderError, className, wrap, setFocusOnClick, prefetchOnHover, getKey, }: ReelsFeedThumbnailProps): react_jsx_runtime.JSX.Element | null;
+declare function ReelsFeedThumbnail({ renderThumbnail, onThumbnailClick, renderLoading, renderEmpty, renderError, className, wrap, setFocusOnClick, openOnClick, prefetchOnHover, prewarmOnClick, getKey, }: ReelsFeedThumbnailProps): react_jsx_runtime.JSX.Element | null;
+
+interface ReelsModalAnimationConfig {
+    /** Enter/exit duration in ms (default: 300) */
+    duration?: number;
+    /** CSS easing (default: 'cubic-bezier(0.22, 1, 0.36, 1)') */
+    easing?: string;
+    /**
+     * Panel travel direction:
+     * - 'up'   (default): slides up from the bottom edge (bottom-sheet drawer)
+     * - 'down': slides down from the top edge
+     * - 'fade': no translate, opacity only
+     */
+    direction?: 'up' | 'down' | 'fade';
+}
+/** State handed to render-prop customisation callbacks. */
+interface ReelsModalRenderState {
+    phase: NavigationPhase;
+    openIndex: number | null;
+    /** Begin closing the viewer (runs the exit animation). */
+    close: () => void;
+}
+interface ReelsModalProps {
+    /** Props forwarded to the inner <ReelsFeed> (render callbacks, initialMuted, etc.). */
+    feedProps?: ReelsFeedProps;
+    /** Enter/exit animation overrides. Defaults applied when omitted. */
+    animationConfig?: ReelsModalAnimationConfig;
+    /**
+     * Custom backdrop visual. Rendered inside the SDK-owned backdrop layer,
+     * whose opacity the SDK animates. If omitted, a semi-transparent black
+     * backdrop is used. Return null to suppress the default visual.
+     */
+    renderBackdrop?: (state: ReelsModalRenderState) => ReactNode;
+    /**
+     * Custom close affordance, rendered above <ReelsFeed> inside the panel.
+     * If omitted, a top-right ✕ button is shown. Return null to hide it
+     * (e.g. when the host relies on swipe-to-dismiss or its own chrome).
+     */
+    renderCloseButton?: (state: ReelsModalRenderState) => ReactNode;
+    /** Fired when the enter animation completes (viewer fully open). */
+    onOpen?: (index: number | null) => void;
+    /** Fired when the exit animation completes (viewer fully closed). */
+    onClose?: () => void;
+    /** Close when the backdrop is clicked. Default: true. */
+    closeOnBackdropClick?: boolean;
+    /** Close when Escape is pressed. Default: true. */
+    closeOnEscape?: boolean;
+    /** Lock body scroll while open. Default: true. */
+    lockBodyScroll?: boolean;
+    /**
+     * How many slots to prewarm on open. `prewarmForward` items ahead of the
+     * focused index plus 1 behind get an immediate preloadMetadata() call so
+     * buffering starts in the same tick as the tap. Default: 2.
+     */
+    prewarmForward?: number;
+    /** className on the sliding panel element. */
+    className?: string;
+    /** z-index for the modal root. Default: 1000. */
+    zIndex?: number;
+    /** Portal target. Default: document.body. */
+    portalTarget?: HTMLElement | null;
+}
+declare function ReelsModal({ feedProps, animationConfig, renderBackdrop, renderCloseButton, onOpen, onClose, closeOnBackdropClick, closeOnEscape, lockBodyScroll, prewarmForward, className, zIndex, portalTarget, }: ReelsModalProps): react.ReactPortal | null;
 
 /**
  * useHls — React hook for hls.js lifecycle management (3-Tier buffer support)
@@ -1001,6 +1195,30 @@ declare function useResource(): {
     getTier: (index: number) => 3 | 1 | 2 | 4 | null;
 };
 
+/**
+ * useNavigation — React hook for NavigationManager
+ *
+ * Subscribes to the reels viewer open/close lifecycle via useSyncExternalStore.
+ * Mirrors the useResource / useFeed selector pattern — no Zustand React bindings.
+ *
+ * Primary consumers:
+ * - ReelsModal: reads `phase` / `openIndex` to mount + animate the viewer,
+ *   and calls `setPhase` when its enter/exit animation finishes.
+ * - ReelsFeedThumbnail: calls `open(index)` on click when `openOnClick` is set.
+ * - Host app: can read `isOpen` / call `close()` to drive its own chrome.
+ */
+
+declare function useNavigationSelector<T>(selector: (state: NavigationState) => T): T;
+declare function useNavigation(): {
+    phase: NavigationPhase;
+    openIndex: number | null;
+    isOpen: boolean;
+    shouldMount: boolean;
+    open: (index: number) => void;
+    close: () => void;
+    setPhase: (next: NavigationPhase) => void;
+};
+
 /**
  * Mock adapters for development and testing
  */
@@ -1201,4 +1419,4 @@ declare class HttpError extends Error {
     constructor(status: number, message: string, body?: string | undefined);
 }
 
-export { type Article, type ArticleImage, type Author, type BufferTier, type CommentItem, type CommentPage, type ContentItem, type ContentStats, DEFAULT_FEED_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, type FeedConfig, type FeedError, FeedManager, type FeedPage, type FeedState, HttpDataSource, type HttpDataSourceConfig, HttpError, type IAnalytics, type ICommentAdapter, type IDataSource, type IInteraction, type ILogger, type INetworkAdapter, type ISessionStorage, type IVideoLoader, type InteractionState, type LogLevel, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, type NetworkType, OptimisticManager, type PauseSlotActions, type PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PointerGestureConfig, type PreloadResult, type PreloadStatus, ReelsFeed, type ReelsFeedProps, ReelsFeedThumbnail, type ReelsFeedThumbnailProps, ReelsProvider, type ReelsProviderProps, type ResourceConfig, ResourceGovernor, type ResourceState, type SDKAdapters, type SDKContextValue, type SlotActions, type SnapTarget, type UseHlsOptions, type UseHlsReturn, VALID_TRANSITIONS, type VideoItem, type VideoQuality, VideoSlot, type VideoSource, canPause, canPlay, canSeek, isArticle, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };
+export { type Article, type ArticleImage, type Author, type BufferTier, type CommentItem, type CommentPage, type ContentItem, type ContentStats, DEFAULT_FEED_CONFIG, DEFAULT_NAVIGATION_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, type FeedConfig, type FeedError, FeedManager, type FeedPage, type FeedState, HttpDataSource, type HttpDataSourceConfig, HttpError, type IAnalytics, type ICommentAdapter, type IDataSource, type IInteraction, type ILogger, type INetworkAdapter, type ISessionStorage, type IVideoLoader, type InteractionState, type LogLevel, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, type NavigationConfig, NavigationManager, type NavigationPhase, type NavigationState, type NetworkType, OptimisticManager, type PauseSlotActions, type PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PointerGestureConfig, type PreloadResult, type PreloadStatus, ReelsFeed, type ReelsFeedProps, ReelsFeedThumbnail, type ReelsFeedThumbnailProps, ReelsModal, type ReelsModalAnimationConfig, type ReelsModalProps, type ReelsModalRenderState, ReelsProvider, type ReelsProviderProps, type ResourceConfig, ResourceGovernor, type ResourceState, type SDKAdapters, type SDKContextValue, type SlotActions, type SnapTarget, type UseHlsOptions, type UseHlsReturn, VALID_TRANSITIONS, type VideoItem, type VideoQuality, VideoSlot, type VideoSource, canPause, canPlay, canSeek, isArticle, isValidNavTransition, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, useNavigation, useNavigationSelector, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };