graph LR
    A[主线程 Worker] -->|postMessage 100ms 心跳| B[Media Engine Worker]
    B -->|SharedArrayBuffer 状态同步| A
    C[Service Worker] -->|Push API / Background Fetch| D[原生推送唤醒]
    B -->|WebCodecs / WASM 编解码| E[OffscreenCanvas 编码管线]

// AudioWorkletProcessor 内部：每 10ms 输出 1 帧静音帧（128 samples @ 48kHz）
class KeepAliveProcessor extends AudioWorkletProcessor {
  process(inputs, outputs) {
    const out = outputs[0][0]; // Float32Array(128)
    out.fill(0); // 静音帧
    // 关键：向主线程上报“引擎存活”心跳
    this.port.postMessage({ type: 'heartbeat', ts: currentTime });
    return true; // 保持节点存活
  }
}
registerProcessor('keep-alive', KeepAliveProcessor);

interface ResourceQuota {
  cpuBudgetMsPerSec: number;      // 可用 CPU 时间片（ms/s）
  memoryBudgetMB: number;         // 可用内存上限
  networkPriority: 'high' | 'low'; // 网络调度优先级
  thermalState: 'nominal' | 'fair' | 'serious' | 'critical';
}

// 周期性探测（Worker 内每 500ms 采样一次）
async function probeQuota(): Promise<ResourceQuota> {
  const start = performance.now();
  // 执行定量 WASM 计算基准（如 10k 次矩阵乘法）
  await wasmBenchmark();
  const elapsed = performance.now() - start;
  const cpuBudget = Math.max(1000 - elapsed, 50); // 反推可用预算
  
  return {
    cpuBudgetMsPerSec: cpuBudget,
    memoryBudgetMB: await estimateMemory(),
    networkPriority: navigator.connection?.saveData ? 'low' : 'high',
    thermalState: (await navigator.getBattery()).level < 0.2 ? 'serious' : 'nominal'
  };
}

graph TD
    Q[资源配额探测] -->|每 500ms| R[配额评估器]
    R -->|CPU < 30%| S[降级策略 A: 降帧率/分辨率]
    R -->|CPU 30-60%| T[维持策略: 当前配置]
    R -->|CPU > 60%| U[升级策略: 升帧率/开启 FEC/Simulcast]
    S --> V[编码器重配置]
    T --> V
    U --> V
    V -->|applyConfig| W[VideoEncoder.reconfigure()]
    W --> X[QoE 指标上报]
    X --> R

// WASM 侧伪代码：根据 RTT 与丢包率动态计算 GOP 长度
int calculate_optimal_gop(int rtt_ms, float loss_rate, int cpu_budget) {
  // 基础 GOP = max(1s, RTT * 3) 保证重传窗口覆盖
  int base_gop = std::max(1000, rtt_ms * 3);
  // 丢包补偿：每 1% 丢包缩短 100ms GOP
  int loss_adj = static_cast<int>(loss_rate * 100 * 100);
  // CPU 预算修正：预算低则拉长 GOP 减少关键帧开销
  int cpu_adj = (cpu_budget < 200) ? 500 : 0;
  return std::clamp(base_gop - loss_adj + cpu_adj, 500, 5000); // 0.5s ~ 5s
}

graph TB
    L1[Layer 1: 基础 WebRTC] -->|全平台兜底| L2[Layer 2: Insertable Streams + WebCodecs]
    L2 -->|Chrome/Edge/Firefox| L3[Layer 3: WebGPU Compute Shader 预处理/后处理]
    L3 -->|支持 WebGPU 的桌面端| L4[Layer 4: 原生插件/Electron/Tauri 混合模式]
    L4 -->|企业级客户端/移动端 SDK|

// Safari 17- / 移动端 WebKit：无 VideoEncoder 时的兜底
if (!('VideoEncoder' in window)) {
  // 方案 A：Canvas + captureStream + 软编（性能差，仅作兜底）
  // 方案 B：引入 WASM 版 libvpx / openh264（体积 +2MB，CPU 高）
  // 方案 C：引导用户下载原生客户端（推荐）
  await import('./wasm-vp8-encoder.js'); // 动态加载
  encoder = new WasmVp8Encoder({ width, height, bitrate });
}

