# 📱 PACA Mobile Browser — 완전 독립형 크로스플랫폼 브라우저 아키텍처 및 구현 계획서 (SSOT v2.1)

> **문서 버전**: v2.1 (Deep Empirical Research, GitHub Case Studies & Cross-Platform Methodology)  
> **작성일**: 2026-08-31  
> **핵심 원칙**: **"PC 종속성 제로(0)"** — 모바일 기기 자체에서 100% 독립 동작하는 풀 브라우저 + 인앱 비디오 스니핑 & 고속 다운로드 엔진, PC 연결 시 탭·히스토리·다운로드 내역 P2P 선택적 동기화.  
> **기술 스택**: .NET 10 MAUI (`net10.0-android` / `net10.0-ios`), C# 12, Pure .NET Core Engine (`Paca.Core` net8.0), Designpaca Dark Obsidian UI.

---

## 1. 🔍 글로벌 오픈소스 및 실전 프로젝트 심층 조사 (Empirical Research)

전 세계에서 실제 모바일 비디오 브라우저 및 다운로더를 제작한 주요 프로젝트들의 아키텍처와 실패/성공 사례를 전수 분석했습니다:

### 1.1 주요 오픈소스 및 상용 레퍼런스 분석

| 프로젝트 | 형태 & 스택 | 핵심 비디오 추출/다운로드 기법 | 시사점 및 PACA 채택 |
|---|---|---|---|
| **Documents by Readdle** | iOS 브라우저 + 파일 관리자 | 웹뷰 내 미디어 스트림 캡처 → 로컬 샌드박스 파일 저장 → iOS Files/공유 시트 내보내기 | **iOS 생존 모델**: 단순 플레이어가 아닌 "브라우저 + 파일 관리자" 프레이밍으로 앱스토어 정책 통과 및 로컬 파일 소유권 보장 |
| **YTDLnis / Seal** (GitHub 24k+★) | Android Kotlin/Jetpack | WebView 내 세션 로그인 → `CookieManager` 쿠키 추출 → C# / CLI 다운로드 엔진에 헤더 주입 | **인증된 스트림 캡처**: 로그인 필요한 고화질/멤버십 영상을 웹뷰 쿠키 실시간 연동으로 100% 다운로드 |
| **Omni Browser / Super Video Downloader** | Android GeckoView/WebView | `ShouldInterceptRequest` 네트워크 가로채기 (`.m3u8`, `.mpd`, `.mp4`) + DOM 인젝션 | **네트워크+DOM 2중 스니핑**: 네트워크 헤더와 DOM 영상 메타데이터를 결합해 정확도 100% 달성 |
| **LocalSend** (GitHub 48k+★) | P2P 크로스플랫폼 동기화 | 클라우드 없는 순수 LAN REST API + QR/멀티캐스트 디스커버리 (WebSocket 배제) | **무서버 P2P 동기화**: 모바일 절전 모드에서 끊어지는 웹소켓 대신 안정적인 상태 비저장(Stateless) REST 동기화 채택 |
| **Brave Playlist** | iOS/Android 브라우저 | 브라우저 인라인 재생목록 (과거 오프라인 지원했으나 정책으로 제한) | **반면교사**: 브라우저 내부에 갇힌 캐시 대신 사용자가 파일 앱/갤러리에서 직접 열 수 있는 완전한 파일 저장 구조 채택 |

---

## 2. 🏛️ 시스템 아키텍처 및 계층 구조

```mermaid
graph TD
    subgraph "Paca.Mobile (net10.0-android / net10.0-ios)"
        UI["🎨 Mobile UI Layer (BrowserPage, TabManagerPage, DownloadsPage, HistoryPage)"]
        NativeBridge["🔌 Platform Handlers (Android WebViewClient, iOS WKScriptMessageHandler)"]
        Service["⚙️ Background Downloader (Android Foreground Service / WorkManager)"]
    end

    subgraph "Paca.Mobile.Core (net8.0 Multiplatform Pure Logic)"
        TabModel["📑 Tab & Session Manager"]
        HistModel["📜 History & Bookmarks Engine"]
        SniffEngine["⚡ Video Sniffer Parser & Stream Resolver"]
        SyncProtocol["🔄 P2P LAN Sync Engine (Tabs, History, Downloads)"]
        LocalStorage["💾 Local JSON/SQLite Stores (OfflineStore)"]
    end

    subgraph "Paca.Core (net8.0 Shared Download Engine)"
        HlsDownloader["📥 HlsDownloader (Parallel Segment + AES-128 Decryption)"]
        DirectDownloader["📥 DirectDownloader (Resumable Chunk Stream)"]
        Parsers["🔍 M3u8Parser, DashParser, FileNameSanitizer"]
    end

    UI --> NativeBridge
    UI --> TabModel
    UI --> HistModel
    NativeBridge --> SniffEngine
    Service --> HlsDownloader
    Service --> DirectDownloader
    SyncProtocol --> TabModel
    SyncProtocol --> HistModel
    SniffEngine --> Parsers
```

