下載引擎架構

┌─────────────────────────────────────────────────┐
│                   下載引擎                        │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ 分片下載  │→│ 分片處理  │→│ 檔案寫入       │  │
│  │ 模組     │  │ 模組     │  │ 模組           │  │
│  │          │  │          │  │                │  │
│  │ · 並行   │  │ · 解密   │  │ · FSA 串流    │  │
│  │ · 重試   │  │ · 拼接   │  │ · StreamSaver │  │
│  │ · 限速   │  │ · 轉封裝  │  │ · Blob 兜底   │  │
│  └──────────┘  └──────────┘  └───────────────┘  │
│                                                  │
│  ┌─────────────────────────────────────────────┐ │
│  │              記憶體安全管理器                │ │
│  │  · 大小預估  · 閾值檢查  · 策略選擇         │ │
│  └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

使用者點擊下載
    │
    ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ 1. 清單解析   │ ──→ │ 2. 分片下載   │ ──→ │ 3. 分片處理   │
│              │     │              │     │              │
│ · 下載 M3U8  │     │ · Worker Pool│     │ · AES 解密   │
│ · 解析分片列表│     │ · 並行控制   │     │ · TS 拼接    │
│ · 提取金鑰   │     │ · 指數退避   │     │ · FFmpeg 轉封│
│ · 預估大小   │     │ · 進度上報   │     │ · 音影片合併  │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
                                                  ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ 6. 完成通知   │ ←── │ 5. 清理回收   │ ←── │ 4. 檔案寫入   │
│              │     │              │     │              │
│ · 桌面通知   │     │ · 釋放記憶體 │     │ · FSA 串流   │
│ · 路徑複製   │     │ · 清理暫存檔 │     │ · StreamSaver│
│ · 佇列推進   │     │ · 重設狀態   │     │ · Blob 兜底  │
└──────────────┘     └──────────────┘     └──────────────┘

  [閒置]
    │ 使用者觸發下載
    ▼
  [初始化] ──── 載入 WASM、檢查 API 可用性、選擇寫入策略
    │
    ▼
  [清單解析] ── 下載並解析 M3U8/MPD，提取分片列表和金鑰
    │
    ▼
  [分片下載] ── Worker Pool 並行下載，即時上報進度
    │
    ▼
  [分片處理] ── 解密 → 拼接/轉封裝 → 寫入磁碟
    │
    ├── 成功 → [清理] → [完成] → [閒置]
    │
    ├── 取消 → [清理] → [閒置]
    │
    └── 失敗 → [清理] → [錯誤] → [閒置]

const downloadSegmentsConcurrently = async (
  segments: SegmentInfo[],
  onSegmentDownloaded: (buffer: ArrayBuffer, index: number) => void
) => {
  const concurrency = Math.min(config.concurrency, 8)
  let nextIndex = 0

  const worker = async () => {
    while (nextIndex < segments.length) {
      const index = nextIndex++
      const buffer = await downloadWithRetry(segments[index]!)
      onSegmentDownloaded(buffer, index)
    }
  }

  const workers = Array.from(
    { length: Math.min(concurrency, segments.length) },
    () => worker()
  )
  await Promise.all(workers)
}

預先分片（不推薦）：
Worker 1: [分片 0-49]   ← 如果這些分片較大，Worker 1 成為瓶頸
Worker 2: [分片 50-99]  ← 可能提前完成，然後閒置等待

共享計數器（FlowPick 採用）：
Worker 1: 分片 0 → 分片 3 → 分片 5 → ...
Worker 2: 分片 1 → 分片 4 → 分片 7 → ...
Worker 3: 分片 2 → 分片 6 → 分片 8 → ...

async function* segmentGenerator(
  segments: SegmentInfo[],
  signal?: AbortSignal
): AsyncGenerator<ArrayBuffer> {
  for (const segment of segments) {
    if (signal?.aborted) break
    const buffer = await downloadWithRetry(segment)
    yield buffer
  }
}

const downloadWithRetry = async (
  segment: SegmentInfo,
  maxRetries = 3
): Promise<ArrayBuffer> => {
  let lastError: unknown
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await downloadAndDecryptSegment(segment)
    } catch (e) {
      lastError = e
      if (attempt < maxRetries - 1) {
        // 指數退避：400ms, 800ms, 1600ms
        await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 400))
      }
    }
  }
  throw lastError
}

class FetchError extends Error {
  constructor(
    message: string,
    public status: number,
    public url: string
  ) {
    super(message)
    this.name = 'FetchError'
  }
}