// 关键指标上报（每 10s 一次批量发送）
interface MediaEngineMetrics {
  // 保活健康度
  backgroundDurationMs: number;      // 累计后台时长
  heartbeatMissCount: number;        // 心跳丢失次数
  audioContextStateChanges: number;  // 音频上下文状态变更
  
  // 资源博弈结果
  currentCpuBudget: number;
  activeEncodingConfig: EncodingConfig;
  gopLengthMs: number;
  keyFrameIntervalActual: number;
  
  // QoE 结果
  freezeRate: number;                // 卡顿率
  avgLatencyMs: number;              // 端到端延迟
  reconnectCount: number;            // 重连次数
}

sequenceDiagram
    participant Client as 媒体引擎
    participant Signal as 信令网关
    participant Media as 媒体服务器(SFU/MCU)
    
    Note over Client, Media: 正常会话期
    Client->>Signal: WebSocket (主通道)
    Client->>Signal: HTTP/2 + SSE / WebTransport (备用通道)
    
    Note over Client, Media: 后台节流期 (主通道心跳漏发)
    Signal->>Client: Push API (Service Worker) 唤醒
    Client->>Signal: WebTransport 0-RTT 快速重连
    Signal->>Media: 触发 ICE Restart / Re-negotiation
    Media-->>Client: 新 Candidate + 更新 DTLS 参数
    Client->>Media: 无缝切流 (无感知重连)

enum EngineState {
  INIT = 'INIT',
  CONNECTING = 'CONNECTING',
  CONNECTED = 'CONNECTED',
  RECONNECTING = 'RECONNECTING',   // 核心：显性化重连态
  MIGRATING = 'MIGRATING',         // 网络切换/通道迁移
  SUSPENDED = 'SUSPENDED',         // 后台深度节流/冻结
  TERMINATED = 'TERMINATED'
}

// 关键转移逻辑：RECONNECTING 复用现有 PeerConnection 对象
async function handleReconnect(signal: SignalClient) {
  // 1. 保留本地 Track / Transceiver / DataChannel 引用
  const localTracks = pc.getSenders().map(s => s.track).filter(Boolean);
  
  // 2. 触发 ICE Restart (仅重新收集 Candidate，不重建 DTLS)
  await pc.restartIce();
  
  // 3. 创建 Offer (包含 ICE restart 标记)
  const offer = await pc.createOffer({ iceRestart: true });
  await pc.setLocalDescription(offer);
  
  // 4. 信令交换 (复用 WebTransport 流)
  const answer = await signal.exchange({ type: 'reconnect', sdp: offer.spc });
  await pc.setRemoteDescription(answer);
  
  // 5. 状态机流转：RECONNECTING -> CONNECTED
  stateMachine.transition(EngineState.CONNECTED);
}

// WASM 发送端调度器伪代码
class BandwidthEstimator {
  // 节流感知探测：利用 Worker 高精度定时器发送探测包簇
  void onProbeTimer() {
    if (state_ == PROBING) {
      // 构造 Probe Cluster: 5 个 1200B 包，间隔 1ms (模拟 48Mbps 突发)
      sendProbeCluster(5, 1200, 1); 
      // 关键：记录发送墙钟时间 (performance.timeOrigin + performance.now())
      probeClusterId_ = generateId();
      probeSendTime_[probeClusterId_] = getHighResTime(); 
    }
  }

  // 接收 TWCC 反馈时修正
  void onTransportFeedback(const FeedbackPacket& fb) {
    if (fb.packet_ids.contains(probeClusterId_)) {
      // 计算单程延迟梯度 (OWD trend) -> 推导瓶颈带宽
      double bw = calculateBweFromProbe(fb);
      // 融合 GCC 估计值 (加权: 节流期信任主动探测 70%)
      estimatedBw_ = 0.7 * bw + 0.3 * gccEstimate_;
      updateEncoderTargetBitrate(estimatedBw_);
    }
  }
};

