releases/docs/MOBILE_BROWSER_ARCHITECTURE_PLAN.md

📱 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. 🏛️ 시스템 아키텍처 및 계층 구조

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)

• Phase 1: 모바일 코어 도메인 확장 (Paca.Mobile.Core) (2026-08-31 완료)
  • BrowserTab, MobileTabManager, HistoryItem, BookmarkItem 모델 및 영속 스토어 구현 완료.
  • VideoSniffResult, VideoSnifferParser 구현 완료.
  • MobileDownloadEngine (순수 C# HLS/MP4 병렬 스트림 다운로드 엔진) 구현 완료.
  • Paca.Tests에 단위/스펙 테스트 작성 (100% GREEN 통과).
• Phase 2: 모바일 브라우저 메인 UI 구축 (Paca.Mobile) (2026-08-31 완료)
  • BrowserPage.cs (상단 옴니박스 + 풀 웹뷰 + 하단 글래스 툴바) 구현 완료.
  • NewTabPage.cs (자주 찾는 사이트 그리드 + 빠른 검색) 구현 완료.
  • TabManagerPage.cs (멀티 탭 그리드 카드 스위처) 구현 완료.
• Phase 3: 인앱 비디오 스니퍼 & 다운로드 UI 연동 (2026-08-31 완료)
  • Android WebView 핸들러에 SnifferScript.cs 브릿지 주입 완료.
  • 감지 뱃지 애니메이션 및 다운로드 모달(VideoSnifferModal.cs) 구현 완료.
  • 로컬 기기 저장소(Movies/Paca 및 로컬 앱 데이터) 다운로드 파이프라인 연결 완료.
• Phase 4: 방문 기록, 북마크 & P2P 동기화 UI 구축 (2026-08-31 ~ 2026-09-04 완료)
  • HistoryBookmarksPage.cs (방문 기록 및 북마크 탭 뷰) 구현 완료.
  • SyncSettingsPage.cs (LAN 자동 발견, 수동 IP 페어링, PacaDrop 연동) 구현 완료.
• 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) 완비.