const decryptAES128 = async (
  encryptedData: ArrayBuffer,
  key: ArrayBuffer,
  iv?: Uint8Array
): Promise<ArrayBuffer> => {
  const keyBytes = await crypto.subtle.importKey(
    'raw', key,
    { name: 'AES-CBC' },
    false,
    ['decrypt']
  )

  const ivBuffer = iv ? new Uint8Array(iv) : new Uint8Array(16)

  const decrypted = await crypto.subtle.decrypt(
    { name: 'AES-CBC', iv: ivBuffer },
    keyBytes,
    encryptedData
  )

  return decrypted
}

// 虛擬碼
const merged = new Uint8Array(totalSize)
let offset = 0
for (const segment of segments) {
  merged.set(new Uint8Array(segment), offset)
  offset += segment.byteLength
}

HLS 串流處理：
  分片 0 → 分片 1 → 分片 2 → ... → 拼接 → 輸出

DASH 串流處理（音影片分離）：
  初始化段 → 影片分片 0 → 影片分片 1 → ... ─┐
                                              ├→ FFmpeg 合併 → 輸出
  初始化段 → 音訊分片 0 → 音訊分片 1 → ... ─┘

async function createFSAStream(
  filename: string,
  dirHandle?: FileSystemDirectoryHandle | null
): Promise<WritableStream<Uint8Array>> {
  let handle: FileSystemFileHandle

  if (dirHandle) {
    // 已有目錄權限，直接建立檔案
    handle = await dirHandle.getFileHandle(filename, { create: true })
  } else {
    // 彈窗讓使用者選擇儲存位置
    handle = await window.showSaveFilePicker!({
      suggestedName: filename,
      types: [{
        description: 'Video',
        accept: { 'video/mp4': ['.mp4'] }
      }]
    })
  }

  const writable = await handle.createWritable()

  return new WritableStream<Uint8Array>({
    async write(chunk) { await writable.write(chunk) },
    async close() { await writable.close() },
    async abort(reason) { await writable.abort(reason) }
  }, {
    highWaterMark: 16 * 1024 * 1024 // 16MB 緩衝區
  })
}

async function createStreamSaverStream(
  filename: string,
  fileSize?: number
): Promise<WritableStream<Uint8Array>> {
  const ss = await getStreamSaver()
  const fileStream = ss.createWriteStream(filename, { size: fileSize })
  return fileStream
}

// 虛擬碼
const blob = new Blob([mergedData], { type: 'video/mp4' })
const url = URL.createObjectURL(blob)
const a = document.createElement('a')
a.href = url
a.download = filename
a.click()
URL.revokeObjectURL(url)

async function estimateSegmentsSize(
  segments: ArrayBuffer[] | AsyncGenerator<ArrayBuffer>,
  totalCount: number
): Promise<{ estimatedSize: number; isEstimate: boolean }> {
  // 取樣數量：min(5, max(1, totalCount * 0.1))
  const sampleCount = Math.min(5, Math.max(1, Math.floor(totalCount * 0.1)))

  // 下載前幾個分片並計算平均大小
  let sampledTotal = 0
  for (let i = 0; i < sampleCount; i++) {
    sampledTotal += sampleSegment.byteLength
  }

  const avgSample = sampledTotal / sampleCount
  return {
    estimatedSize: Math.round(avgSample * totalCount),
    isEstimate: true
  }
}

預估大小 < 800MB  → 任意策略均可
預估大小 800MB-1.5GB → 優先串流寫入，Blob 模式顯示警告
預估大小 > 1.5GB → 強制串流寫入，Blob 模式拒絕

const MEMORY_CONFIG = {
  maxBlobSize: 1500 * 1024 * 1024,    // 1.5GB 硬限制
  warnBlobSize: 800 * 1024 * 1024,    // 800MB 警告閾值
}

const checkMemoryPressure = (): 'normal' | 'warning' | 'critical' => {
  // 檢查目前已分配的分片緩衝區總大小
  const allocatedMB = allocatedBuffers.reduce((sum, buf) => sum + buf.byteLength, 0) / 1048576

  if (allocatedMB > 1200) return 'critical'
  if (allocatedMB > 600) return 'warning'
  return 'normal'
}

const updateSpeedAndTime = () => {
  const elapsed = (Date.now() - downloadStartTime) / 1000
  const bytesPerSecond = downloadedBytes / elapsed

  // 格式化速度顯示
  if (bytesPerSecond > 1024 * 1024) {
    speed = `${(bytesPerSecond / 1048576).toFixed(1)} MB/s`
  } else if (bytesPerSecond > 1024) {
    speed = `${(bytesPerSecond / 1024).toFixed(1)} KB/s`
  } else {
    speed = `${bytesPerSecond.toFixed(0)} B/s`
  }
}