// 接收端 TransformStream：修正被节流延迟的包到达时间
const timestampCorrector = new TransformStream({
  transform(controller, frame) {
    // frame: RTCTransformableFrame (RTCEncodedVideoFrame / RTCEncodedAudioFrame)
    const now = performance.now();
    // 关键修正：若检测到主线程阻塞 (now - frame.timestamp > 50ms)
    // 则用 "预期到达时间" 覆盖 "实际到达时间" 上报给发送端
    const correctedTimestamp = estimateTrueArrivalTime(frame, now);
    
    // 重新封装 RTCP Transport Feedback (TWCC) 元数据
    // 注意：需配合 RTCRtpScriptSender 发送自定义 RTCP 包
    sendTwccFeedback(frame.sequenceNumber, correctedTimestamp);
    
    controller.enqueue(frame); // 透传给解码器
  }
});

// 注入管线
const receiver = pc.getReceivers()[0];
const { readable, writable } = new RTCRtpScriptTransform(receiver);
readable.pipeThrough(timestampCorrector).pipeTo(writable);

// Android 原生层注入：绕过 WebView 节流
public class MediaWebViewClient extends WebViewClient {
    @Override
    public void onPageFinished(WebView view, String url) {
        // 1. 禁用 WebView 自身的计时器节流 (需 API 24+)
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
            WebView.setWebContentsDebuggingEnabled(true); // 触发特定内核路径
        }
        
        // 2. 注入原生 MediaCodec 编解码桥接对象
        view.addJavascriptInterface(new MediaCodecBridge(context), "NativeMedia");
        
        // 3. 设置优先级提升 (需系统签名或 Root)
        // Process.setThreadPriority(Process.THREAD_PRIORITY_URGENT_AUDIO);
    }
}

// JS 侧调用原生硬编
class NativeEncoder {
  async init(config) { return await NativeMedia.initEncoder(JSON.stringify(config)); }
  async encode(frame) { 
    // VideoFrame -> ImageBitmap -> 原生纹理 ID (零拷贝)
    const textureId = await NativeMedia.importFrame(frame); 
    return await NativeMedia.encode(textureId, frame.timestamp); 
  }
}

// Tauri (Rust) 侧：原生媒体引擎核心
#[tauri::command]
async fn start_native_engine(config: EngineConfig, window: Window) -> Result<(), String> {
    // 1. 启动独立媒体进程 (隔离崩溃、独立 CPU 调度优先级)
    let (tx, mut rx) = mpsc::channel::<MediaEvent>(100);
    
    std::thread::spawn(move || {
        let runtime = tokio::runtime::Builder::new_current_thread()
            .enable_all()
            .build()
            .unwrap();
        
        runtime.block_on(async {
            let mut engine = MediaEngine::new(config).await?;
            // 关键：监听前端指令 (编码参数动调、关键帧请求)
            while let Some(cmd) = rx.recv().await {
                engine.handle_command(cmd).await;
            }
            Ok::<_, Error>(())
        })
    });
    
    // 2. 事件回传前端 (统计、首帧、错误)
    tauri::async_runtime::spawn(async move {
        while let Some(event) = rx.recv().await {
            window.emit("media-event", event).unwrap();
        }
    });
    Ok(())
}

// 埋点上报前的合规处理中间件
class TelemetrySanitizer {
  // 敏感字段白名单机制
  private static readonly ALLOWED_FIELDS = new Set([
    'cpu_budget', 'memory_usage', 'bitrate', 'fps', 'rtt', 
    'packet_loss', 'freeze_rate', 'encoder_name', 'browser_version'
  ]);
  
  // 严禁上报字段黑名单
  private static readonly FORBIDDEN_PATTERNS = [
    /user_?id/i, /device_?id/i, /ip_?address/i, /mac_?addr/i,
    /meeting_?id/i, /room_?id/i, /token/i, /cookie/i
  ];

  static sanitize(raw: MediaEngineMetrics): SafeMetrics {
    const safe: Record<string, any> = {};
    
    for (const [key, value] of Object.entries(raw)) {
      // 1. 字段名合规性校验
      if (!this.ALLOWED_FIELDS.has(key)) continue;
      if (this.FORBIDDEN_PATTERNS.some(r => r.test(key))) continue;
      
      // 2. 数值泛化 (K-匿名 / 差分隐私)
      if (typeof value === 'number') {
        safe[key] = this.generalizeNumeric(key, value);
      } else if (typeof value === 'string') {
        safe[key] = this.hashOrBucket(value); // 版本号 -> "Chrome 120" -> "Chrome 12x"
      }
    }
    
    // 3. 注入差分隐私噪声 (Laplace 机制, ε=0.5)
    return this.addDpNoise(safe);
  }
  