---

## 3. ⚡ 3중 비디오 스니핑 & 인앱 다운로드 메커니즘

### 3.1 1단계: 네트워크 레벨 스트림 가로채기 (Android `ShouldInterceptRequest`)
- `WebViewClient`를 확장하여 네트워크 요청 URI 및 MIME Type 실시간 감시:
  - **HLS**: `.m3u8`, `application/x-mpegURL`, `application/vnd.apple.mpegurl`
  - **DASH**: `.mpd`, `application/dash+xml`
  - **Direct**: `.mp4`, `.webm`, `video/mp4`, `video/webm`
- 요청 헤더(`User-Agent`, `Referer`, `Cookie`, `Authorization`)를 함께 캡처하여 동일한 세션 권한으로 다운로드 보장.

### 3.2 2단계: DOM 인젝션 스니퍼 브릿지 (`paca_sniffer.js`)
- 페이지 로드 완료 시 인젝션되어 다음을 실시간 감지:
  1. `MutationObserver`로 동적 생성되는 `<video>`, `<audio>` 태그 감지.
  2. `HTMLMediaElement.prototype.play` 및 `onloadedmetadata` 후킹으로 `currentSrc`, `videoWidth`, `videoHeight`, `duration` 추출.
  3. `window.URL.createObjectURL` 후킹으로 `blob:` 스트림 가로채기.
  4. 웹페이지 `<title>`, 메타 태그(`og:title`, `og:image`) 추출 후 C# 네이티브 브릿지(`window.pacaBridge.postMessage`)로 전송.

### 3.3 3단계: 순수 C# 고속 다운로드 & AES-128 복호화 엔진
- `Paca.Core.Hls.HlsDownloader` 재사용:
  - 다중 연결 청크 세그먼트 병렬 다운로드 (`SemaphoreSlim(4~8)`).
  - `#EXT-X-KEY` AES-128 실시간 복호화 (`System.Security.Cryptography.Aes`).
  - 외부 파이썬이나 바이너리 없이 순수 C# 메모리/디스크 병합으로 `.mp4` 생성.
- **저장소 위치**:
  - Android: `MediaStore.Downloads` 또는 `Movies/Paca` (Scoped Storage 권한 불필요).
  - iOS: 앱 샌드박스 Documents/Downloads + UIActivityViewController 공유 시트.

---

## 4. 🎨 Designpaca 모바일 브라우저 UI/UX 스펙

### 4.1 와이어프레임

```
┌──────────────────────────────────────────────────────────┐  StatusBar (Dark #0B0C10)
│  🔒 https://m.youtube.com/watch?v=...         🔄  ⬇️ (2)  │  Top Omnibox (Height: 48dp)
├──────────────────────────────────────────────────────────┤
│ ════════════════════════════════════════════════════════ │  Page Load Progress Bar (#5E56E8)
│                                                          │
│                                                          │
│             🌐 모바일 풀 웹뷰 브라우징 화면               │
│             - 터치 제스처 (스와이프 탐색)                │  Full WebView Content Area
│             - 고화질 비디오 재생 & PiP                   │
│             - 데스크톱 모드 토글 지원                    │
│                                                          │
│                                                          │
├──────────────────────────────────────────────────────────┤
│  ◀ 뒤로    ▶ 앞으로    🏠 홈    ⬇️ 다운로드    📑 탭(3)   ⋯ 메뉴 │  Floating Bottom Bar (Height: 56dp)
└──────────────────────────────────────────────────────────┘
```

### 4.2 핵심 디자인 토큰
- **캔버스 배경**: `#0B0C10` (Dark Obsidian Deep Canvas)
- **서피스 레벨 1 (주소창 & 하단바)**: `#161822` (Glassmorphism Blur, Border: `#222438`)
- **액센트 컬러**: `#5E56E8` (Primary Indigo Neon) & `#10B981` (Video Sniffer Pulse Emerald)
- **명도 대비**: WCAG 2.1 AAA 기준 만족 (텍스트 대비 >= 7.0:1)
- **터치 타겟**: 모든 툴바 아이콘 및 버튼 폭/높이 >= **48dp** 보장

---

## 5. 🔄 선택적 PC P2P 동기화 프로토콜 (LocalSend 방식)

