@xhub-short/contracts 0.1.0-beta.0

package/dist/index.d.ts

@@ -0,0 +1,1474 @@
+/**
+ * Core types for XHub-short SDK
+ * These types are the foundation of the SDK's data model.
+ */
+/**
+ * Video source configuration
+ * Supports both MP4 (native) and HLS streaming
+ */
+interface VideoSource {
+    /** Video URL - can be MP4 or HLS (.m3u8) */
+    url: string;
+    /** Source type for playback strategy selection */
+    type: 'mp4' | 'hls';
+    /** Optional quality variants for adaptive streaming */
+    qualities?: VideoQuality[];
+}
+/**
+ * Video quality variant for adaptive bitrate streaming
+ */
+interface VideoQuality {
+    /** Quality label (e.g., '720p', '1080p') */
+    label: string;
+    /** Bitrate in kbps */
+    bitrate: number;
+    /** Resolution width */
+    width: number;
+    /** Resolution height */
+    height: number;
+    /** URL for this quality */
+    url: string;
+}
+/**
+ * Video author information
+ */
+interface Author {
+    /** Unique author ID */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Avatar URL */
+    avatar?: string;
+    /** Verified status */
+    isVerified?: boolean;
+}
+/**
+ * Video statistics
+ */
+interface VideoStats {
+    /** Total view count */
+    views: number;
+    /** Total like count */
+    likes: number;
+    /** Total comment count */
+    comments: number;
+    /** Total share count */
+    shares: number;
+}
+/**
+ * Main video item structure
+ * This is the core data model for a video in the feed
+ */
+interface VideoItem {
+    /** Unique video ID */
+    id: string;
+    /** Video source configuration */
+    source: VideoSource;
+    /** Poster/thumbnail image URL */
+    poster?: string;
+    /** Video duration in seconds */
+    duration: number;
+    /** Video title/description */
+    title?: string;
+    /** Author information */
+    author: Author;
+    /** Video statistics */
+    stats: VideoStats;
+    /** Whether current user has liked this video */
+    isLiked: boolean;
+    /** Whether current user is following the author */
+    isFollowing: boolean;
+    /** Video creation timestamp */
+    createdAt: string;
+    /** Optional hashtags */
+    hashtags?: string[];
+    /** Optional music/sound information */
+    music?: MusicInfo;
+}
+/**
+ * Music/Sound information for a video
+ */
+interface MusicInfo {
+    /** Music ID */
+    id: string;
+    /** Music title */
+    title: string;
+    /** Artist name */
+    artist: string;
+    /** Cover image URL */
+    cover?: string;
+}
+/**
+ * Feed pagination response
+ */
+interface FeedResponse {
+    /** List of video items */
+    items: VideoItem[];
+    /** Cursor for next page (null if no more data) */
+    nextCursor: string | null;
+    /** Whether there are more items to load */
+    hasMore: boolean;
+}
+/**
+ * Feed state for state management
+ */
+interface FeedState {
+    /** Map of video items by ID (for O(1) lookup and deduplication) */
+    itemsMap: Map<string, VideoItem>;
+    /** Ordered list of video IDs for rendering */
+    orderedIds: string[];
+    /** Current cursor for pagination */
+    cursor: string | null;
+    /** Whether more items can be loaded */
+    hasMore: boolean;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    error: Error | null;
+}
+/**
+ * Playback state enum
+ */
+type PlaybackState = 'idle' | 'loading' | 'ready' | 'playing' | 'paused' | 'buffering' | 'ended' | 'error';
+/**
+ * Player state for a single video
+ */
+interface PlayerState {
+    /** Current playback state */
+    playbackState: PlaybackState;
+    /** Current playback time in seconds */
+    currentTime: number;
+    /** Total duration in seconds */
+    duration: number;
+    /** Buffered time ranges */
+    buffered: number;
+    /** Whether video is muted */
+    isMuted: boolean;
+    /** Current volume (0-1) */
+    volume: number;
+    /** Playback rate */
+    playbackRate: number;
+    /** Error information if playback failed */
+    error: PlayerError | null;
+}
+/**
+ * Player error information
+ */
+interface PlayerError {
+    /** Error code for programmatic handling */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Whether error is recoverable */
+    recoverable: boolean;
+    /** Retry count for circuit breaker */
+    retryCount: number;
+}
+/**
+ * Session snapshot for state persistence
+ * Used by Lifecycle Manager for state restoration
+ */
+interface SessionSnapshot {
+    /** Video items from feed (for offline restore) */
+    items: VideoItem[];
+    /** Feed cursor position for pagination */
+    cursor: string | null;
+    /** Index of the currently focused video */
+    focusedIndex: number;
+    /** Scroll position (optional, for virtual scroller) */
+    scrollPosition?: number;
+    /**
+     * Video playback position in seconds (optional)
+     * Only saved when restorePlaybackPosition config is enabled
+     * Used to seek() video to exact position when restoring
+     */
+    playbackTime?: number;
+    /**
+     * ID of the currently playing video (optional)
+     * Backup for focusedIndex in case feed order changed
+     */
+    currentVideoId?: string;
+    /** Snapshot creation time */
+    savedAt: number;
+    /** SDK version for compatibility checking */
+    version: string;
+}
+/**
+ * Comment structure
+ */
+interface Comment {
+    /** Comment ID */
+    id: string;
+    /** Comment text */
+    text: string;
+    /** Comment author */
+    author: Author;
+    /** Like count */
+    likes: number;
+    /** Whether current user liked this comment */
+    isLiked: boolean;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Reply count */
+    replyCount: number;
+}
+/**
+ * Optimistic action for tracking pending operations
+ */
+interface OptimisticAction<T = unknown> {
+    /** Unique action ID */
+    id: string;
+    /** Action type */
+    type: 'like' | 'unlike' | 'follow' | 'unfollow' | 'comment';
+    /** Target resource ID */
+    targetId: string;
+    /** Previous state for rollback */
+    previousState: T;
+    /** Timestamp for timeout handling */
+    timestamp: number;
+}
+/**
+ * Analytics event types
+ */
+type AnalyticsEventType = 'video_view' | 'video_play' | 'video_pause' | 'video_complete' | 'video_seek' | 'video_error' | 'like' | 'unlike' | 'share' | 'comment' | 'follow' | 'unfollow' | 'scroll' | 'impression';
+/**
+ * Analytics event structure
+ */
+interface AnalyticsEvent {
+    /** Event type */
+    type: AnalyticsEventType;
+    /** Video ID (if applicable) */
+    videoId?: string;
+    /** Event timestamp */
+    timestamp: number;
+    /** Additional event data */
+    data?: Record<string, unknown>;
+}
+/**
+ * SDK configuration options
+ */
+interface SDKConfig {
+    /** Data source adapter */
+    dataSource?: unknown;
+    /** Interaction adapter */
+    interaction?: unknown;
+    /** Storage adapter */
+    storage?: unknown;
+    /** Analytics adapter */
+    analytics?: unknown;
+    /** Logger adapter */
+    logger?: unknown;
+    /** Enable debug mode */
+    debug?: boolean;
+    /** Maximum number of video DOM nodes (default: 3) */
+    maxVideoDomNodes?: number;
+    /** Preload strategy */
+    preloadStrategy?: 'none' | 'next' | 'adjacent';
+}
+/**
+ * Log levels
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Log entry structure
+ */
+interface LogEntry {
+    /** Log level */
+    level: LogLevel;
+    /** Log message */
+    message: string;
+    /** Timestamp */
+    timestamp: number;
+    /** Additional context */
+    context?: Record<string, unknown>;
+    /** Error stack trace (if error) */
+    stack?: string;
+}
+
+/**
+ * IDataSource - Data Port Interface
+ *
+ * This interface defines the contract for fetching video data.
+ * SDK core never knows about specific APIs - it only talks to this interface.
+ *
+ * Implementations:
+ * - DefaultApiAdapter: Uses config.apiEndpoint to fetch
+ * - MockDataAdapter: Returns mock data for testing/development
+ * - Custom: Host App can provide their own implementation
+ *
+ * @example
+ * ```typescript
+ * class MyDataAdapter implements IDataSource {
+ *   async fetchFeed(cursor?: string): Promise<FeedResponse> {
+ *     const response = await myApi.getVideos(cursor);
+ *     return {
+ *       items: response.data.map(transformToVideoItem),
+ *       nextCursor: response.pagination.next,
+ *       hasMore: response.pagination.hasMore,
+ *     };
+ *   }
+ * }
+ * ```
+ */
+interface IDataSource {
+    /**
+     * Fetch a page of videos for the feed
+     *
+     * @param cursor - Pagination cursor from previous response (undefined for first page)
+     * @returns Promise resolving to feed response with items and pagination info
+     * @throws Error if network fails or API returns error
+     *
+     * Implementation notes:
+     * - Must handle network errors gracefully
+     * - Should return empty items array (not throw) if no data
+     * - Cursor format is opaque to SDK - can be page number, timestamp, etc.
+     */
+    fetchFeed(cursor?: string): Promise<FeedResponse>;
+    /**
+     * Get detailed information for a specific video
+     *
+     * @param id - Video ID
+     * @returns Promise resolving to video item details
+     * @throws Error if video not found or network fails
+     *
+     * Implementation notes:
+     * - May return cached data if available
+     * - Should throw specific error for 404 (video deleted/not found)
+     */
+    getVideoDetail(id: string): Promise<VideoItem>;
+    /**
+     * Optional: Prefetch videos for smoother scrolling
+     *
+     * @param ids - Array of video IDs to prefetch
+     * @returns Promise resolving when prefetch is complete
+     *
+     * Implementation notes:
+     * - This is optional - implementation can be no-op
+     * - Used by Resource Governor for preloading
+     * - Should not throw errors - fail silently
+     */
+    prefetch?(ids: string[]): Promise<void>;
+}
+
+/**
+ * IInteraction - Interaction Port Interface
+ *
+ * This interface defines the contract for user interactions with videos.
+ * Used with Optimistic UI pattern - UI updates immediately, API call happens async.
+ *
+ * Flow:
+ * 1. User taps like
+ * 2. UI updates immediately (optimistic)
+ * 3. This adapter is called
+ * 4. On error -> UI rolls back
+ *
+ * @example
+ * ```typescript
+ * class MyInteractionAdapter implements IInteraction {
+ *   async like(videoId: string): Promise<void> {
+ *     await api.post(`/videos/${videoId}/like`);
+ *   }
+ *
+ *   async unlike(videoId: string): Promise<void> {
+ *     await api.delete(`/videos/${videoId}/like`);
+ *   }
+ * }
+ * ```
+ */
+interface IInteraction {
+    /**
+     * Like a video
+     *
+     * @param videoId - ID of the video to like
+     * @returns Promise that resolves when like is persisted
+     * @throws Error if API fails (triggers rollback in OptimisticManager)
+     *
+     * Implementation notes:
+     * - Should be idempotent (liking twice = same result)
+     * - Throw error to trigger UI rollback
+     */
+    like(videoId: string): Promise<void>;
+    /**
+     * Remove like from a video
+     *
+     * @param videoId - ID of the video to unlike
+     * @returns Promise that resolves when unlike is persisted
+     * @throws Error if API fails (triggers rollback in OptimisticManager)
+     */
+    unlike(videoId: string): Promise<void>;
+    /**
+     * Follow a video author
+     *
+     * @param authorId - ID of the author to follow
+     * @returns Promise that resolves when follow is persisted
+     * @throws Error if API fails (triggers rollback in OptimisticManager)
+     */
+    follow(authorId: string): Promise<void>;
+    /**
+     * Unfollow a video author
+     *
+     * @param authorId - ID of the author to unfollow
+     * @returns Promise that resolves when unfollow is persisted
+     * @throws Error if API fails (triggers rollback in OptimisticManager)
+     */
+    unfollow(authorId: string): Promise<void>;
+    /**
+     * Post a comment on a video
+     *
+     * @param videoId - ID of the video to comment on
+     * @param text - Comment text content
+     * @returns Promise resolving to the created comment
+     * @throws Error if API fails
+     *
+     * Implementation notes:
+     * - Returns the full Comment object for UI display
+     * - Comment ID is generated by server
+     */
+    comment(videoId: string, text: string): Promise<Comment>;
+    /**
+     * Delete a comment
+     *
+     * @param commentId - ID of the comment to delete
+     * @returns Promise that resolves when comment is deleted
+     * @throws Error if API fails or comment not found
+     */
+    deleteComment(commentId: string): Promise<void>;
+    /**
+     * Like a comment
+     *
+     * @param commentId - ID of the comment to like
+     * @returns Promise that resolves when like is persisted
+     */
+    likeComment(commentId: string): Promise<void>;
+    /**
+     * Unlike a comment
+     *
+     * @param commentId - ID of the comment to unlike
+     * @returns Promise that resolves when unlike is persisted
+     */
+    unlikeComment(commentId: string): Promise<void>;
+    /**
+     * Share a video (optional tracking)
+     *
+     * @param videoId - ID of the video being shared
+     * @param platform - Optional platform identifier (e.g., 'facebook', 'twitter')
+     * @returns Promise that resolves when share is tracked
+     *
+     * Implementation notes:
+     * - This is primarily for tracking/analytics
+     * - Actual share mechanism is handled by Host App
+     */
+    share?(videoId: string, platform?: string): Promise<void>;
+    /**
+     * Report a video
+     *
+     * @param videoId - ID of the video to report
+     * @param reason - Report reason code
+     * @param description - Optional additional description
+     * @returns Promise that resolves when report is submitted
+     */
+    report?(videoId: string, reason: string, description?: string): Promise<void>;
+}
+
+/**
+ * IStorage - Storage Port Interface
+ *
+ * This interface defines the contract for persistent storage.
+ * Used by Lifecycle Manager for state restoration when user returns.
+ *
+ * Implementations:
+ * - LocalStorageAdapter: Uses browser localStorage
+ * - HybridStorageAdapter: Uses Flutter native storage via bridge
+ * - MemoryStorageAdapter: In-memory (for testing)
+ *
+ * Key Design Decision:
+ * - Storage is simple key-value
+ * - Complex objects are JSON serialized by the adapter
+ * - SDK stores session snapshots for state restoration
+ *
+ * @example
+ * ```typescript
+ * class LocalStorageAdapter implements IStorage {
+ *   async get<T>(key: string): Promise<T | null> {
+ *     const value = localStorage.getItem(key);
+ *     return value ? JSON.parse(value) : null;
+ *   }
+ *
+ *   async set<T>(key: string, value: T): Promise<void> {
+ *     localStorage.setItem(key, JSON.stringify(value));
+ *   }
+ * }
+ * ```
+ */
+interface IStorage {
+    /**
+     * Get a value from storage
+     *
+     * @param key - Storage key
+     * @returns Promise resolving to the stored value or null if not found
+     *
+     * Implementation notes:
+     * - Should return null (not throw) if key doesn't exist
+     * - Handle JSON parse errors gracefully (return null)
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Set a value in storage
+     *
+     * @param key - Storage key
+     * @param value - Value to store (will be serialized)
+     * @returns Promise that resolves when value is persisted
+     * @throws Error if storage is full (QuotaExceededError)
+     *
+     * Implementation notes:
+     * - Handle QuotaExceededError by implementing LRU eviction
+     * - Serialize complex objects to JSON
+     */
+    set<T>(key: string, value: T): Promise<void>;
+    /**
+     * Remove a value from storage
+     *
+     * @param key - Storage key to remove
+     * @returns Promise that resolves when value is removed
+     *
+     * Implementation notes:
+     * - Should not throw if key doesn't exist
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * Clear all SDK-related storage
+     *
+     * @returns Promise that resolves when storage is cleared
+     *
+     * Implementation notes:
+     * - Should only clear SDK-namespaced keys
+     * - Do not clear unrelated Host App storage
+     */
+    clear(): Promise<void>;
+    /**
+     * Get all keys in storage (for debugging/maintenance)
+     *
+     * @returns Promise resolving to array of storage keys
+     *
+     * Implementation notes:
+     * - Only return SDK-namespaced keys
+     * - Used for debugging and LRU eviction
+     */
+    keys(): Promise<string[]>;
+}
+/**
+ * Specialized interface for session snapshot storage
+ * Extends base IStorage with type-safe session methods
+ */
+interface ISessionStorage extends IStorage {
+    /**
+     * Save session snapshot for state restoration
+     *
+     * @param snapshot - Session state to persist
+     * @returns Promise that resolves when saved
+     *
+     * Implementation notes:
+     * - Called when user navigates away
+     * - Should handle QuotaExceeded by clearing old snapshots
+     */
+    saveSnapshot(snapshot: SessionSnapshot): Promise<void>;
+    /**
+     * Load the most recent session snapshot
+     *
+     * @returns Promise resolving to snapshot or null if none exists
+     *
+     * Implementation notes:
+     * - Called when SDK mounts
+     * - May return stale snapshot - let SDK decide if valid
+     */
+    loadSnapshot(): Promise<SessionSnapshot | null>;
+    /**
+     * Clear session snapshot
+     *
+     * @returns Promise that resolves when cleared
+     *
+     * Implementation notes:
+     * - Called when session is explicitly ended
+     * - Or when snapshot is too old to be useful
+     */
+    clearSnapshot(): Promise<void>;
+}
+
+/**
+ * IAnalytics - Analytics Port Interface
+ *
+ * This interface defines the contract for analytics tracking.
+ * Uses batching strategy - events are queued and sent in batches.
+ *
+ * Batching Strategy (per ADD):
+ * 1. Events are pushed to internal queue
+ * 2. Flush conditions:
+ *    - Queue > 10 items
+ *    - User changes video
+ *    - visibilitychange (user tabs away)
+ * 3. Uses navigator.sendBeacon for reliability
+ *
+ * @example
+ * ```typescript
+ * class MyAnalyticsAdapter implements IAnalytics {
+ *   private queue: AnalyticsEvent[] = [];
+ *
+ *   track(event: AnalyticsEvent): void {
+ *     this.queue.push(event);
+ *     if (this.queue.length >= 10) {
+ *       this.flush();
+ *     }
+ *   }
+ *
+ *   async flush(): Promise<void> {
+ *     if (this.queue.length === 0) return;
+ *
+ *     const events = [...this.queue];
+ *     this.queue = [];
+ *
+ *     navigator.sendBeacon('/analytics', JSON.stringify(events));
+ *   }
+ * }
+ * ```
+ */
+interface IAnalytics {
+    /**
+     * Track an analytics event
+     *
+     * @param event - Event to track
+     *
+     * Implementation notes:
+     * - Should NOT throw errors (fire-and-forget)
+     * - Queue events internally for batching
+     * - Don't block main thread
+     */
+    track(event: AnalyticsEvent): void;
+    /**
+     * Flush queued events immediately
+     *
+     * @returns Promise that resolves when flush is complete
+     *
+     * Implementation notes:
+     * - Called on visibilitychange
+     * - Called when user changes video
+     * - Use navigator.sendBeacon for reliability
+     * - Should not throw - fail silently
+     */
+    flush(): Promise<void>;
+    /**
+     * Track video view duration
+     *
+     * @param videoId - ID of the video
+     * @param duration - Watch duration in seconds
+     * @param totalDuration - Total video duration in seconds
+     *
+     * Implementation notes:
+     * - Called periodically during playback (heartbeat)
+     * - Used to calculate engagement metrics
+     */
+    trackViewDuration(videoId: string, duration: number, totalDuration: number): void;
+    /**
+     * Track video completion
+     *
+     * @param videoId - ID of the video
+     * @param watchTime - Total time watched in seconds
+     * @param loops - Number of times video looped
+     *
+     * Implementation notes:
+     * - Called when video ends or user navigates away
+     * - loops > 0 means user watched multiple times
+     */
+    trackCompletion(videoId: string, watchTime: number, loops: number): void;
+    /**
+     * Set user context for analytics
+     *
+     * @param userId - Optional user ID (null for anonymous)
+     * @param properties - Optional user properties
+     *
+     * Implementation notes:
+     * - Called once when SDK initializes
+     * - Properties are attached to all subsequent events
+     */
+    setUser?(userId: string | null, properties?: Record<string, unknown>): void;
+    /**
+     * Get current queue size (for debugging)
+     *
+     * @returns Number of events in queue
+     */
+    getQueueSize?(): number;
+}
+/**
+ * Analytics configuration options
+ */
+interface AnalyticsConfig {
+    /** Batch size threshold for auto-flush (default: 10) */
+    batchSize?: number;
+    /** Flush interval in milliseconds (default: 30000) */
+    flushInterval?: number;
+    /** Endpoint URL for sending events */
+    endpoint?: string;
+    /** Whether to use sendBeacon API (default: true) */
+    useSendBeacon?: boolean;
+    /** Whether to track automatically (default: true) */
+    autoTrack?: boolean;
+}
+
+/**
+ * ILogger - Logger Port Interface
+ *
+ * This interface defines the contract for logging.
+ * SDK uses internal Circular Buffer Logger pattern.
+ *
+ * Design (per ADD - Observability Strategy):
+ * - Maintain circular buffer of last 50 log entries in RAM
+ * - Normal operation: Only write to buffer (silent)
+ * - On error: Flush buffer + error to this adapter (loud)
+ *
+ * This gives context for debugging ("what happened before crash")
+ * without constant network traffic.
+ *
+ * @example
+ * ```typescript
+ * class ConsoleLoggerAdapter implements ILogger {
+ *   log(entry: LogEntry): void {
+ *     const method = entry.level === 'error' ? 'error' : 'log';
+ *     console[method](`[${entry.level}] ${entry.message}`, entry.context);
+ *   }
+ *
+ *   flush(entries: LogEntry[]): void {
+ *     console.group('SDK Log Flush');
+ *     entries.forEach(e => this.log(e));
+ *     console.groupEnd();
+ *   }
+ * }
+ * ```
+ */
+interface ILogger {
+    /**
+     * Log a single entry
+     *
+     * @param entry - Log entry to record
+     *
+     * Implementation notes:
+     * - Should not throw errors
+     * - Host App decides where logs go (console, Sentry, Firebase, etc.)
+     */
+    log(entry: LogEntry): void;
+    /**
+     * Flush multiple log entries (on error)
+     *
+     * @param entries - Array of recent log entries for context
+     *
+     * Implementation notes:
+     * - Called when SDK encounters an error
+     * - Entries are the last N items from circular buffer
+     * - Use this to send to error tracking service (Sentry, etc.)
+     */
+    flush(entries: LogEntry[]): void;
+    /**
+     * Log debug message (convenience method)
+     *
+     * @param message - Debug message
+     * @param context - Optional context data
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log info message (convenience method)
+     *
+     * @param message - Info message
+     * @param context - Optional context data
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log warning message (convenience method)
+     *
+     * @param message - Warning message
+     * @param context - Optional context data
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log error message (convenience method)
+     *
+     * @param message - Error message
+     * @param error - Optional Error object
+     * @param context - Optional context data
+     */
+    error(message: string, error?: Error, context?: Record<string, unknown>): void;
+}
+/**
+ * Logger configuration options
+ */
+interface LoggerConfig {
+    /** Minimum log level to record (default: 'info' in prod, 'debug' in dev) */
+    minLevel?: LogLevel;
+    /** Maximum entries in circular buffer (default: 50) */
+    bufferSize?: number;
+    /** Whether to also log to console in dev mode (default: true) */
+    consoleInDev?: boolean;
+    /** Whether to include timestamps (default: true) */
+    includeTimestamp?: boolean;
+    /** Whether to redact sensitive data (default: true) */
+    redactSensitive?: boolean;
+}
+/**
+ * Internal logger instance type
+ * Used by SDK internal components
+ */
+interface InternalLogger {
+    /** Log at debug level */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /** Log at info level */
+    info(message: string, context?: Record<string, unknown>): void;
+    /** Log at warn level */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /** Log at error level - triggers flush */
+    error(message: string, error?: Error, context?: Record<string, unknown>): void;
+    /** Get buffer contents (for debugging) */
+    getBuffer(): LogEntry[];
+    /** Manually trigger flush */
+    forceFlush(): void;
+}
+
+/**
+ * Network Adapter Interface
+ *
+ * Provides network information for adaptive prefetch/preload strategies.
+ * Implementations can use Web API (navigator.connection) or native bridge.
+ */
+/**
+ * Network connection type
+ */
+type NetworkType = 'wifi' | 'cellular' | '4g' | '3g' | 'slow' | 'offline';
+/**
+ * Network quality metrics
+ */
+interface NetworkQuality {
+    /** Effective connection type */
+    type: NetworkType;
+    /** Estimated downlink speed in Mbps */
+    downlink?: number;
+    /** Round-trip time in ms */
+    rtt?: number;
+    /** Whether connection is metered (cellular data) */
+    isMetered?: boolean;
+}
+/**
+ * Network adapter interface (Port)
+ *
+ * Abstracts network detection for cross-platform support:
+ * - Web: Uses Navigator.connection API (with fallbacks)
+ * - Flutter WebView: Uses native bridge for accurate info
+ *
+ * @example
+ * ```typescript
+ * // Web implementation
+ * class WebNetworkAdapter implements INetworkAdapter {
+ *   async getNetworkType() {
+ *     const conn = navigator.connection;
+ *     return conn?.effectiveType ?? 'wifi';
+ *   }
+ * }
+ *
+ * // Flutter bridge implementation
+ * class FlutterNetworkAdapter implements INetworkAdapter {
+ *   async getNetworkType() {
+ *     return await flutterBridge.getNetworkType();
+ *   }
+ * }
+ * ```
+ */
+interface INetworkAdapter {
+    /**
+     * Get current effective network type
+     *
+     * @returns Promise resolving to network type
+     */
+    getNetworkType(): Promise<NetworkType>;
+    /**
+     * Get detailed network quality metrics
+     *
+     * @returns Promise resolving to quality metrics
+     */
+    getNetworkQuality(): Promise<NetworkQuality>;
+    /**
+     * Subscribe to network changes
+     *
+     * @param callback - Called when network type changes
+     * @returns Unsubscribe function
+     */
+    onNetworkChange(callback: (type: NetworkType) => void): () => void;
+    /**
+     * Check if currently online
+     *
+     * @returns Promise resolving to online status
+     */
+    isOnline(): Promise<boolean>;
+}
+
+/**
+ * Video Loader Interface
+ *
+ * Abstracts video preloading for different video types (MP4 vs HLS).
+ * ResourceGovernor uses this to prefetch videos without knowing implementation details.
+ */
+
+/**
+ * Preload status for a video
+ */
+type PreloadStatus = 'idle' | 'loading' | 'ready' | 'error';
+/**
+ * Preload result with status and optional error
+ */
+interface PreloadResult {
+    /** Video ID */
+    videoId: string;
+    /** Preload status */
+    status: PreloadStatus;
+    /** Preloaded bytes (if available) */
+    loadedBytes?: number;
+    /** Error if preload failed */
+    error?: Error;
+}
+/**
+ * Preload configuration
+ */
+interface PreloadConfig {
+    /** Priority (higher = more important) */
+    priority?: number;
+    /** Maximum bytes to preload (for range requests) */
+    maxBytes?: number;
+    /** Timeout in ms */
+    timeout?: number;
+}
+/**
+ * Video loader interface (Port)
+ *
+ * Abstracts video preloading strategy based on video type:
+ *
+ * - **MP4:** Uses fetch with Range header to preload first N bytes
+ * - **HLS:** Uses hls.js API (startLoad) to preload initial segments
+ * - **Native HLS (Safari):** Uses video.preload="auto" with ghost video element
+ *
+ * @example
+ * ```typescript
+ * // ResourceGovernor uses IVideoLoader without knowing MP4 vs HLS
+ * class ResourceGovernor {
+ *   constructor(private videoLoader: IVideoLoader) {}
+ *
+ *   async prefetchNext(videoId: string, source: VideoSource) {
+ *     if (this.networkType === 'wifi') {
+ *       await this.videoLoader.preload(videoId, source);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface IVideoLoader {
+    /**
+     * Preload a video source
+     *
+     * Implementation varies by source type:
+     * - MP4: Fetch first chunk (500KB-1MB)
+     * - HLS: Load manifest + first segment via hls.js
+     *
+     * @param videoId - Unique video identifier
+     * @param source - Video source configuration
+     * @param config - Optional preload configuration
+     * @returns Promise resolving to preload result
+     */
+    preload(videoId: string, source: VideoSource, config?: PreloadConfig): Promise<PreloadResult>;
+    /**
+     * Cancel an in-progress preload
+     *
+     * @param videoId - Video ID to cancel
+     */
+    cancelPreload(videoId: string): void;
+    /**
+     * Check if a video is preloaded
+     *
+     * @param videoId - Video ID to check
+     * @returns Whether video data is cached/preloaded
+     */
+    isPreloaded(videoId: string): boolean;
+    /**
+     * Get preload status for a video
+     *
+     * @param videoId - Video ID to check
+     * @returns Current preload status
+     */
+    getPreloadStatus(videoId: string): PreloadStatus;
+    /**
+     * Clear preloaded data for a video (memory management)
+     *
+     * @param videoId - Video ID to clear
+     */
+    clearPreload(videoId: string): void;
+    /**
+     * Clear all preloaded data
+     */
+    clearAll(): void;
+    /**
+     * Get total preloaded bytes (for memory monitoring)
+     *
+     * @returns Total bytes currently preloaded
+     */
+    getTotalPreloadedBytes(): number;
+}
+/**
+ * Poster/thumbnail preloader interface
+ *
+ * Separate from video preloader for simpler implementation
+ * and to ensure posters are always loaded (even on slow networks)
+ */
+interface IPosterLoader {
+    /**
+     * Preload a poster image
+     *
+     * @param url - Poster image URL
+     * @returns Promise resolving when image is loaded
+     */
+    preload(url: string): Promise<void>;
+    /**
+     * Check if poster is cached
+     *
+     * @param url - Poster URL to check
+     * @returns Whether poster is in cache
+     */
+    isCached(url: string): boolean;
+    /**
+     * Clear poster cache
+     */
+    clearCache(): void;
+}
+
+/**
+ * UI Component Types for XHub-short SDK
+ *
+ * These types define the props for headless UI components and their wired versions.
+ * Used by:
+ * - @xhub-short/ui (headless components receive these as props)
+ * - @xhub-short/sdk (wired components inject these via HOC)
+ *
+ * Architecture: Two-Tier Export Pattern (Headless UI + SDK Wiring)
+ *
+ * NOTE: This package has NO DEPENDENCIES. React types are defined as generics
+ * and will be resolved by the consuming package (@xhub-short/ui or @xhub-short/sdk).
+ */
+
+/**
+ * Generic ReactNode type (resolved by consuming package)
+ * Use React.ReactNode when importing in @xhub-short/ui
+ */
+type UINode = unknown;
+/**
+ * Generic React ref type
+ */
+type UIRef<T> = {
+    current: T | null;
+} | ((instance: T | null) => void);
+/**
+ * Generic React component type
+ */
+type UIComponent<P = object> = (props: P) => UINode;
+/**
+ * Feed state from useFeed() hook
+ */
+interface UIFeedState {
+    /** List of video items */
+    videos: VideoItem[];
+    /** Whether feed is loading */
+    isLoading: boolean;
+    /** Whether there are more items to load */
+    hasMore: boolean;
+    /** Error if any */
+    error: Error | null;
+    /** Load more items */
+    loadMore: () => Promise<void>;
+    /** Refresh feed */
+    refresh: () => Promise<void>;
+}
+/**
+ * Swipe/scroll state from useSwipeGesture() hook
+ */
+interface UISwipeState {
+    /** Current active video index */
+    activeIndex: number;
+    /** Whether user is currently swiping */
+    isSwiping: boolean;
+    /** Drag offset in pixels (during swipe) */
+    dragOffset: number;
+    /** Swipe direction */
+    direction: 'up' | 'down' | null;
+    /** Go to specific index */
+    goToIndex: (index: number) => void;
+    /** Go to next video */
+    goToNext: () => void;
+    /** Go to previous video */
+    goToPrev: () => void;
+}
+/**
+ * Resource allocation state from useResourceAllocation() hook
+ */
+interface UIResourceState {
+    /** Whether this slot has an allocated video DOM node */
+    isAllocated: boolean;
+    /** Whether video data is preloaded */
+    isPreloaded: boolean;
+    /** Whether this is the active (focused) slot */
+    isActive: boolean;
+    /** Distance from active slot (0 = active, 1 = adjacent, etc.) */
+    distance: number;
+}
+/**
+ * Player state from usePlayerForVideo() hook
+ */
+interface UIPlayerState {
+    /** Current playback state */
+    state: PlayerState['playbackState'];
+    /** Current time in seconds */
+    currentTime: number;
+    /** Total duration in seconds */
+    duration: number;
+    /** Buffered percentage (0-1) */
+    buffered: number;
+    /** Whether video is muted */
+    isMuted: boolean;
+    /** Volume level (0-1) */
+    volume: number;
+    /** Whether video is playing */
+    isPlaying: boolean;
+    /** Whether video is loading */
+    isLoading: boolean;
+    /** Error if any */
+    error: Error | null;
+}
+/**
+ * Player controls from usePlayerForVideo() hook
+ */
+interface UIPlayerControls {
+    /** Play video */
+    play: () => void;
+    /** Pause video */
+    pause: () => void;
+    /** Toggle play/pause */
+    toggle: () => void;
+    /** Seek to time in seconds */
+    seek: (time: number) => void;
+    /** Set volume (0-1) */
+    setVolume: (volume: number) => void;
+    /** Toggle mute */
+    toggleMute: () => void;
+    /** Set muted state */
+    setMuted: (muted: boolean) => void;
+}
+/**
+ * Interaction state from useOptimistic() hook
+ */
+interface UIInteractionState {
+    /** Whether video is liked by current user */
+    isLiked: boolean;
+    /** Like count */
+    likeCount: number;
+    /** Comment count */
+    commentCount: number;
+    /** Share count */
+    shareCount: number;
+    /** Whether like action is pending */
+    isLikePending: boolean;
+}
+/**
+ * Interaction actions from useOptimistic() hook
+ */
+interface UIInteractionActions {
+    /** Toggle like state */
+    toggleLike: () => Promise<void>;
+    /** Share video */
+    share: () => Promise<void>;
+    /** Open comments */
+    openComments: () => void;
+}
+/**
+ * Author interaction state from useOptimistic() hook
+ */
+interface UIAuthorState {
+    /** Author info */
+    author: Author;
+    /** Whether current user is following */
+    isFollowing: boolean;
+    /** Whether follow action is pending */
+    isFollowPending: boolean;
+}
+/**
+ * Author interaction actions from useOptimistic() hook
+ */
+interface UIAuthorActions {
+    /** Toggle follow state */
+    toggleFollow: () => Promise<void>;
+    /** Open author profile */
+    openProfile: () => void;
+}
+/**
+ * VideoFeed headless component props
+ */
+interface VideoFeedHeadlessProps {
+    /** Feed state (videos, loading, etc.) */
+    feedState: UIFeedState;
+    /** Swipe/scroll state */
+    swipeState: UISwipeState;
+    /** Container height (usually 100vh) */
+    height?: number | string;
+    /** Additional CSS classes */
+    className?: string;
+    /** Render function for each video slot */
+    renderSlot: (video: VideoItem, index: number) => UINode;
+    /** Called when active index changes */
+    onIndexChange?: (index: number) => void;
+    /** Called when reaching near end of feed */
+    onEndReached?: () => void;
+    /** Threshold for triggering onEndReached (default: 2) */
+    endReachedThreshold?: number;
+}
+/**
+ * VideoSlot headless component props
+ */
+interface VideoSlotHeadlessProps {
+    /** Video item to display */
+    video: VideoItem;
+    /** Resource allocation state */
+    resourceState: UIResourceState;
+    /** Player state */
+    playerState: UIPlayerState;
+    /** Player controls */
+    playerControls: UIPlayerControls;
+    /** Additional CSS classes */
+    className?: string;
+    /** Children (overlay content) */
+    children?: UINode;
+    /** Called when video becomes visible */
+    onVisible?: () => void;
+    /** Called when video becomes hidden */
+    onHidden?: () => void;
+}
+/**
+ * VideoPlayer headless component props
+ */
+interface VideoPlayerHeadlessProps {
+    /** Video source URL */
+    src: string;
+    /** Source type */
+    type: 'mp4' | 'hls';
+    /** Poster image URL */
+    poster?: string;
+    /** Whether video should autoplay */
+    autoPlay?: boolean;
+    /** Whether video should loop */
+    loop?: boolean;
+    /** Whether video is muted */
+    muted?: boolean;
+    /** Initial volume (0-1) */
+    volume?: number;
+    /** Additional CSS classes */
+    className?: string;
+    /** Video element ref callback */
+    videoRef?: UIRef<HTMLVideoElement>;
+    /** Called when video can play */
+    onCanPlay?: () => void;
+    /** Called when video starts playing (play event) */
+    onPlay?: () => void;
+    /** Called when playback resumes after buffering (playing event) */
+    onPlaying?: () => void;
+    /** Called when video is paused */
+    onPause?: () => void;
+    /** Called when video ends */
+    onEnded?: () => void;
+    /** Called on time update */
+    onTimeUpdate?: (currentTime: number) => void;
+    /** Called when duration is known */
+    onDurationChange?: (duration: number) => void;
+    /** Called when video is waiting for data */
+    onWaiting?: () => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+    /** Called when first frame is captured */
+    onFirstFrameCapture?: (dataUrl: string) => void;
+}
+/**
+ * ProgressBar headless component props
+ */
+interface ProgressBarHeadlessProps {
+    /** Current time in seconds */
+    currentTime: number;
+    /** Total duration in seconds */
+    duration: number;
+    /** Buffered percentage (0-1) */
+    buffered?: number;
+    /** Whether seeking is enabled */
+    seekable?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Called when user seeks */
+    onSeek?: (time: number) => void;
+    /** Called when user starts seeking */
+    onSeekStart?: () => void;
+    /** Called when user ends seeking */
+    onSeekEnd?: () => void;
+}
+/**
+ * ActionBar headless component props
+ */
+interface ActionBarHeadlessProps {
+    /** Interaction state */
+    interactionState: UIInteractionState;
+    /** Interaction actions */
+    interactionActions: UIInteractionActions;
+    /** Additional CSS classes */
+    className?: string;
+    /** Children (action buttons) */
+    children?: UINode;
+}
+/**
+ * ActionButton (Like, Comment, Share) headless component props
+ */
+interface ActionButtonHeadlessProps {
+    /** Button icon (inactive state) */
+    icon: UINode;
+    /** Button icon (active state, e.g., filled heart) */
+    activeIcon?: UINode;
+    /** Whether button is in active state */
+    isActive?: boolean;
+    /** Count to display */
+    count?: number;
+    /** Whether action is pending */
+    isPending?: boolean;
+    /** Click handler */
+    onClick?: () => void;
+    /** Additional CSS classes */
+    className?: string;
+    /** Accessible label */
+    ariaLabel?: string;
+}
+/**
+ * AuthorInfo headless component props
+ */
+interface AuthorInfoHeadlessProps {
+    /** Author state */
+    authorState: UIAuthorState;
+    /** Author actions */
+    authorActions: UIAuthorActions;
+    /** Whether to show follow button */
+    showFollowButton?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Children (for compound pattern) */
+    children?: UINode;
+}
+/**
+ * ErrorBoundary component props
+ */
+interface ErrorBoundaryProps {
+    /** Children to render */
+    children: UINode;
+    /** Error handling mode */
+    mode?: 'show-error' | 'auto-skip' | 'auto-skip-with-toast';
+    /** Custom error fallback */
+    fallback?: UINode | ((error: Error, reset: () => void) => UINode);
+    /** Called when error occurs */
+    onError?: (error: Error) => void;
+    /** Called when reset is triggered */
+    onReset?: () => void;
+}
+/**
+ * Skeleton component props
+ */
+interface SkeletonProps {
+    /** Width */
+    width?: number | string;
+    /** Height */
+    height?: number | string;
+    /** Border radius */
+    borderRadius?: number | string;
+    /** Animation type */
+    animation?: 'pulse' | 'wave' | 'none';
+    /** Additional CSS classes */
+    className?: string;
+}
+/**
+ * VideoFeed wired component props
+ * feedState and swipeState are injected by SDK
+ */
+interface VideoFeedProps extends Omit<VideoFeedHeadlessProps, 'feedState' | 'swipeState'> {
+    /** Override feed state (optional) */
+    feedState?: UIFeedState;
+    /** Override swipe state (optional) */
+    swipeState?: UISwipeState;
+}
+/**
+ * VideoSlot wired component props
+ * resourceState, playerState, playerControls are injected by SDK
+ */
+interface VideoSlotProps extends Omit<VideoSlotHeadlessProps, 'resourceState' | 'playerState' | 'playerControls'> {
+    /** Override resource state (optional) */
+    resourceState?: UIResourceState;
+    /** Override player state (optional) */
+    playerState?: UIPlayerState;
+    /** Override player controls (optional) */
+    playerControls?: UIPlayerControls;
+}
+/**
+ * VideoPlayer wired component props
+ * Uses video from context, only needs overrides
+ */
+interface VideoPlayerWiredProps extends Partial<VideoPlayerHeadlessProps> {
+    /** Video item (required for wired version) */
+    video: VideoItem;
+}
+/**
+ * ActionBar wired component props
+ * interactionState and interactionActions are injected by SDK
+ */
+interface ActionBarProps extends Omit<ActionBarHeadlessProps, 'interactionState' | 'interactionActions'> {
+    /** Video to get interaction state for */
+    video: VideoItem;
+    /** Override interaction state (optional) */
+    interactionState?: UIInteractionState;
+    /** Override interaction actions (optional) */
+    interactionActions?: UIInteractionActions;
+}
+/**
+ * AuthorInfo wired component props
+ * authorState and authorActions are injected by SDK
+ */
+interface AuthorInfoProps extends Omit<AuthorInfoHeadlessProps, 'authorState' | 'authorActions'> {
+    /** Video to get author from */
+    video: VideoItem;
+    /** Override author state (optional) */
+    authorState?: UIAuthorState;
+    /** Override author actions (optional) */
+    authorActions?: UIAuthorActions;
+}
+/**
+ * Hook configuration for HOC factory
+ */
+interface WiredComponentConfig<THooks, THeadlessProps, TWiredProps> {
+    /** Function that calls SDK hooks and returns hook results */
+    useHooks: (props: TWiredProps) => THooks;
+    /** Function that maps hook results to headless component props */
+    mapHooksToProps: (hooks: THooks, props: TWiredProps) => Partial<THeadlessProps>;
+}
+/**
+ * HOC factory return type
+ */
+type WiredComponent<TWiredProps> = UIComponent<TWiredProps>;
+/**
+ * Icon component type
+ */
+type IconComponent = UIComponent<{
+    className?: string;
+    size?: number | string;
+}>;
+/**
+ * Format count function type (1000 -> "1K")
+ */
+type FormatCountFn = (count: number) => string;
+
+export type { ActionBarHeadlessProps, ActionBarProps, ActionButtonHeadlessProps, AnalyticsConfig, AnalyticsEvent, AnalyticsEventType, Author, AuthorInfoHeadlessProps, AuthorInfoProps, Comment, ErrorBoundaryProps, FeedResponse, FeedState, FormatCountFn, IAnalytics, IDataSource, IInteraction, ILogger, INetworkAdapter, IPosterLoader, ISessionStorage, IStorage, IVideoLoader, IconComponent, InternalLogger, LogEntry, LogLevel, LoggerConfig, MusicInfo, NetworkQuality, NetworkType, OptimisticAction, PlaybackState, PlayerError, PlayerState, PreloadConfig, PreloadResult, PreloadStatus, ProgressBarHeadlessProps, SDKConfig, SessionSnapshot, SkeletonProps, UIAuthorActions, UIAuthorState, UIComponent, UIFeedState, UIInteractionActions, UIInteractionState, UINode, UIPlayerControls, UIPlayerState, UIRef, UIResourceState, UISwipeState, VideoFeedHeadlessProps, VideoFeedProps, VideoItem, VideoPlayerHeadlessProps, VideoPlayerWiredProps, VideoQuality, VideoSlotHeadlessProps, VideoSlotProps, VideoSource, VideoStats, WiredComponent, WiredComponentConfig };