  private static generalizeNumeric(key: string, val: number): number {
    // 码率分桶: 100kbps 粒度; 延迟分桶: 10ms 粒度
    const buckets: Record<string, number> = {
      'bitrate': 100_000, 'rtt': 10, 'cpu_budget': 10
    };
    const bucket = buckets[key] || 1;
    return Math.round(val / bucket) * bucket;
  }
}

graph LR
    A[采集 Track] --> B[E2EE 加密器 Worker]
    B -->|加密帧 SFrame| C[RTCPeerConnection]
    C -->|网络传输| D[接收端 PeerConnection]
    D -->|加密帧| E[E2EE 解密器 Worker]
    E -->|明文帧| F[WebCodecs 解码器 Worker]
    F --> G[渲染]
    
    H[密钥管理服务 KMS] -.->|MLS Epoch/Key| B
    H -.->|MLS Epoch/Key| E

flowchart TD
    Start[丢包率 > 2%?] -->|否| NoFEC[无 FEC, 仅 RTX/NACK]
    Start -->|是| CheckRTT{RTT < 150ms?}
    CheckRTT -->|是| CheckBurst{丢包是否突发?}
    CheckBurst -->|是| FlexFEC[FlexFEC 保护组: K=4, D=1<br>开销 25%, 恢复延迟 1帧]
    CheckBurst -->|否| RED[RED 冗余编码<br>开销 50-100%, 恢复延迟 0]
    CheckRTT -->|否| RED[RED + 降码率<br>避免 FEC 反馈延迟导致无效]

// Rust -> WASM: 视频 PLC 核心逻辑 (编译为 wasm 引入 Worker)
#[wasm_bindgen]
pub struct VideoPlc {
    last_good_frame: Vec<u8>,      // YUV420P
    last_mv_buffer: Vec<i16>,      // 运动矢量场
    concealment_count: u32,
}

#[wasm_bindgen]
impl VideoPlc {
    // 正常帧到达：更新参考帧与运动矢量
    pub fn on_frame_received(&mut self, yuv: &[u8], mvs: &[i16]) {
        self.last_good_frame.copy_from_slice(yuv);
        self.last_mv_buffer.copy_from_slice(mvs);
        self.concealment_count = 0;
    }

    // 丢包触发：生成隐藏帧
    pub fn generate_concealment(&mut self, width: u32, height: u32) -> Vec<u8> {
        self.concealment_count += 1;
        
        if self.concealment_count > 5 {
            // 连续丢包过多：输出冻结帧 + 灰度化提示
            return self.freeze_frame_gray(width, height);
        }

        // 核心算法：运动矢量外推 + 边界平滑
        let mut concealed = vec![0u8; (width * height * 3 / 2) as usize];
        
        // 1. 运动补偿预测 (简化版: 块级 MV 平均)
        motion_compensation(
            &self.last_good_frame, 
            &self.last_mv_buffer, 
            &mut concealed, 
            width, height
        );
        
        // 2. 边界伪影抑制 (双边滤波近似)
        bilateral_filter_fast(&mut concealed, width, height);
        
        // 3. 随机噪声注入 (防止静止区域“贴纸感")
        add_dither(&mut concealed, 2.0);
        
        concealed
    }
}

// shared/ring-buffer.ts
// 基于 SharedArrayBuffer + Atomics 的 SPSC (单生产单消费) 队列
export class LockFreeRingBuffer<T extends Transferable> {
  private readonly buffer: SharedArrayBuffer;
  private readonly slots: Uint32Array; // 存储索引/偏移量
  private readonly head: Int32Array;   // 生产者位置 (Atomics)
  private readonly tail: Int32Array;   // 消费者位置 (Atomics)
  private readonly capacity: number;

