아키텍처

 ┌────────────────────────────────────────────┐
 │ https://chzzk.naver.com/*                  │
 │  URL 조건만 확인합니다. DOM 접근이 없습니다.  │
 └───────────────────┬────────────────────────┘
                     │ 툴바 아이콘 클릭
                     ▼
 ┌────────────────────────────────────────────┐
 │ Background Service Worker                  │
 │  · declarativeContent 규칙 등록             │
 │  · Finder 새 탭 생성                        │
 │  · 설치·업데이트 시 설정 마이그레이션         │
 │  · 데이터 탐색은 하지 않습니다.               │
 └───────────────────┬────────────────────────┘
                     │ chrome.tabs.create
                     ▼
 ┌────────────────────────────────────────────┐
 │ Finder Extension Page (React)              │
 │  UI ─ Reducer ─ Selectors                  │
 │        │                                   │
 │        ├─ Discovery Orchestrator           │
 │        │    ├─ Request Budget              │
 │        │    ├─ Follower Resolver           │
 │        │    └─ Chzzk Client (schema/adapter)│
 │        └─ chrome.storage (설정 · 캐시)       │
 └───────────────────┬────────────────────────┘
                     │ HTTPS 읽기 전용 GET
                     ▼
 ┌────────────────────────────────────────────┐
 │ https://api.chzzk.naver.com/service/v1/*   │
 │  치지직 웹 클라이언트용 비공식 응답            │
 └────────────────────────────────────────────┘

Background → Finder : 새 탭 생성만
Finder → Storage    : 설정·캐시 읽기/쓰기
Finder → CHZZK API  : 직접 fetch

                     finder/  (React UI · Reducer · Selectors)
                          │
                          │ 호출
                          ▼
                  application/  (오케스트레이션 · 예산 · 팔로워 큐)
                          │
                          │ 호출
                          ▼
   ┌──────────────────► domain/ ◄──────────────────┐
   │                (순수 규칙 · 모델)                │
   │  의존                                      변환  │
   │                                                 │
shared/  (상수 · URL 검증)              infrastructure/
                                    (fetch · zod · chrome.storage)

function selectStrategy(settings: FinderSettings): ScanStrategy {
  return settings.viewerFilter.enabled ? "viewer-tail" : "latest";
}

// infrastructure/chzzk-web/endpoints.ts
function seedCursorForViewerCeiling(viewerMax: number): LiveCursor {
  return { concurrentUserCount: viewerMax + 1, liveId: 0 };
}

서버 기본 정렬 = 시청자 수 내림차순 (전체 라이브)

  12,431명  ┐
   ...      │  관심 없는 구간.
      11명  ┘  시드 커서 덕분에 이 구간은 한 페이지도 받지 않습니다.
 ─────────────  시드 커서 = (viewerMax + 1, 0)   ※ 예: viewerMax = 10
      10명  ┐
       ...  │  조건 만족 구간. 받아 온 항목이 전부 결과 후보가 됩니다.
       0명  ┘
 ─────────────  page.next == null → coverage.exhausted = true

// application/discovery-events.ts
function computeViewerFrontier(nextCursor: LiveCursor | null): number {
  return nextCursor === null ? 0 : nextCursor.concurrentUserCount + 1;
}

시작 시각 내림차순 (전체 라이브)

  방금 시작  ┐
    ...     │  예산이 닿는 만큼만 훑습니다.
            │  각 후보의 팔로워 수는 채널을 따로 조회해야 알 수 있습니다.
  예산 소진  ┘
 ─────────────  아래는 보지 못했습니다 → 항상 partial
    ...

 Finder 진입 / 새로고침
        │
        ▼
 ① 캐시 확인 ─────────────► 신선하면 즉시 렌더 (dataOrigin = cache-fresh)
        │
        ▼
 ② 전략 선택 (viewer-tail | latest)
        │
        ▼
 ③ 라이브 목록 루프  ◄──── 예산: maxLivePages
        │   · 스키마 검증 → 어댑터 → StreamCandidate
        │   · 성인 방송 제외 · 중복 제거(liveId → channelId)
        │   · 커서 갱신 · coverage 갱신
        │   · 스냅샷 방출 (최소 120ms 간격)
        ▼
 ④ 팔로워 판정 (조건 ON일 때만)  ◄──── 예산: maxChannelLookups
        │   · 대상 = 성인 아님 + followerState "idle" + 시청자 상한 이하
        │   · 캐시 우선 → 남은 것만 네트워크 (동시성 4)
        │   · 하나 확정될 때마다 스냅샷 방출
        │   · 429/403/오프라인 → 남은 큐를 흘려보내고 중단
        ▼
 ⑤ 최종 필터·정렬 → 부분 결과 사유 판정 → 캐시 저장
        │
        ▼
 ⑥ resume 토큰 반환 (커서가 남아 있으면 `계속 탐색` 활성화)

// shared/constants.ts
const DISCOVERY_BUDGET = {
  maxLivePagesPerRun: 20,      // 한 번의 실행에서 받을 라이브 페이지 수
  maxChannelLookupsPerRun: 300, // 한 번의 실행에서 조회할 채널 수
  channelConcurrency: 4,        // 채널 조회 동시성
  refreshCooldownMs: 20_000,    // 수동 새로고침 쿨다운
};

팔로워 조건 OFF
  maxLivePages    = 20            (페이지당 50건 → 최대 1,000건)
  maxChannelLookups = 0

팔로워 조건 ON
  maxChannelLookups = 300
  maxLivePages      = min(20, ceil(300 / 50)) = 6
                       └─ 판정하지도 못할 후보를 잔뜩 받아 오지 않습니다.

 진입
   │
   ├─ Fresh 있음 ──► 즉시 렌더 (cache-fresh) ──► 백그라운드 갱신
   │                                              ├─ 성공 → network 로 교체
   │                                              └─ 실패 → 캐시 유지 + 오류 배지
   ├─ Stale만 있음 ► 즉시 렌더 (cache-stale)  ──► 백그라운드 갱신
   │                 "이전 데이터 · 8분 전 갱신"    ├─ 성공 → network 로 교체
   │                                              └─ 실패 → 이전 데이터 고지 유지
   └─ 없음 ────────► Skeleton ─────────────────► 성공 → 실시간 결과
                                                 실패 → Error State

 followerHalt == RATE_LIMITED                    → "rate-limit"
 followerHalt == NETWORK_OFFLINE                 → "network"
 errorCode    == RATE_LIMITED                    → "rate-limit"
 errorCode    == NETWORK_OFFLINE | REQUEST_TIMEOUT → "network"
 라이브 페이지 요청 실패                            → "network"
 예산 때문에 시도조차 못한 채널 있음                 → "channel-budget"
 예산 소진 + 다음 커서 남음                         → "page-budget" | "channel-budget"
 전략 == latest                                   → "latest-strategy"
 그 외                                            → null  (완전 탐색)

 후보 0건 + errorCode 있음        → "error"
 partialReason 또는 errorCode 있음 → "partial"
 그 외                            → "ready"

// domain/settings.ts
function enforceSettingsInvariants(settings: FinderSettings): FinderSettings {
  const recentFirst = isBaseFilterActive(settings) && settings.recentFirst;
  if (recentFirst === settings.recentFirst) return settings;
  return { ...settings, recentFirst };
}