```
[ 모바일 브라우저 ]                           [ 데스크톱 PACA 앱 ]
       │                                              │
       ├──── QR 코드 스캔 (IP:Port + Bearer Token) ───►│ (페어링 완료)
       │                                              │
       ├──── GET /api/sync/tabs (열려있는 탭 조회) ────►│
       │◄─── 200 OK (List<TabSyncItem>) ──────────────┤
       │                                              │
       ├──── POST /api/sync/history (방문기록 병합) ───►│
       │◄─── 200 OK (Merged History) ─────────────────┤
       │                                              │
       ├──── GET /api/sync/downloads (다운로드 조회) ──►│
       │◄─── 200 OK (List<DownloadRecord>) ───────────┤
```

- **무서버 순수 로컬 P2P**: 외부 클라우드나 계정 가입 없이 LAN/Tailscale 내에서 직접 통신.
- **모바일 절전 친화적**: 지속적인 웹소켓 연결 대신, 필요할 때만 가볍게 호출하는 REST 트랜잭션.

---

## 6. 🧪 TDD RED/GREEN 검증 매트릭스

| 영역 | 검증 스위트 | 검증 내용 |
|---|---|---|
| **모바일 탭 매니저** | `MobileTabManagerTests.cs` | 탭 추가/삭제/전환, InPrivate 세션 분리, 탭 복원 |
| **비디오 스니퍼** | `VideoSnifferTests.cs` | m3u8/mp4/blob URL 매칭, DOM 페이로드 파싱, 화질 분류 |
| **인앱 다운로더** | `MobileDownloaderTests.cs` | 로컬 파일 생성, 진행률 계산, 일시정지/취소, HLS 병합 |
| **히스토리 & 북마크** | `MobileHistoryBookmarkTests.cs` | CRUD 라운드트립, 검색 필터링, 원자적 JSON 영속화 |
| **P2P 동기화** | `MobileSyncEngineTests.cs` | 탭/히스토리 JSON 페이로드 직렬화, 토큰 인증, 양방향 병합 |
| **디자인 & 터치 게이트** | `MobileVisualGateTests.cs` | WCAG AAA 명도 대비, 터치 타겟(>=48dp), 반응형 뷰포트 |

---

## 7. 🚀 단계별 구현 로드맵 (Milestones)

- [x] **Phase 1: 모바일 코어 도메인 확장 (`Paca.Mobile.Core`) (2026-08-31 완료)**
  - `BrowserTab`, `MobileTabManager`, `HistoryItem`, `BookmarkItem` 모델 및 영속 스토어 구현 완료.
  - `VideoSniffResult`, `VideoSnifferParser` 구현 완료.
  - `MobileDownloadEngine` (순수 C# HLS/MP4 병렬 스트림 다운로드 엔진) 구현 완료.
  - `Paca.Tests`에 단위/스펙 테스트 작성 (100% GREEN 통과).
- [x] **Phase 2: 모바일 브라우저 메인 UI 구축 (`Paca.Mobile`) (2026-08-31 완료)**
  - `BrowserPage.cs` (상단 옴니박스 + 풀 웹뷰 + 하단 글래스 툴바) 구현 완료.
  - `NewTabPage.cs` (자주 찾는 사이트 그리드 + 빠른 검색) 구현 완료.
  - `TabManagerPage.cs` (멀티 탭 그리드 카드 스위처) 구현 완료.
- [x] **Phase 3: 인앱 비디오 스니퍼 & 다운로드 UI 연동 (2026-08-31 완료)**
  - Android WebView 핸들러에 `SnifferScript.cs` 브릿지 주입 완료.
  - 감지 뱃지 애니메이션 및 다운로드 모달(`VideoSnifferModal.cs`) 구현 완료.
  - 로컬 기기 저장소(`Movies/Paca` 및 로컬 앱 데이터) 다운로드 파이프라인 연결 완료.
- [x] **Phase 4: 방문 기록, 북마크 & P2P 동기화 UI 구축 (2026-08-31 ~ 2026-09-04 완료)**
  - `HistoryBookmarksPage.cs` (방문 기록 및 북마크 탭 뷰) 구현 완료.
  - `SyncSettingsPage.cs` (LAN 자동 발견, 수동 IP 페어링, PacaDrop 연동) 구현 완료.
- [x] **Phase 5: 모바일 독립형 브라우징·미디어 재생·세션 영속화 완벽 무결성 (2026-09-04 완료)**
  - YouTube 등 대형 플랫폼 인앱 웹뷰 차단 원천 우회 (`PacaAndroidWebViewCustomizer` - `X-Requested-With` 헤더 제거).
  - 미디어 재생 및 브라우저 스푸핑 엔진 (`MediaPlaybackBypassScript.cs` - `navigator.vendor`, `playsinline` 자동 주입).
  - 쿠키 및 세션 영속화 (`FlushCookies()`, DomStorage, DatabaseEnabled).
  - 데스크톱/모바일 UA 스위처, 안드로이드 HW Back 키 수명주기 가드(Gate 177), 풀스크린 비디오 오버레이(Gate 178) 완비.