剩餘時間 = (剩餘分片數 × 平均分片大小) / 目前速度

export interface StreamMergeProgress {
  phase: 'downloading' | 'merging'
  percent: number
  downloadedBytes: number
  totalBytes: number
  speed: string
  eta: string
}

// 選擇目錄並請求持久化權限
async function pickSaveDirectory(): Promise<string | null> {
  const handle = await window.showDirectoryPicker!({
    mode: 'readwrite',
    id: 'flowpick-save-dir',
    startIn: 'downloads'
  })

  const permissionState = await handle.requestPermission({
    mode: 'readwrite'
  })

  if (permissionState === 'granted') {
    savedDirHandle = handle
    localStorage.setItem('flowpick_save_dir_name', handle.name)
    return handle.name
  }
}

async function checkSavedDirPermission(): Promise<boolean> {
  if (!savedDirHandle) return false

  try {
    const status = await navigator.permissions.query({
      name: 'file-system',
      handle: savedDirHandle
    })
    return status.state === 'granted'
  } catch {
    // query 失敗時用實際操作測試
    const testFile = await savedDirHandle
      .getFileHandle(`__fp_test_${Date.now()}__`, { create: true })
    const w = await testFile.createWritable()
    await w.close()
    return true
  }
}

首次使用：
  使用者點擊「選擇目錄」 → showDirectoryPicker() 彈窗 → 使用者選擇 → 權限授予 → 快取控制代碼

再次開啟頁面：
  讀取快取的目錄名稱 → permissions.query() 靜默檢查 → 權限有效 → 直接使用

權限失效時：
  permissions.query() 回傳 'denied' → 清除快取 → 提示使用者重新選擇目錄

export interface StreamMergeOptions {
  segments: ArrayBuffer[] | AsyncGenerator<ArrayBuffer>
  totalSegments: number
  filename: string
  outputFormat?: 'mp4' | 'ts'
  onProgress?: (progress: StreamMergeProgress) => void
  signal?: AbortSignal  // 取消訊號
}

使用者點擊取消
    │
    ▼
1. signal.abort() 觸發
    │
    ▼
2. 中斷所有進行中的 fetch 請求
   └── AbortController 關聯的所有 fetch 立即拋出 AbortError
    │
    ▼
3. 停止 Worker Pool
   └── 所有 Worker 偵測到 signal.aborted，退出迴圈
    │
    ▼
4. 清理 FFmpeg 虛擬檔案系統
   └── 刪除 filelist.txt、segment_*.ts、output.* 等暫存檔案
    │
    ▼
5. 釋放已分配的記憶體緩衝區
   └── 將所有 ArrayBuffer 參考置空，等待 GC 回收
    │
    ▼
6. 丟棄不完整的檔案
   └── FSA 模式：呼叫 writable.abort()
   └── StreamSaver 模式：呼叫 writable.abort()
   └── Blob 模式：不觸發下載，直接釋放 Blob
    │
    ▼
7. 重設引擎狀態
   └── 清除進度資料、速度統計、錯誤資訊

UI 層 AbortController
    │
    ├──→ 分片下載 Worker Pool（中斷 fetch）
    ├──→ 分片處理管線（跳過剩餘分片）
    ├──→ FFmpeg WASM（終止轉封裝）
    └──→ 檔案寫入串流（abort 寫入）

並行數 1：████████████████████████████  慢，頻寬利用率低
並行數 2：██████████████████  較快，基本可用
並行數 4：██████████  快，推薦預設值
並行數 6：████████  很快，接近最優
並行數 8：████████  與 6 基本持平，邊際收益遞減
並行數 12+：████████  可能觸發 CDN 限速，反而變慢

┌─────────────────────────────────────────────┐
│                 UI 層                        │
│  · 展示使用者提示（Toast/彈窗）              │
│  · 更新下載狀態為「失敗」                    │
│  · 提供重試/回饋入口                         │
└──────────────────┬──────────────────────────┘
                   │ 捕獲所有異常
┌──────────────────▼──────────────────────────┐
│              引擎門面層                       │
│  · 統一異常格式（StreamMergeError）          │
│  · 附加上下文資訊（URL、分片索引、階段）      │
│  · 決定是否可重試                            │
└──────────────────┬──────────────────────────┘
                   │
    ┌──────────────┼──────────────┐
    ▼              ▼              ▼
┌────────┐  ┌──────────┐  ┌──────────┐
│下載模組│  │處理模組  │  │寫入模組  │
│        │  │          │  │          │
│FetchErr│  │CryptoErr │  │WriteErr  │
└────────┘  └──────────┘  └──────────┘