  constructor(capacity: number = 64) {
    this.capacity = capacity;
    // 元数据区: head(4B) + tail(4B) + slots(capacity * 4B)
    const metaSize = 8 + capacity * 4;
    // 数据区: 由外部管理 Transferable 对象池，此处仅传索引
    this.buffer = new SharedArrayBuffer(metaSize);
    this.head = new Int32Array(this.buffer, 0, 1);
    this.tail = new Int32Array(this.buffer, 4, 1);
    this.slots = new Uint32Array(this.buffer, 8, capacity);
  }

  // 生产者: 编码器 Worker
  push(item: T): boolean {
    const h = Atomics.load(this.head, 0);
    const next = (h + 1) % this.capacity;
    if (next === Atomics.load(this.tail, 0)) return false; // 满
    
    // 关键：将 Transferable 对象存入全局对象池，仅写入索引
    const idx = ObjectPool.store(item); 
    this.slots[h] = idx;
    
    Atomics.store(this.head, 0, next);
    Atomics.notify(this.head, 0, 1); // 唤醒消费者
    return true;
  }

  // 消费者: 网络发送 Worker
  pop(): T | null {
    const t = Atomics.load(this.tail, 0);
    if (t === Atomics.load(this.head, 0)) return null; // 空
    
    const idx = this.slots[t];
    const item = ObjectPool.take(idx); // 取出并释放池位
    
    Atomics.store(this.tail, 0, (t + 1) % this.capacity);
    return item;
  }
}

// 编码器状态机：编译期保证非法转移不可通过类型检查
type EncoderState = 
  | { status: 'IDLE' }
  | { status: 'INITIALIZING'; config: EncoderConfig }
  | { status: 'RUNNING'; config: EncoderConfig; frameCount: number }
  | { status: 'RECONFIGURING'; oldConfig: EncoderConfig; newConfig: EncoderConfig }
  | { status: 'FLUSHING'; reason: 'RECONFIG' | 'SHUTDOWN' }
  | { status: 'ERROR'; error: Error; recoverable: boolean };

type EncoderEvent =
  | { type: 'INIT'; config: EncoderConfig }
  | { type: 'CONFIGURE'; config: EncoderConfig }
  | { type: 'ENCODE'; frame: VideoFrame }
  | { type: 'FLUSH'; reason: 'RECONFIG' | 'SHUTDOWN' }
  | { type: 'RESET' }
  | { type: 'ERROR'; error: Error };

// 纯函数转移：易于单测、模糊测试、形式化验证
function encoderTransition(state: EncoderState, event: EncoderEvent): EncoderState {
  switch (state.status) {
    case 'IDLE':
      if (event.type === 'INIT') return { status: 'INITIALIZING', config: event.config };
      throw invalidTransition(state, event);
    case 'INITIALIZING':
      if (event.type === 'ERROR') return { status: 'ERROR', error: event.error, recoverable: false };
      // ... 其它分支
    // TypeScript 会强制覆盖所有 case，漏写即报错
  }
}

# .github/workflows/chaos-media-engine.yml
jobs:
  chaos-test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        scenario:
          - name: "Background Throttle 60s"
            script: "throttle-cpu 10% && sleep 60 && throttle-cpu 100%"
          - name: "Network Partition 5s"
            script: "tc qdisc add dev eth0 root netem loss 30% delay 500ms && sleep 5 && tc qdisc del dev eth0 root"
          - name: "OOM Killer Trigger"
            script: "stress-ng --vm 2 --vm-bytes 90% --timeout 30s"
    steps:
      - uses: actions/checkout@v4
      - name: Start Media Engine (Headless Chrome + Puppeteer)
        run: |
          node scripts/launch-engine.js --headless --config=ci.json &
          ENGINE_PID=$!
      - name: Inject Chaos
        run: ${{ matrix.scenario.script }}
      - name: Collect Metrics & Assert SLO
        run: |
          node scripts/verify-slo.js 
            --max-freeze-rate=0.05 
            --max-reconnect-latency=500 
            --min-audio-mos=4.0
      - name: Upload Artifacts (Traces, Logs, Heap Snapshots)
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: chaos-${{ matrix.scenario.name }}
          path: ./artifacts/