@xhub-reels/sdk 0.1.7

package/dist/index.d.cts

@@ -0,0 +1,1075 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { StoreApi } from 'zustand/vanilla';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { HlsConfig } from 'hls.js';
+
+/**
+ * Content types — VideoItem, Article, ContentItem
+ */
+interface VideoSource {
+    /** MP4 direct URL or HLS .m3u8 URL */
+    url: string;
+    type: 'mp4' | 'hls';
+    qualities?: VideoQuality[];
+}
+interface VideoQuality {
+    label: string;
+    bitrate: number;
+    width: number;
+    height: number;
+    url: string;
+}
+interface Author {
+    id: string;
+    name: string;
+    avatar?: string;
+    description?: string;
+    isVerified?: boolean;
+}
+interface ContentStats {
+    likes: number;
+    comments: number;
+    shares: number;
+    bookmarks?: number;
+    views: number;
+}
+interface InteractionState {
+    isLiked: boolean;
+    isBookmarked: boolean;
+    isFollowing: boolean;
+}
+interface VideoItem {
+    id: string;
+    type: 'video';
+    source: VideoSource;
+    poster?: string;
+    duration: number;
+    title?: string;
+    description?: string;
+    author: Author;
+    stats: ContentStats;
+    interaction: InteractionState;
+    /** HLS-specific: start position in seconds for session restore */
+    startPosition?: number;
+    /** Extra metadata for host app */
+    meta?: Record<string, unknown>;
+}
+interface ArticleImage {
+    url: string;
+    width?: number;
+    height?: number;
+    alt?: string;
+}
+interface Article {
+    id: string;
+    type: 'article';
+    images: ArticleImage[];
+    title?: string;
+    description?: string;
+    author: Author;
+    stats: ContentStats;
+    interaction: InteractionState;
+    meta?: Record<string, unknown>;
+}
+type ContentItem = VideoItem | Article;
+declare function isVideoItem(item: ContentItem): item is VideoItem;
+declare function isArticle(item: ContentItem): item is Article;
+
+/**
+ * Feed adapter interfaces and state types
+ */
+
+interface FeedPage {
+    items: ContentItem[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+interface IDataSource {
+    fetchFeed(cursor?: string | null): Promise<FeedPage>;
+}
+interface FeedState {
+    /** Normalized item map for O(1) lookup */
+    itemsById: Map<string, ContentItem>;
+    /** Ordered item IDs */
+    displayOrder: string[];
+    /** Initial load in progress */
+    loading: boolean;
+    /** Pagination load in progress */
+    loadingMore: boolean;
+    /** Current error */
+    error: FeedError | null;
+    /** Pagination cursor */
+    cursor: string | null;
+    /** Whether more items are available */
+    hasMore: boolean;
+    /** Whether current data is stale (SWR) */
+    isStale: boolean;
+    /** Last successful fetch timestamp */
+    lastFetchTime: number | null;
+}
+interface FeedError {
+    message: string;
+    code: string;
+    retryable: boolean;
+}
+interface FeedConfig {
+    /** Items per page (default: 10) */
+    pageSize?: number;
+    /** Max retries on error (default: 3) */
+    maxRetries?: number;
+    /** Base retry delay ms (default: 1000) */
+    retryDelay?: number;
+    /** Max cached items before LRU eviction (default: 50) */
+    maxCacheSize?: number;
+    /** Stale-while-revalidate TTL ms (default: 5min) */
+    staleTTL?: number;
+}
+declare const DEFAULT_FEED_CONFIG: Required<FeedConfig>;
+
+/**
+ * Player state types
+ */
+
+declare enum PlayerStatus {
+    IDLE = "idle",
+    LOADING = "loading",
+    PLAYING = "playing",
+    PAUSED = "paused",
+    BUFFERING = "buffering",
+    ERROR = "error"
+}
+interface PlayerError {
+    message: string;
+    code: 'MEDIA_ERROR' | 'NETWORK_ERROR' | 'DECODE_ERROR' | 'NOT_SUPPORTED' | 'UNKNOWN';
+    recoverable: boolean;
+    originalError?: Error;
+}
+interface PlayerState {
+    status: PlayerStatus;
+    currentVideo: VideoItem | null;
+    currentVideoId: string | null;
+    currentTime: number;
+    duration: number;
+    /** Buffered seconds */
+    buffered: number;
+    volume: number;
+    muted: boolean;
+    playbackRate: number;
+    loopCount: number;
+    watchTime: number;
+    error: PlayerError | null;
+    ended: boolean;
+    /** Session restore: seek to this position when matching videoId loads */
+    pendingRestoreTime: number | null;
+    pendingRestoreVideoId: string | null;
+}
+interface PlayerConfig {
+    defaultVolume?: number;
+    defaultMuted?: boolean;
+    /** Max consecutive errors before circuit opens (default: 3) */
+    circuitBreakerThreshold?: number;
+    /** Time ms to wait before circuit resets to HALF_OPEN (default: 10000) */
+    circuitBreakerResetMs?: number;
+}
+declare const DEFAULT_PLAYER_CONFIG: Required<PlayerConfig>;
+type PlayerEvent = {
+    type: 'statusChange';
+    status: PlayerStatus;
+    previousStatus: PlayerStatus;
+} | {
+    type: 'videoChange';
+    video: VideoItem;
+} | {
+    type: 'loadRejected';
+    reason: 'circuit_open' | 'invalid_transition';
+} | {
+    type: 'error';
+    error: PlayerError;
+} | {
+    type: 'ended';
+    videoId: string;
+    watchTime: number;
+    loopCount: number;
+};
+type PlayerEventListener = (event: PlayerEvent) => void;
+
+/**
+ * Adapter interfaces (Ports) — implemented by host app or use built-in mocks
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface ILogger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+interface IAnalytics {
+    trackView(videoId: string, duration: number): void;
+    trackLike(videoId: string, isLiked: boolean): void;
+    trackShare(videoId: string): void;
+    trackComment(videoId: string): void;
+    trackError(videoId: string, error: string): void;
+    trackPlaybackEvent(videoId: string, event: 'play' | 'pause' | 'seek' | 'end', position?: number): void;
+}
+interface IInteraction {
+    like(contentId: string): Promise<void>;
+    unlike(contentId: string): Promise<void>;
+    follow(authorId: string): Promise<void>;
+    unfollow(authorId: string): Promise<void>;
+    bookmark(contentId: string): Promise<void>;
+    unbookmark(contentId: string): Promise<void>;
+    share(contentId: string): Promise<void>;
+}
+interface ISessionStorage {
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T): void;
+    remove(key: string): void;
+    clear(): void;
+}
+type NetworkType = 'wifi' | '4g' | '3g' | '2g' | 'slow-2g' | 'offline' | 'unknown';
+interface INetworkAdapter {
+    getNetworkType(): NetworkType;
+    isOnline(): boolean;
+    onNetworkChange(callback: (type: NetworkType) => void): () => void;
+}
+type PreloadStatus = 'idle' | 'loading' | 'loaded' | 'error';
+interface PreloadResult {
+    videoId: string;
+    status: PreloadStatus;
+    loadedBytes?: number;
+    error?: Error;
+}
+interface IVideoLoader {
+    preload(videoId: string, url: string, signal?: AbortSignal): Promise<PreloadResult>;
+    cancel(videoId: string): void;
+    isPreloaded(videoId: string): boolean;
+    getPreloadStatus(videoId: string): PreloadStatus;
+    clearAll(): void;
+}
+interface CommentItem {
+    id: string;
+    contentId: string;
+    authorId: string;
+    authorName: string;
+    authorAvatar?: string;
+    text: string;
+    createdAt: number;
+    likeCount: number;
+    isLiked: boolean;
+}
+interface CommentPage {
+    items: CommentItem[];
+    nextCursor: string | null;
+    hasMore: boolean;
+    total: number;
+}
+interface ICommentAdapter {
+    fetchComments(contentId: string, cursor?: string | null): Promise<CommentPage>;
+    postComment(contentId: string, text: string): Promise<CommentItem>;
+    deleteComment(commentId: string): Promise<void>;
+    likeComment(commentId: string): Promise<void>;
+    unlikeComment(commentId: string): Promise<void>;
+}
+interface SDKAdapters {
+    dataSource: IDataSource;
+    interaction?: Partial<IInteraction>;
+    storage?: ISessionStorage;
+    analytics?: IAnalytics;
+    logger?: ILogger;
+    network?: INetworkAdapter;
+    videoLoader?: IVideoLoader;
+    comment?: ICommentAdapter;
+}
+
+/**
+ * ReelsFeed component types — Render Props architecture
+ */
+
+/** Actions provided to render prop callbacks for each video slot */
+interface SlotActions {
+    /** Optimistic like toggle via OptimisticManager */
+    toggleLike: () => void;
+    /** Current like delta from optimistic updates */
+    likeDelta: number;
+    /** Toggle follow via OptimisticManager */
+    toggleFollow: () => Promise<boolean>;
+    /** Optimistic follow state: undefined = server state, boolean = optimistic */
+    followState: boolean | undefined;
+    /** Share — calls IInteraction.share() if provided */
+    share: () => void;
+    /** Current global mute state */
+    isMuted: boolean;
+    /** Toggle global mute */
+    toggleMute: () => void;
+    /** Whether this slot is the active playing slot */
+    isActive: boolean;
+    /** Slot index in feed */
+    index: number;
+}
+/** Props for the ReelsFeed component */
+interface ReelsFeedProps {
+    /**
+     * Custom overlay rendered on each video slot.
+     * Receives the content item + actions. Return ReactNode.
+     * Positioned absolute bottom-left by SDK.
+     * If not provided, SDK uses DefaultOverlay showing author + title.
+     */
+    renderOverlay?: (item: ContentItem, actions: SlotActions) => ReactNode;
+    /**
+     * Custom action bar rendered on each video slot.
+     * Receives the content item + actions. Return ReactNode.
+     * Positioned absolute bottom-right by SDK.
+     * If not provided, SDK uses DefaultActions showing like/comment/share emojis.
+     */
+    renderActions?: (item: ContentItem, actions: SlotActions) => ReactNode;
+    /**
+     * Custom loading skeleton shown during initial feed load.
+     * If not provided, SDK uses DefaultSkeleton with shimmer animation.
+     */
+    renderLoading?: () => ReactNode;
+    /**
+     * Custom empty state shown when feed has zero items after load.
+     * If not provided, SDK shows a simple "No videos found" message.
+     */
+    renderEmpty?: () => ReactNode;
+    /**
+     * Custom error state shown when feed fails to load.
+     * If not provided, SDK shows the error message with a retry button.
+     */
+    renderError?: (error: {
+        message: string;
+        retry: () => void;
+    }) => ReactNode;
+    /** Show FPS counter overlay — dev only (default: false) */
+    showFps?: boolean;
+    /** Number of items from end to trigger loadMore (default: 5) */
+    loadMoreThreshold?: number;
+    /**
+     * Called when the active slot changes (user swipes to a new video).
+     * Fires AFTER snap animation triggers and new focusedIndex is set.
+     * Use for analytics tracking, preloading comments, updating URL, etc.
+     *
+     * @param index - New focused index
+     * @param item - The ContentItem at the new index
+     * @param prevIndex - Previous focused index
+     */
+    onSlotChange?: (index: number, item: ContentItem, prevIndex: number) => void;
+    /** Gesture config overrides */
+    gestureConfig?: {
+        velocityThreshold?: number;
+        distanceThreshold?: number;
+        dragThresholdRatio?: number;
+    };
+    /** Snap animation config overrides */
+    snapConfig?: {
+        duration?: number;
+        easing?: string;
+    };
+}
+
+/**
+ * PlayerEngine — Video player state machine with Circuit Breaker
+ *
+ * Features:
+ * - Guarded state transitions (only valid transitions allowed)
+ * - Circuit Breaker: auto-opens after N consecutive errors (WebView crash protection)
+ * - Watch time tracking
+ * - Analytics integration via adapter (optional)
+ * - Event system for external listeners
+ * - Framework-agnostic: uses zustand/vanilla (no React dependency)
+ */
+
+declare class PlayerEngine {
+    readonly store: StoreApi<PlayerState>;
+    private readonly config;
+    private readonly analytics?;
+    private readonly logger?;
+    private readonly listeners;
+    private circuit;
+    private circuitResetTimer;
+    private watchTimeInterval;
+    private lastStatus;
+    constructor(config?: PlayerConfig, analytics?: IAnalytics, logger?: ILogger);
+    /**
+     * Load a video and prepare for playback.
+     * Returns false if rejected by circuit breaker or invalid state.
+     */
+    load(video: VideoItem): boolean;
+    play(): boolean;
+    pause(): boolean;
+    togglePlay(): boolean;
+    seek(time: number): boolean;
+    setMuted(muted: boolean): void;
+    toggleMute(): void;
+    setVolume(volume: number): void;
+    setPlaybackRate(rate: number): void;
+    /** Called when <video> fires `canplay` */
+    onCanPlay(): void;
+    /** Called when <video> fires `waiting` */
+    onWaiting(): boolean;
+    /** Called when <video> fires `playing` (after buffering) */
+    onPlaying(): boolean;
+    /** Called when <video> fires `timeupdate` */
+    onTimeUpdate(currentTime: number): void;
+    /** Called when <video> fires `progress` (buffer update) */
+    onProgress(buffered: number): void;
+    /** Called when <video> fires `loadedmetadata` */
+    onLoadedMetadata(duration: number): void;
+    /** Called when <video> fires `ended` */
+    onEnded(): void;
+    /** Called when <video> fires `error` */
+    onError(code: PlayerError['code'], message: string): void;
+    setPendingRestore(videoId: string, time: number): void;
+    consumePendingRestore(videoId: string): number | null;
+    on(listener: PlayerEventListener): () => void;
+    reset(): void;
+    destroy(): void;
+    private transition;
+    private startWatchTime;
+    private stopWatchTime;
+    private checkCircuit;
+    private recordCircuitError;
+    private trackLeave;
+    private emit;
+}
+
+declare class FeedManager {
+    private dataSource;
+    readonly store: StoreApi<FeedState>;
+    private readonly config;
+    private readonly logger?;
+    /** Cancel in-flight requests */
+    private abortController;
+    /** In-flight request deduplication: cursor → Promise */
+    private inFlightRequests;
+    /** LRU tracking: itemId → lastAccessTime */
+    private accessOrder;
+    /** Prefetch cache — instance-scoped (not static) */
+    private prefetchCache;
+    constructor(dataSource: IDataSource, config?: FeedConfig, logger?: ILogger);
+    getDataSource(): IDataSource;
+    setDataSource(dataSource: IDataSource, reset?: boolean): void;
+    prefetch(ttlMs?: number): Promise<void>;
+    hasPrefetchCache(): boolean;
+    clearPrefetchCache(): void;
+    loadInitial(): Promise<void>;
+    loadMore(): Promise<void>;
+    refresh(): Promise<void>;
+    getItems(): ContentItem[];
+    getItemById(id: string): ContentItem | undefined;
+    updateItem(id: string, patch: Partial<ContentItem>): void;
+    destroy(): void;
+    private fetchPage;
+    private doFetch;
+    private applyItems;
+    private evictLRU;
+}
+
+/**
+ * OptimisticManager — Optimistic UI updates with rollback
+ *
+ * Handles like/follow/bookmark with:
+ * - Immediate local state update (optimistic)
+ * - Background API call
+ * - Rollback on failure
+ * - Debounced toggleLike (prevent rapid double-tap API spam)
+ */
+
+type ActionType = 'like' | 'unlike' | 'follow' | 'unfollow' | 'bookmark' | 'unbookmark';
+interface PendingAction {
+    id: string;
+    type: ActionType;
+    contentId: string;
+    enqueuedAt: number;
+}
+interface OptimisticState {
+    /** Map of actionId → PendingAction */
+    pendingActions: Map<string, PendingAction>;
+    /** IDs of failed actions waiting for retry */
+    failedQueue: string[];
+    hasPending: boolean;
+    isRetrying: boolean;
+    /** Optimistic like counts: contentId → delta */
+    likeDeltas: Map<string, number>;
+    /** Optimistic follow state: authorId → isFollowing */
+    followState: Map<string, boolean>;
+}
+declare class OptimisticManager {
+    readonly store: StoreApi<OptimisticState>;
+    private readonly interaction;
+    private readonly logger?;
+    /** Debounce timers: contentId → timer */
+    private likeDebounceTimers;
+    /** Pending like direction: contentId → final intended state */
+    private pendingLikeState;
+    constructor(interaction: Partial<IInteraction>, logger?: ILogger);
+    /**
+     * Debounced like toggle — prevents rapid API spam on double-tap.
+     * UI updates instantly; API call fires after 600ms debounce.
+     */
+    toggleLike(contentId: string, currentIsLiked: boolean): void;
+    toggleFollow(authorId: string, currentIsFollowing: boolean): Promise<boolean>;
+    getLikeDelta(contentId: string): number;
+    getFollowState(authorId: string): boolean | undefined;
+    destroy(): void;
+}
+
+/**
+ * ResourceGovernor — Video DOM allocation manager (3-Tier Pre-buffering)
+ *
+ * Tier 1 (Active):  1 slot — playing, 10s HLS buffer
+ * Tier 2 (Hot):     ±bufferWindow slots — DOM + HLS + 2s pre-buffered → instant swap
+ * Tier 3 (Warm):    +warmWindow beyond hot — DOM + HLS manifest + 1 segment (~0.5s) → ~300ms show
+ * Tier 4 (Cold):    preloadLookAhead beyond warm — metadata/manifest prefetch only (no DOM)
+ *
+ * Total DOM nodes = 1 + 2×bufferWindow + warmWindow (forward) + 1 (backward)
+ * Default: 1 + 6 + 4 = 11 DOM nodes, ~112 MB memory (fits comfortably in 1 GB budget)
+ */
+
+interface ResourceState {
+    /** Set of indices with active video DOM allocations (Tier 1 + 2 — hot) */
+    activeAllocations: Set<number>;
+    /** Set of indices with warm video DOM allocations (Tier 3 — manifest + 1 segment) */
+    warmAllocations: Set<number>;
+    /** Indices queued for preloading (Tier 4 — no DOM) */
+    preloadQueue: number[];
+    /** Currently focused index */
+    focusedIndex: number;
+    /** Total items in feed */
+    totalItems: number;
+    /** Current network type */
+    networkType: NetworkType;
+    /** Whether governor is active */
+    isActive: boolean;
+    /**
+     * Index that should be eagerly prefetched (src loaded) before the swipe commits.
+     * Set by the gesture layer at ~50% drag; cleared after snap completes.
+     * null = no active prefetch.
+     */
+    prefetchIndex: number | null;
+}
+interface ResourceConfig {
+    /** Max concurrent video DOM nodes — Tier 1+2+3 combined (default: 11) */
+    maxAllocations?: number;
+    /** Buffer window above/below focused index for hot tier (default: 3) */
+    bufferWindow?: number;
+    /** Additional warm slots beyond hot window — forward-biased (default: 4) */
+    warmWindow?: number;
+    /** Debounce ms for focusedIndex changes (default: 0) */
+    focusDebounceMs?: number;
+    /** How many items ahead of the warm window to queue for cold preload (default: 3) */
+    preloadLookAhead?: number;
+}
+declare const DEFAULT_RESOURCE_CONFIG: Required<ResourceConfig>;
+declare class ResourceGovernor {
+    readonly store: StoreApi<ResourceState>;
+    private readonly config;
+    private readonly videoLoader?;
+    private readonly network?;
+    private readonly logger?;
+    private focusDebounceTimer;
+    private networkUnsubscribe?;
+    constructor(config?: ResourceConfig, videoLoader?: IVideoLoader, network?: INetworkAdapter, logger?: ILogger);
+    activate(): Promise<void>;
+    deactivate(): void;
+    destroy(): void;
+    setTotalItems(count: number): void;
+    /**
+     * Debounced focus update — prevents rapid re-allocations during fast swipe
+     */
+    setFocusedIndex(index: number): void;
+    setFocusedIndexImmediate(index: number): void;
+    /**
+     * Signal that the given index should have its video src eagerly loaded.
+     * Called by the gesture layer at ~50% drag.  Pass null to clear.
+     */
+    setPrefetchIndex(index: number | null): void;
+    isAllocated(index: number): boolean;
+    isWarmAllocated(index: number): boolean;
+    shouldRenderVideo(index: number): boolean;
+    isPreloading(index: number): boolean;
+    getActiveAllocations(): number[];
+    getWarmAllocations(): number[];
+    private recalculate;
+}
+
+/**
+ * Player State Machine — Guarded transitions
+ *
+ * State Flow:
+ *   IDLE → LOADING → PLAYING ↔ PAUSED
+ *              ↓         ↓
+ *            ERROR ← BUFFERING
+ *              ↓
+ *            IDLE (retry)
+ */
+
+declare const VALID_TRANSITIONS: Record<PlayerStatus, PlayerStatus[]>;
+declare function isValidTransition(from: PlayerStatus, to: PlayerStatus): boolean;
+declare function canPlay(status: PlayerStatus): boolean;
+declare function canPause(status: PlayerStatus): boolean;
+declare function canSeek(status: PlayerStatus): boolean;
+
+/**
+ * usePointerGesture — Low-level pointer event handler for swipe gestures
+ *
+ * Architecture fix vs xhub-short:
+ * - Uses native Pointer Events (not React synthetic events)
+ * - ZERO React state updates during drag (only on snap)
+ * - No setTimeout polling for sync
+ * - MutationObserver-based slot cache (not querySelectorAll per frame)
+ * - cancelAnimationFrame dedup built-in
+ *
+ * @returns bind — spread on the container element
+ */
+interface PointerGestureConfig {
+    /** Axis to track (default: 'y') */
+    axis?: 'x' | 'y';
+    /** Minimum velocity px/ms to trigger snap (default: 0.3) */
+    velocityThreshold?: number;
+    /** Minimum distance px to trigger snap (default: 80) */
+    distanceThreshold?: number;
+    /** Whether gestures are disabled (default: false) */
+    disabled?: boolean;
+    /**
+     * Called every animation frame during drag with current offset.
+     * Use for direct DOM manipulation — do NOT call setState here.
+     */
+    onDragOffset?: (offset: number) => void;
+    /**
+     * Called once when drag passes the given threshold ratio (0–1) of containerSize.
+     * direction indicates which way the user is swiping.
+     * Use for prefetching — do NOT call setState here.
+     */
+    onDragThreshold?: (direction: 'forward' | 'backward') => void;
+    /**
+     * Container size in px used to calculate threshold ratio (default: window.innerHeight).
+     * Typically set to the viewport height for vertical feeds.
+     */
+    containerSize?: number;
+    /**
+     * Ratio of containerSize at which onDragThreshold fires (default: 0.5 = 50%).
+     */
+    dragThresholdRatio?: number;
+    /** Called when gesture ends and snap is triggered */
+    onSnap?: (direction: 'forward' | 'backward') => void;
+    /** Called when gesture ends without snap (bounce back) */
+    onBounceBack?: () => void;
+}
+interface PointerGestureBind {
+    onPointerDown: (e: React.PointerEvent) => void;
+}
+declare function usePointerGesture(config?: PointerGestureConfig): {
+    bind: PointerGestureBind;
+    isDraggingRef: React.RefObject<boolean>;
+    dragOffsetRef: React.RefObject<number>;
+};
+
+/**
+ * useSnapAnimation — Web Animations API snap
+ *
+ * Fixes xhub-short issue where CSS transition was interrupted by React renders.
+ * Web Animations API is imperative — runs independently of React lifecycle.
+ *
+ * Features:
+ * - Can be cancelled at any time (e.g., user starts new swipe during animation)
+ * - Predictable timing regardless of React render schedule
+ * - Automatic cleanup on unmount
+ */
+interface SnapAnimationConfig {
+    /** Duration in ms (default: 280) */
+    duration?: number;
+    /** CSS easing (default: 'cubic-bezier(0.25, 0.46, 0.45, 0.94)') */
+    easing?: string;
+}
+interface SnapTarget {
+    element: HTMLElement;
+    fromY: number;
+    toY: number;
+}
+declare function useSnapAnimation(config?: SnapAnimationConfig): {
+    /** Animate one or more slot elements from their current position to target */
+    animateSnap: (targets: SnapTarget[]) => void;
+    /** Animate bounce-back (offset → 0) */
+    animateBounceBack: (targets: SnapTarget[]) => void;
+    /** Cancel any in-progress animation */
+    cancelAnimation: () => void;
+};
+
+interface SDKContextValue {
+    feedManager: FeedManager;
+    playerEngine: PlayerEngine;
+    resourceGovernor: ResourceGovernor;
+    optimisticManager: OptimisticManager;
+    adapters: Required<Omit<SDKAdapters, 'dataSource'>> & Pick<SDKAdapters, 'dataSource'>;
+}
+interface ReelsProviderProps {
+    children: ReactNode;
+    adapters: SDKAdapters;
+    /** Enable verbose logging (default: false) */
+    debug?: boolean;
+}
+declare function ReelsProvider({ children, adapters, debug }: ReelsProviderProps): react_jsx_runtime.JSX.Element;
+declare function useSDK(): SDKContextValue;
+
+declare function ReelsFeed({ renderOverlay, renderActions, renderLoading, renderEmpty, renderError: _renderError, showFps, loadMoreThreshold, onSlotChange, gestureConfig, snapConfig, }: 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;
+
+/**
+ * useHls — React hook for hls.js lifecycle management (3-Tier buffer support)
+ *
+ * Handles:
+ * - hls.js initialization with optimized buffer config for video feeds
+ * - 3-tier buffer strategy: active (10s), hot (2s), warm (0.5s manifest+1seg)
+ * - Safari fallback (native HLS — no hls.js needed)
+ * - Automatic cleanup on unmount / src change (hls.destroy())
+ * - Fatal error mapping to PlayerEngine error codes
+ * - Media error recovery (one retry via recoverMediaError)
+ * - Quality level selection (ABR or manual)
+ *
+ * KEY FIX: When bufferTier changes (e.g. hot→active on swipe), the existing
+ * HLS instance is reconfigured in-place instead of being destroyed/recreated.
+ * This preserves already-buffered video data, eliminating the
+ * poster → black → play flash on swipe.
+ *
+ * Contract:
+ * - This hook does NOT call setState during playback frames
+ * - isReady state update happens once per src load (on canplay)
+ * - Cleanup is guaranteed via useEffect return
+ */
+
+/** Buffer tier determines how aggressively this slot pre-buffers video data. */
+type BufferTier = 'active' | 'hot' | 'warm';
+interface UseHlsOptions {
+    /** The .m3u8 URL to load. Pass undefined to unload. */
+    src: string | undefined;
+    /** Ref to the <video> element */
+    videoRef: React.RefObject<HTMLVideoElement | null>;
+    /** Whether this slot is the active (playing) one */
+    isActive: boolean;
+    /** Whether this slot should prefetch (load source but not play) */
+    isPrefetch: boolean;
+    /**
+     * Buffer tier for this slot (default: 'active').
+     * - 'active': Full 10s buffer (Tier 1 — currently playing)
+     * - 'hot':    2s buffer (Tier 2 — instant swap on swipe)
+     * - 'warm':   0.5s buffer (Tier 3 — manifest + 1 segment for fast show)
+     */
+    bufferTier?: BufferTier;
+    /** HLS config overrides (merged with tier-specific defaults) */
+    hlsConfig?: Partial<HlsConfig>;
+    /** Called when hls.js encounters a fatal error. Maps to PlayerEngine error codes. */
+    onError?: (code: 'NETWORK_ERROR' | 'MEDIA_ERROR' | 'DECODE_ERROR' | 'UNKNOWN', message: string) => void;
+}
+interface UseHlsReturn {
+    /** Whether hls.js is being used (false = native HLS on Safari) */
+    isHlsJs: boolean;
+    /** Whether the video has buffered enough data to play without black flash */
+    isReady: boolean;
+    /** Destroy the HLS instance manually (also called automatically on unmount) */
+    destroy: () => void;
+}
+declare function useHls(options: UseHlsOptions): UseHlsReturn;
+
+interface VideoSlotProps {
+    item: ContentItem;
+    index: number;
+    isActive: boolean;
+    isPrefetch: boolean;
+    isPreloaded: boolean;
+    bufferTier: BufferTier;
+    isMuted: boolean;
+    onToggleMute: () => void;
+    showFps?: boolean;
+    renderOverlay?: (item: ContentItem, actions: SlotActions) => ReactNode;
+    renderActions?: (item: ContentItem, actions: SlotActions) => ReactNode;
+}
+declare function VideoSlot({ item, index, isActive, isPrefetch, isPreloaded, bufferTier, isMuted, onToggleMute, showFps, renderOverlay, renderActions, }: VideoSlotProps): react_jsx_runtime.JSX.Element;
+
+declare function DefaultOverlay({ item }: {
+    item: ContentItem;
+}): react_jsx_runtime.JSX.Element;
+
+declare function DefaultActions({ item, actions }: {
+    item: ContentItem;
+    actions: SlotActions;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * DefaultSkeleton — Default loading skeleton with shimmer animation
+ *
+ * Used when host app does not provide renderLoading prop.
+ */
+declare function DefaultSkeleton(): react_jsx_runtime.JSX.Element;
+
+declare function useFeedSelector<T>(selector: (state: FeedState) => T): T;
+declare function useFeed(): {
+    items: NonNullable<ContentItem | undefined>[];
+    loading: boolean;
+    loadingMore: boolean;
+    hasMore: boolean;
+    error: FeedError | null;
+    isStale: boolean;
+    loadInitial: () => Promise<void>;
+    loadMore: () => Promise<void>;
+    refresh: () => Promise<void>;
+};
+
+declare function usePlayerSelector<T>(selector: (state: PlayerState) => T): T;
+declare function usePlayer(): {
+    status: PlayerStatus;
+    currentVideo: VideoItem | null;
+    currentTime: number;
+    duration: number;
+    buffered: number;
+    muted: boolean;
+    volume: number;
+    playbackRate: number;
+    error: PlayerError | null;
+    loopCount: number;
+    watchTime: number;
+    isPlaying: boolean;
+    isPaused: boolean;
+    isBuffering: boolean;
+    isLoading: boolean;
+    hasError: boolean;
+    progress: number;
+    bufferProgress: number;
+    play: () => boolean;
+    pause: () => boolean;
+    togglePlay: () => boolean;
+    seek: (t: number) => boolean;
+    setMuted: (m: boolean) => void;
+    toggleMute: () => void;
+    setVolume: (v: number) => void;
+    setPlaybackRate: (r: number) => void;
+    handlers: {
+        onCanPlay: () => void;
+        onWaiting: () => boolean;
+        onPlaying: () => boolean;
+        onEnded: () => void;
+        onTimeUpdate: (e: React.SyntheticEvent<HTMLVideoElement>) => void;
+        onProgress: (e: React.SyntheticEvent<HTMLVideoElement>) => void;
+        onLoadedMetadata: (e: React.SyntheticEvent<HTMLVideoElement>) => void;
+        onError: () => void;
+    };
+};
+
+declare function useResourceSelector<T>(selector: (state: ResourceState) => T): T;
+declare function useResource(): {
+    activeIndices: number[];
+    warmIndices: number[];
+    focusedIndex: number;
+    totalItems: number;
+    networkType: NetworkType;
+    isActive: boolean;
+    prefetchIndex: number | null;
+    setFocusedIndex: (i: number) => void;
+    setFocusedIndexImmediate: (i: number) => void;
+    setTotalItems: (n: number) => void;
+    shouldRenderVideo: (i: number) => boolean;
+    isAllocated: (i: number) => boolean;
+    isWarmAllocated: (i: number) => boolean;
+    setPrefetchIndex: (i: number | null) => void;
+};
+
+/**
+ * Mock adapters for development and testing
+ */
+
+declare class MockLogger implements ILogger {
+    private readonly prefix;
+    constructor(prefix?: string);
+    debug(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+}
+declare class MockAnalytics implements IAnalytics {
+    readonly events: unknown[];
+    private log;
+    trackView(videoId: string, duration: number): void;
+    trackLike(videoId: string, isLiked: boolean): void;
+    trackShare(videoId: string): void;
+    trackComment(videoId: string): void;
+    trackError(videoId: string, error: string): void;
+    trackPlaybackEvent(videoId: string, event: string, position?: number): void;
+}
+declare class MockInteraction implements IInteraction {
+    readonly calls: string[];
+    private delay;
+    constructor(delayMs?: number);
+    private simulate;
+    like(id: string): Promise<void>;
+    unlike(id: string): Promise<void>;
+    follow(id: string): Promise<void>;
+    unfollow(id: string): Promise<void>;
+    bookmark(id: string): Promise<void>;
+    unbookmark(id: string): Promise<void>;
+    share(id: string): Promise<void>;
+}
+declare class MockSessionStorage implements ISessionStorage {
+    private store;
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T): void;
+    remove(key: string): void;
+    clear(): void;
+}
+declare class MockNetworkAdapter implements INetworkAdapter {
+    private type;
+    private callbacks;
+    getNetworkType(): NetworkType;
+    isOnline(): boolean;
+    onNetworkChange(cb: (t: NetworkType) => void): () => void;
+    /** Test helper: simulate network change */
+    simulateChange(type: NetworkType): void;
+}
+declare class MockVideoLoader implements IVideoLoader {
+    private preloaded;
+    private loading;
+    private delayMs;
+    constructor(delayMs?: number);
+    preload(videoId: string, _url: string, signal?: AbortSignal): Promise<PreloadResult>;
+    cancel(videoId: string): void;
+    isPreloaded(videoId: string): boolean;
+    getPreloadStatus(videoId: string): "idle" | "loading" | "loaded";
+    clearAll(): void;
+}
+declare class MockDataSource implements IDataSource {
+    private totalItems;
+    private pageSize;
+    private delayMs;
+    constructor(options?: {
+        totalItems?: number;
+        pageSize?: number;
+        delayMs?: number;
+    });
+    fetchFeed(cursor?: string | null): Promise<{
+        items: {
+            id: string;
+            type: "video";
+            source: {
+                url: string;
+                type: "mp4";
+            };
+            poster: string;
+            duration: number;
+            title: string;
+            description: string;
+            author: {
+                id: string;
+                name: string;
+                avatar: string;
+                isVerified: boolean;
+            };
+            stats: {
+                likes: number;
+                comments: number;
+                shares: number;
+                views: number;
+            };
+            interaction: {
+                isLiked: boolean;
+                isBookmarked: boolean;
+                isFollowing: boolean;
+            };
+        }[];
+        nextCursor: string | null;
+        hasMore: boolean;
+    }>;
+}
+declare class MockCommentAdapter implements ICommentAdapter {
+    fetchComments(contentId: string, cursor?: string | null): Promise<{
+        items: {
+            id: string;
+            contentId: string;
+            authorId: string;
+            authorName: string;
+            text: string;
+            createdAt: number;
+            likeCount: number;
+            isLiked: boolean;
+        }[];
+        nextCursor: string | null;
+        hasMore: boolean;
+        total: number;
+    }>;
+    postComment(contentId: string, text: string): Promise<{
+        id: string;
+        contentId: string;
+        authorId: string;
+        authorName: string;
+        text: string;
+        createdAt: number;
+        likeCount: number;
+        isLiked: boolean;
+    }>;
+    deleteComment(_id: string): Promise<void>;
+    likeComment(_id: string): Promise<void>;
+    unlikeComment(_id: string): Promise<void>;
+}
+
+/**
+ * HttpDataSource — IDataSource implementation for REST APIs
+ *
+ * Maps API responses (snake_case) → SDK ContentItem (camelCase).
+ * Targets: GET /api/v1/reels?api_key=<key>&limit=<n>&cursor=<cursor>
+ *
+ * Response shape:
+ *   { code, data: { reels[], total, number_of_items, has_next, next_cursor }, success }
+ *
+ * Usage:
+ *   const ds = new HttpDataSource({
+ *     baseUrl: 'https://gw-stg-messages.blocktrend.xyz/api/v1',
+ *     apiKey: 'yaah',
+ *   });
+ */
+
+interface HttpDataSourceConfig {
+    /** Base URL of the API, e.g. https://gw-stg-messages.blocktrend.xyz/api/v1 */
+    baseUrl: string;
+    /**
+     * API key sent as `?api_key=<value>` query param.
+     * Takes precedence over `getAccessToken` for this backend.
+     */
+    apiKey?: string;
+    /** Returns Bearer token (sync or async). Return null/undefined to skip. */
+    getAccessToken?: () => string | null | undefined | Promise<string | null | undefined>;
+    /** Feed list endpoint path (default: '/reels') */
+    feedPath?: string;
+    /** Query param name for cursor (default: 'cursor') */
+    cursorParam?: string;
+    /** Query param name for page size (default: 'limit') */
+    limitParam?: string;
+    /** Number of items per page (default: 10) */
+    pageSize?: number;
+    /** Extra static headers to include in every request */
+    headers?: Record<string, string>;
+    /** Request timeout in ms (default: 10000) */
+    timeoutMs?: number;
+    /** Logger adapter */
+    logger?: ILogger;
+}
+declare class HttpDataSource implements IDataSource {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly getAccessToken;
+    private readonly feedPath;
+    private readonly cursorParam;
+    private readonly limitParam;
+    private readonly pageSize;
+    private readonly extraHeaders;
+    private readonly timeoutMs;
+    private readonly logger?;
+    constructor(config: HttpDataSourceConfig);
+    fetchFeed(cursor?: string | null): Promise<FeedPage>;
+    private fetch;
+    private buildHeaders;
+}
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly body?: string | undefined;
+    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, 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 PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PointerGestureConfig, type PreloadResult, type PreloadStatus, ReelsFeed, type ReelsFeedProps, 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 };