@xhub-short/sdk 0.1.0-beta.0

package/README.md

@@ -0,0 +1,596 @@
+# @xhub-short/sdk
+
+> **Glue Layer** - Kết nối Core Domain với React UI
+
+## 📖 SDK là gì?
+
+**SDK (Software Development Kit)** là package chính mà Host App cài đặt để tích hợp Short Video Feed. Nó đóng vai trò **"Glue Layer"** - kết nối tất cả các thành phần bên trong SDK thành một API thống nhất, dễ sử dụng.
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         HOST APP (Your App)                          │
+│                                                                      │
+│   import { ShortVideoProvider, useFeed, usePlayer } from '@xhub-short/sdk';
+│   import { VideoFeed, VideoPlayer } from '@xhub-short/ui';          │
+│                                                                      │
+└──────────────────────────────┬──────────────────────────────────────┘
+                               │ uses
+                               ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                         @xhub-short/ui                               │
+│                    (Lego Components - Phase 4)                       │
+│                                                                      │
+│   VideoFeed, VideoPlayer, InteractionBar, CommentSheet...           │
+│                                                                      │
+└──────────────────────────────┬──────────────────────────────────────┘
+                               │ imports hooks from
+                               ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                         @xhub-short/sdk                              │
+│                       (Glue Layer - Current)                         │
+│                                                                      │
+│   ┌─────────────┐   ┌─────────────┐   ┌─────────────────────────┐  │
+│   │  Provider   │   │   Hooks     │   │    Factory (createSDK)  │  │
+│   │  (Context)  │   │  (React)    │   │    (Dependency Inject)  │  │
+│   └─────────────┘   └─────────────┘   └─────────────────────────┘  │
+│                                                                      │
+└──────────────────────────────┬──────────────────────────────────────┘
+                               │ orchestrates
+          ┌────────────────────┴────────────────────┐
+          ▼                                         ▼
+   ┌─────────────┐                           ┌─────────────┐
+   │   @core     │                           │  @adapters  │
+   │ (Domain)    │                           │ (Infra)     │
+   └─────────────┘                           └─────────────┘
+```
+
+> **Lưu ý:** `@sdk` **KHÔNG** import từ `@ui`. Mũi tên chỉ hướng dependency (ai import ai).
+
+---
+
+## 🎯 Tại sao cần SDK?
+
+| Vấn đề | Giải pháp của SDK |
+|--------|-------------------|
+| Host App phải hiểu kiến trúc phức tạp bên trong | SDK expose API đơn giản: hooks + provider |
+| Khó setup dependency injection cho adapters | `createSDK()` tự động wire tất cả |
+| State management phức tạp (Feed, Player, Resource...) | Hooks abstract hết complexity |
+| SSR compatibility | `useSyncExternalStore` built-in |
+| Memory leaks khi unmount | `sdk.destroy()` cleanup tự động |
+
+---
+
+## 📋 Nhiệm vụ chi tiết của SDK
+
+SDK thực hiện **7 nhiệm vụ chính** để Host App có thể tích hợp dễ dàng:
+
+### 1. Dependency Injection & Wiring
+
+SDK là nơi **duy nhất** thực hiện dependency injection - kết nối các adapters với core managers:
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                    DEPENDENCY INJECTION MAP                          │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│   Adapter Interface          ───►    Core Component                 │
+│   ─────────────────                  ──────────────                 │
+│   IDataSource                ───►    FeedManager                    │
+│   IInteraction               ───►    OptimisticManager              │
+│   ISessionStorage            ───►    LifecycleManager               │
+│   INetworkAdapter            ───►    ResourceGovernor               │
+│   IVideoLoader + IPosterLoader ───►  ResourceGovernor               │
+│   IAnalytics                 ───►    PlayerEngine (events)          │
+│   ILogger                    ───►    All managers (debug)           │
+│                                                                      │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### 2. Adapter Resolution
+
+SDK tự động resolve adapters theo thứ tự ưu tiên:
+
+```
+Config Priority:
+┌──────────────────────────────────────────────────────────────┐
+│                                                               │
+│   1. config.adapters.dataSource    ◄── Highest (User-defined)│
+│              │                                                │
+│              ▼ fallback                                       │
+│   2. config.preset → createBrowserAdapters()                 │
+│              │                                                │
+│              ▼ fallback                                       │
+│   3. MockAdapter                   ◄── Lowest (Development)  │
+│                                                               │
+└──────────────────────────────────────────────────────────────┘
+```
+
+Điều này cho phép:
+- **Development**: Không cần config → Mock adapters tự động
+- **Production với Preset**: Chỉ cần `baseUrl + auth + endpoints`
+- **Full Custom**: Override bất kỳ adapter nào
+
+### 3. State Synchronization (Core ↔ React)
+
+Core Domain sử dụng **vanilla stores** (không React). SDK bridge chúng sang React:
+
+```
+┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
+│  Core Store     │         │     SDK Hook    │         │   React UI      │
+│  (Vanilla)      │   ───►  │ (useSyncExternal│   ───►  │  (Re-render)    │
+│                 │         │     Store)      │         │                 │
+└─────────────────┘         └─────────────────┘         └─────────────────┘
+     │                              │
+     │ store.subscribe()           │ getSnapshot()
+     │ store.setState()            │
+     ▼                              ▼
+  Framework-agnostic           SSR-safe subscription
+```
+
+**Tại sao không dùng Zustand trực tiếp trong Core?**
+- Core phải framework-agnostic (có thể dùng với Vue, Svelte...)
+- Giảm bundle size cho Core package
+- Tách biệt concerns rõ ràng
+
+### 4. Event Orchestration
+
+SDK wire các events giữa managers để chúng phối hợp:
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                        EVENT WIRING                                   │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                       │
+│   PlayerEngine                                                        │
+│       │                                                               │
+│       ├── on('videoChange') ──────► Analytics.flush()                │
+│       │                              (Flush trước khi đổi video)     │
+│       │                                                               │
+│       └── on('timeUpdate') ───────► LifecycleManager.setPendingSave()│
+│                                      (Auto-save playback position)   │
+│                                                                       │
+│   LifecycleManager                                                    │
+│       │                                                               │
+│       └── on('visibilityChange') ─► Analytics.flush()                │
+│           (state === 'hidden')       (Flush khi app background)      │
+│                                                                       │
+│   ResourceGovernor                                                    │
+│       │                                                               │
+│       └── on('focusChange') ──────► PlayerEngine.load(video)         │
+│                                      (Load video khi swipe)          │
+│                                                                       │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### 5. Lifecycle Management
+
+SDK quản lý toàn bộ vòng đời của các managers:
+
+| Phase | SDK Actions |
+|-------|-------------|
+| **Init** | Tạo managers, inject adapters, wire events, restore session |
+| **Active** | Managers hoạt động độc lập, SDK chỉ expose hooks |
+| **Background** | Auto-save session, flush analytics |
+| **Destroy** | Cleanup timers, unsubscribe events, clear cache |
+
+```typescript
+// Tự động trong Provider:
+useEffect(() => {
+  const sdk = createSDK(config);
+  return () => sdk.destroy(); // Cleanup khi unmount
+}, []);
+```
+
+### 6. Public API Surface
+
+SDK expose API đơn giản, ẩn đi complexity bên trong:
+
+| Exposed to Host App | Hidden from Host App |
+|---------------------|----------------------|
+| `useFeed()` - videos, loadMore | FeedManager internals |
+| `usePlayer()` - play, pause, seek | PlayerEngine state machine |
+| `useOptimistic()` - like, follow | Rollback queue, pending states |
+| `useSwipeGesture()` - onSwipe | DOM allocation logic |
+| Config với preset | Adapter creation |
+
+### 7. SSR Support
+
+SDK đảm bảo hoạt động với Server-Side Rendering:
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                      SSR STRATEGY                             │
+├──────────────────────────────────────────────────────────────┤
+│                                                               │
+│   Server:                                                     │
+│   ├─ ShortVideoProvider renders với empty state              │
+│   ├─ Hooks return initial/fallback values                    │
+│   └─ Không tạo SDK instance                                  │
+│                                                               │
+│   Client (Hydration):                                         │
+│   ├─ useEffect tạo SDK instance                              │
+│   ├─ Restore session từ localStorage                         │
+│   └─ useSyncExternalStore subscribe to stores                │
+│                                                               │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🏗️ Kiến trúc
+
+### Vị trí trong hệ thống
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                      HEXAGONAL ARCHITECTURE                          │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│   ┌─────────────────────────────────────────────────────────────┐   │
+│   │                    @xhub-short/sdk                           │   │
+│   │                    ════════════════                          │   │
+│   │                                                              │   │
+│   │   ShortVideoProvider ──────┬──────── createSDK()            │   │
+│   │          │                 │              │                  │   │
+│   │          │          Dependency Injection  │                  │   │
+│   │          │                 │              │                  │   │
+│   │          ▼                 ▼              ▼                  │   │
+│   │   ┌──────────┐      ┌──────────┐   ┌──────────┐             │   │
+│   │   │  Hooks   │      │  Core    │   │ Adapters │             │   │
+│   │   │ (React)  │◀────▶│ Managers │◀──│ (Inject) │             │   │
+│   │   └──────────┘      └──────────┘   └──────────┘             │   │
+│   │                                                              │   │
+│   └─────────────────────────────────────────────────────────────┘   │
+│                                                                      │
+│   ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │
+│   │ @contracts   │  │   @core      │  │      @adapters           │  │
+│   │ (Interfaces) │  │ (Domain)     │  │   (Infrastructure)       │  │
+│   └──────────────┘  └──────────────┘  └──────────────────────────┘  │
+│                                                                      │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Package Dependencies
+
+```
+@xhub-short/sdk
+├── @xhub-short/contracts  (types, interfaces)
+├── @xhub-short/core       (domain logic)
+├── @xhub-short/adapters   (mock + preset adapters)
+└── react (peer dependency)
+```
+
+---
+
+## ✨ Chức năng chính
+
+### 1. **Provider** - Context cho toàn bộ SDK
+
+```tsx
+<ShortVideoProvider config={{ preset: {...} }}>
+  <YourApp />
+</ShortVideoProvider>
+```
+
+### 2. **Hooks** - React API để truy cập SDK
+
+| Hook | Mục đích |
+|------|----------|
+| `useFeed()` | Video list, pagination, loading states |
+| `usePlayer()` | Playback control, time, volume, handlers |
+| `useResource()` | DOM allocations, prefetch queue |
+| `useOptimistic()` | Like/Follow với instant UI + rollback |
+| `useSwipeGesture()` | Vertical swipe navigation |
+
+### 3. **Wired Components** - Pre-connected UI Components
+
+SDK exports pre-wired versions of UI components with SDK hooks already injected:
+
+| Component | Description |
+|-----------|-------------|
+| `VideoFeed` | Wired VideoFeedHeadless with useFeed + useSwipeGesture |
+| `VideoSlot` | Wired VideoSlotHeadless with useResourceAllocation + usePlayer |
+| `VideoPlayer` | Wired VideoPlayerHeadless with usePlayer (auto-load, sync) |
+| `ProgressBar` | Wired progress bar with Direct DOM Update (60fps smooth) |
+
+#### VideoPlayer (Wired)
+
+Pre-wired video player that auto-connects to SDK PlayerEngine.
+
+```tsx
+import { VideoSlot, VideoPlayer } from '@xhub-short/sdk';
+import { VideoSlotPoster, VideoSlotOverlay } from '@xhub-short/ui';
+
+function FeedItem({ video }) {
+  return (
+    <VideoSlot video={video}>
+      <VideoPlayer 
+        resetOnInactive={true}  // TikTok-like: restart from beginning
+      />
+      <VideoSlotPoster />
+      <VideoSlotOverlay>...</VideoSlotOverlay>
+    </VideoSlot>
+  );
+}
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `video` | `VideoItem` | from context | Video to play (optional if inside VideoSlot) |
+| `autoLoad` | `boolean` | `true` | Auto-load video into PlayerEngine |
+| `autoPlay` | `boolean` | `true` | Auto-play when slot becomes active |
+| `resetOnInactive` | `boolean` | `true` | Reset video to 0:00 when slot becomes inactive |
+| `loop` | `boolean` | `true` | Loop video playback |
+| `muted` | `boolean` | `true` | Start muted (required for autoplay) |
+
+**`resetOnInactive` behavior:**
+- `true` (default): TikTok-like - swiping back restarts video from beginning
+- `false`: YouTube-like - video continues from where user left off
+
+#### ProgressBar (Wired) - P11 Re-render Optimization
+
+Pre-wired progress bar that uses **Direct DOM Update** for 60fps smooth animation.
+
+```tsx
+import { VideoSlot, VideoPlayer, ProgressBar } from '@xhub-short/sdk';
+import { VideoSlotOverlay } from '@xhub-short/ui';
+
+function FeedItem({ video }) {
+  return (
+    <VideoSlot video={video}>
+      <VideoPlayer />
+      <VideoSlotOverlay>
+        <ProgressBar seekable={true} />  {/* 60fps smooth! */}
+      </VideoSlotOverlay>
+    </VideoSlot>
+  );
+}
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `seekable` | `boolean` | `true` | Enable click/drag to seek |
+| `showTime` | `boolean` | `false` | Show current/duration text |
+| `showTooltip` | `boolean` | `true` | Show tooltip on hover |
+| `minimal` | `boolean` | `false` | Thin bar without handle |
+
+**Performance Architecture:**
+
+```
+PlayerEngine.store ───── subscribe() ───── fillRef.style.transform
+                                           (scaleX, GPU accelerated)
+                         NOT React re-render!
+```
+
+This component demonstrates ADR 005: Direct DOM Manipulation for high-frequency updates.
+See `docs/issues/RE_RENDER_ANALYSIS.md` for detailed optimization rationale.
+
+### 4. **Factory** - Dependency Injection
+
+```typescript
+const sdk = createSDK({
+  preset: { baseUrl, auth, endpoints },  // Auto-generate adapters
+  adapters: { dataSource, interaction }, // Or custom adapters
+  feed: { pageSize: 20 },
+  player: { autoplay: true },
+});
+```
+
+---
+
+## 🔄 Cách hoạt động
+
+### Flow: Từ Config đến UI
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                          INITIALIZATION                               │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                       │
+│   1. Host App mount <ShortVideoProvider config={...}>                │
+│                           │                                           │
+│                           ▼                                           │
+│   2. createSDK(config)                                               │
+│      ├─ Resolve adapters (preset → browser adapters)                 │
+│      ├─ Create Core managers:                                        │
+│      │   ├─ FeedManager      (video list, deduplication, GC)        │
+│      │   ├─ PlayerEngine     (playback state machine)               │
+│      │   ├─ ResourceGovernor (DOM allocation, prefetch)             │
+│      │   ├─ OptimisticManager (like/follow with rollback)           │
+│      │   └─ LifecycleManager (session persistence)                  │
+│      └─ Wire analytics flush events                                  │
+│                           │                                           │
+│                           ▼                                           │
+│   3. SDKContext.Provider value={sdk}                                 │
+│                           │                                           │
+│                           ▼                                           │
+│   4. Hooks subscribe to managers via useSyncExternalStore            │
+│                                                                       │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### Flow: User Interaction
+
+```
+User swipes down
+       │
+       ▼
+useSwipeGesture() ─────────► ResourceGovernor.setFocusedIndex(n+1)
+                                    │
+                   ┌────────────────┼────────────────┐
+                   ▼                ▼                ▼
+            Deallocate         Allocate         Preload
+            video[n-1]         video[n+1]       video[n+2]
+                                    │
+                                    ▼
+                            PlayerEngine.load(video)
+                                    │
+                                    ▼
+                            Analytics.track('video_view')
+```
+
+---
+
+## 📦 Exports
+
+### Provider
+
+```typescript
+export { ShortVideoProvider } from './provider';
+export type { ShortVideoProviderProps, SDKConfig } from './provider';
+```
+
+### Hooks
+
+```typescript
+// Feed management
+export { useFeed, useFeedSelector } from './hooks';
+
+// Player control
+export { usePlayer, usePlayerSelector, usePlayerForVideo } from './hooks';
+
+// Resource management (DOM allocation)
+export { useResource, useResourceSelector, useResourceAllocation } from './hooks';
+
+// Optimistic UI (like/follow)
+export { useOptimistic, useOptimisticSelector } from './hooks';
+
+// Swipe navigation
+export { useSwipeGesture } from './hooks';
+
+// SDK context access
+export { useSDK } from './hooks';
+```
+
+### Factory
+
+```typescript
+export { createSDK } from './store';
+export type { SDKInstance } from './store';
+```
+
+### Types (Re-exported)
+
+```typescript
+// From @xhub-short/contracts
+export type { VideoItem, FeedResponse, IDataSource, ... } from '@xhub-short/contracts';
+
+// From @xhub-short/core
+export type { FeedState, PlayerState, ResourceState, ... } from '@xhub-short/core';
+```
+
+---
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```tsx
+import { ShortVideoProvider, useFeed, usePlayer } from '@xhub-short/sdk';
+
+function App() {
+  return (
+    <ShortVideoProvider
+      config={{
+        preset: {
+          baseUrl: 'https://api.example.com/v1',
+          auth: { getAccessToken: () => localStorage.getItem('token') },
+          endpoints: {
+            feed: { list: '/videos', detail: '/videos/:id' },
+            interaction: { like: '/videos/:id/like', ... },
+          },
+        },
+      }}
+    >
+      <VideoFeed />
+    </ShortVideoProvider>
+  );
+}
+
+function VideoFeed() {
+  const { videos, loadInitial, loadMore, hasMore } = useFeed();
+  const { load, play, pause, isPlaying } = usePlayer();
+  
+  // Your UI here...
+}
+```
+
+### With Custom Adapters
+
+```tsx
+<ShortVideoProvider
+  config={{
+    adapters: {
+      dataSource: new MyGraphQLAdapter(),
+      interaction: new MyFlutterBridgeAdapter(),
+    },
+  }}
+>
+  <App />
+</ShortVideoProvider>
+```
+
+---
+
+## 🔗 Liên kết với các Packages
+
+| Package | Quan hệ với SDK |
+|---------|-----------------|
+| `@xhub-short/contracts` | SDK re-export types/interfaces |
+| `@xhub-short/core` | SDK wraps core managers với React hooks |
+| `@xhub-short/adapters` | SDK inject adapters vào core managers |
+| `@xhub-short/ui` | UI components sử dụng SDK hooks (Phase 4) |
+| `@xhub-short/bridge` | Optional Flutter integration |
+
+### Dependency Flow
+
+```
+contracts ◀─────────────────────────────────────────┐
+    ▲                                               │
+    │                                               │
+core ◀──────────────────────────┐                  │
+    ▲                           │                  │
+    │                           │                  │
+adapters ◀──────────┐          │                  │
+    ▲               │          │                  │
+    │               │          │                  │
+    └───────────────┴──────────┴────────── sdk ───┘
+                                             │
+                                             ▼
+                                        Host App
+```
+
+---
+
+## ⚠️ Lưu ý quan trọng
+
+### SSR Safety
+- Tất cả hooks sử dụng `useSyncExternalStore`
+- Provider render fallback trên server
+- SDK instance chỉ tạo trên client
+
+### Memory Management
+- `sdk.destroy()` được gọi tự động khi Provider unmount
+- Max 3 video DOM nodes (via ResourceGovernor)
+- LRU cache eviction trong FeedManager
+
+### Deprecated APIs
+
+```typescript
+// ❌ DEPRECATED - Singleton gây issues với SSR/testing
+const sdk = getSDK(config);
+
+// ✅ RECOMMENDED - Sử dụng Provider
+<ShortVideoProvider config={config}>
+  <App />
+</ShortVideoProvider>
+```
+
+---
+
+## 📚 Tài liệu liên quan
+
+- [ADD.md](/docs/ADD.md) - System Architecture
+- [TECH_STACK.md](/docs/TECH_STACK.md) - Technology Stack
+- [packages/core/README.md](/packages/core/README.md) - Core Domain
+- [packages/adapters/README.md](/packages/adapters/README.md) - Adapters