interface DecoderCapabilityMatrix {
  codec: VideoCodec;                    // 'vp8' | 'vp9' | 'avc' | 'hevc' | 'av1'
  profile: string;                      // 'main', 'high', 'profile0'...
  level: string;                        // '3.1', '4.0', '5.1'...
  colorSpace: VideoColorSpaceInit;      // bt709, bt2020, pq, hlg
  maxResolution: { width: number; height: number };
  maxFramerate: number;                 // 硬解器最大吞吐 fps
  hwAcceleration: 'preferred' | 'fallback' | 'unavailable';
  powerEfficiencyClass: 'high' | 'medium' | 'low'; // 移动端功耗分级
  knownIssues: string[];                // 驱动已知缺陷清单
}

stateDiagram-v2
    [*] --> PROBE: 会话初始化
    PROBE --> L0_HARDWARE: 基准测通过 & 白名单命中
    PROBE --> L1_HYBRID: 基准测边界或灰名单
    PROBE --> L2_SOFTWARE: 黑名单或基准测失败
    
    L0_HARDWARE --> L1_HYBRID: 连续 3 次 decodeError / 帧率跌破 80%
    L1_HYBRID --> L2_SOFTWARE: 连续 2 次 fallback 触发
    L1_HYBRID --> L0_HARDWARE: 网络恢复 & 热插拔重探测通过
    L2_SOFTWARE --> L1_HYBRID: 用户主动切换/设备变更重探测

class AdaptiveDecoderController {
  private tier: DecoderTier = 'L0_HARDWARE';
  private decoder: VideoDecoder | null = null;
  private resetToken = 0;
  private readonly capability: DecoderCapabilityMatrix;

  async initialize(config: DecoderInitConfig): Promise<void> {
    this.capability = await this.probeCapabilities(config.codec);
    this.tier = this.selectInitialTier(this.capability);
    await this.createDecoder(this.tier);
  }

  private async createDecoder(tier: DecoderTier): Promise<void> {
    const token = ++this.resetToken;
    const hwAccel = tier === 'L0_HARDWARE' ? 'prefer-hardware' : 
                    tier === 'L1_HYBRID' ? 'prefer-software' : 'require-software';
    
    this.decoder = new VideoDecoder({
      output: this.handleFrame.bind(this, token),
      error: this.handleError.bind(this, token)
    });
    
    await this.decoder.configure({
      codec: this.capability.codec,
      hardwareAcceleration: hwAccel,
      // ... profile/level/colorSpace 透传
    });
  }

  private handleError(token: number, err: DOMException): void {
    if (token !== this.resetToken) return; // 过期回调丢弃
    this.metrics.record('decode_error', { tier: this.tier, name: err.name });
    this.scheduleFallback(err.name);
  }

  private scheduleFallback(reason: string): void {
    if (this.tier === 'L0_HARDWARE' && this.shouldFallbackToL1(reason)) {
      this.transitionTo('L1_HYBRID');
    } else if (this.tier !== 'L2_SOFTWARE') {
      this.transitionTo('L2_SOFTWARE');
    }
  }
}

P = w1 * (decodeQueueSize / maxQueueSize) 
  + w2 * (frameAge / maxAcceptableLatency)
  + w3 * (bandwidthHeadroom / estimatedBandwidth)

解码器 (P > 0.7) 
  → 发送 RTCP TMMBR / REMB 降码率建议 
  → 编码器调整 targetBitrate / framerate
  → 网络层主动丢弃非关键帧 (Discardable=1)
  → 发送端 PLI/FIR 抑制

class FrameLevelFlowController {
  private readonly decoder: VideoDecoder;
  private readonly sender: RTCRtpSender;
  private readonly statsMonitor: StatsMonitor;
  private pressure = 0;
  private readonly EWMA_ALPHA = 0.2;

  constructor(decoder: VideoDecoder, sender: RTCRtpSender) {
    this.decoder = decoder;
    this.sender = sender;
    this.startPressureLoop();
  }

  private startPressureLoop(): void {
    const loop = async () => {
      while (this.running) {
        await this.samplePressure();
        await this.applyBackpressure();
        await sleep(50); // 20Hz 控制频率
      }
    };
    loop();
  }

  private async samplePressure(): Promise<void> {
    const [decoderStats, netStats] = await Promise.all([
      this.getDecoderStats(),
      this.statsMonitor.getOutboundRtpStats()
    ]);

    const queuePressure = decoderStats.decodeQueueSize / 16; // 硬编码上限
    const latencyPressure = Math.min(
      (performance.now() - decoderStats.oldestFrameTimestamp) / 300, 1
    );
    const bwPressure = Math.max(0, 1 - netStats.availableOutgoingBitrate / netStats.targetBitrate);

    const instantP = 0.5 * queuePressure + 0.3 * latencyPressure + 0.2 * bwPressure;
    this.pressure = this.EWMA_ALPHA * instantP + (1 - this.EWMA_ALPHA) * this.pressure;
  }

  private async applyBackpressure(): Promise<void> {
    if (this.pressure > 0.8) {
      // 激进降码：请求关键帧 + 降低目标码率 30%
      await this.sender.setParameters({
        encodings: [{ 
          scaleResolutionDownBy: 2.0, 
          maxBitrate: Math.floor(this.currentBitrate * 0.7) 
        }]
      });
      this.requestKeyFrame();
    } else if (this.pressure > 0.5) {
      // 温和降码：仅降码率 15%
      await this.sender.setParameters({
        encodings: [{ maxBitrate: Math.floor(this.currentBitrate * 0.85) }]
      });
    } else if (this.pressure < 0.2 && this.currentBitrate < this.maxBitrate) {
      // 恢复：逐步回升 5%/s
      await this.sender.setParameters({
        encodings: [{ maxBitrate: Math.min(this.maxBitrate, this.currentBitrate * 1.05) }]
      });
    }
  }

  private requestKeyFrame(): void {
    const transceiver = this.sender.transceiver;
    if (transceiver?.receiver) {
      transceiver.receiver.sendRtcpFeedback('fir', {});
    }
  }
}

function toneMapToSDR(frame: VideoFrame, canvas: HTMLCanvasElement): void {
  const ctx = canvas.getContext('2d', { colorSpace: 'srgb' })!;
  // 1. 使用 CSS Filter 近似 PQ→SDR OETF（性能最优）
  ctx.filter = 'brightness(0.85) contrast(1.15) saturate(0.9)';
  ctx.drawImage(frame, 0, 0, canvas.width, canvas.height);
  ctx.filter = 'none';
  
  // 2. 高保真路径：WebGL 片元着色器实现 BT.2390 EETF
  // 仅在用户开启「高画质模式」且 GPU 支持 EXT_color_buffer_float 时启用
}

class SVCDecoderScheduler {
  private readonly layerPriority = ['BL', 'EL1', 'EL2', 'EL3']; // 低→高
  private activeLayers: Set<string> = new Set(['BL']); // 当前激活层

  // 解码回调中拦截
  handleFrame(token: number, frame: VideoFrame): void {
    const layerId = this.parseSVCLayerId(frame); // 从 frame.metadata 或 side-data 解析
    
    // 压力过大时，仅保留 BL，其余入队即丢弃（不调用 decoder.decode）
    if (this.pressure > 0.7 && layerId !== 'BL') {
      this.metrics.record('svc_layer_dropped', { layer: layerId });
      frame.close(); // 关键：及时释放 VideoFrame 内存
      return;
    }
    
    // 压力中等，保留 BL+EL1
    if (this.pressure > 0.4 && !['BL', 'EL1'].includes(layerId)) {
      frame.close();
      return;
    }
    
    this.decoder.decode(frame);
  }

  // 动态调整激活层，配合编码端 spatialLayers 设置
  updateActiveLayers(targetLayers: string[]): void {
    this.activeLayers = new Set(targetLayers);
    // 通知编码端调整 scalabilityMode
    this.encoderController.setScalabilityMode(this.mapToScalabilityMode(targetLayers));
  }
}

// 编码端 ROI 应用示例
async function encodeWithROI(frame: VideoFrame, roiRects: DOMRect[]): Promise<void> {
  const roiMap = roiRects.map(r => ({
    x: Math.round(r.x * frame.codedWidth),
    y: Math.round(r.y * frame.codedHeight),
    width: Math.round(r.width * frame.codedWidth),
    height: Math.round(r.height * frame.codedHeight),
    qpDelta: -6 // ROI 区域 QP 降低 6，约等于码率 +40% 画质增益
  }));
  
  await encoder.encode(frame, { 
    keyFrame: false,
    roiMap // 需编码器支持：VP9/AV1/H.264 (部分硬编)
  });
}

// WebCodecs + WebGPU 零拷贝管线初始化
async function initZeroCopyPipeline(): Promise<ZeroCopyPipeline> {
  const adapter = await navigator.gpu.requestAdapter();
  const device = await adapter.requestDevice({
    requiredFeatures: ['video-decoder', 'texture-compression-bc', 'dawn-internal-usages'] // Chrome 标志位
  });

  // 1. 创建解码器，输出目标为 GPUTexture
  const decoder = new VideoDecoder({
    output: (frame) => gpuFrameQueue.push(frame), // frame 为 GPU-backed VideoFrame
    error: handleDecodeError
  });

  await decoder.configure({
    codec: 'avc',
    hardwareAcceleration: 'prefer-hardware',
    // 关键：指定输出格式为 GPU 可直接采样的格式
    outputFormat: 'rgba16float' // HDR 管线首选，SDR 用 'rgba8unorm'
  });

  // 2. WebGPU 侧：创建外部纹理绑定组布局
  const bindGroupLayout = device.createBindGroupLayout({
    entries: [{
      binding: 0,
      visibility: GPUShaderStage.FRAGMENT | GPUShaderStage.COMPUTE,
      externalTexture: {}
    }]
  });

  return { decoder, device, bindGroupLayout, gpuFrameQueue: [] };
}

// 3. 渲染/后处理 Compute Shader 直接消费
const computeShader = `
  @group(0) @binding(0) var inputTex: texture_external;
  @group(0) @binding(1) var outputTex: texture_storage_2d<rgba16float, write>;
  
  @compute @workgroup_size(16, 16)
  fn main(@builtin(global_invocation_id) id: vec3<u32>) {
    let color = textureLoad(inputTex, id.xy);
    // Tone Mapping / Super Resolution / Denoise 逻辑
    textureStore(outputTex, id.xy, tonemapPQtoSDR(color));
  }
`;

// Worker 侧：解密 + 重排序 + 交付 WebCodecs Decoder
class SecureDecoderWorker {
  private decoder: VideoDecoder;
  private readonly keyRatchet: KeyRatchet; // Double Ratchet 算法

  constructor() {
    this.decoder = new VideoDecoder({
      output: this.onFrameDecrypted.bind(this),
      error: this.onError.bind(this)
    });
  }

  async transform(controller: TransformStreamDefaultController<EncodedVideoChunk>): Promise<void> {
    for await (const chunk of controller.readable) {
      // 1. 反序列化自定义 Header: [KeyID(4B) | FrameID(8B) | FEC_ID(1B) | Payload]
      const { keyId, frameId, payload, fec } = this.parseCustomHeader(chunk);
      
      // 2. 密钥派生（前向保密）
      const key = await this.keyRatchet.deriveDecryptKey(keyId, frameId);
      
      // 3. AES-GCM 解密（Web Crypto API 原生硬件加速）
      const decrypted = await crypto.subtle.decrypt(
        { name: 'AES-GCM', iv: this.buildIV(frameId) },
        key,
        payload
      );
      
      // 4. 重组标准 EncodedVideoChunk 交付解码器
      const plainChunk = new EncodedVideoChunk({
        type: chunk.type,
        timestamp: chunk.timestamp,
        duration: chunk.duration,
        data: new Uint8Array(decrypted)
      });
      
      this.decoder.decode(plainChunk);
      
      // 5. FEC 恢复逻辑（RaptorQ / Reed-Solomon）
      if (fec) this.fecBuffer.store(frameId, plainChunk);
    }
  }
}

class CodecLicenseGuard {
  private static readonly POLICY = {
    encode: ['vp9', 'av1', 'avc'],      // 允许编码
    decode: ['vp9', 'av1', 'avc', 'hevc'] // 允许解码（含兜底）
  };

  static assertEncodeAllowed(codec: string): void {
    if (!this.POLICY.encode.includes(codec)) {
      throw new ComplianceError(`Codec ${codec} encoding forbidden by patent policy`);
    }
  }

  static selectPreferredCodec(capabilities: DecoderCapabilityMatrix[]): VideoCodec {
    // 优先级：AV1(硬解) > VP9(硬解) > H.264(硬解) > AV1(软解) > VP9(软解)
    const order: VideoCodec[] = ['av1', 'vp9', 'avc'];
    for (const c of order) {
      if (capabilities.some(cap => cap.codec === c && cap.hwAcceleration !== 'unavailable')) {
        return c;
      }
    }
    return 'vp9'; // 最终兜底软解 VP9 (dav1d WASM 体积 300KB+，VP9 WASM 仅 80KB)
  }
}

// WebGPU INT8 量化超分模型推理（ONNX -> WebNN / 手写 WGSL）
class SuperResolutionPipeline {
  private readonly computePipeline: GPUComputePipeline;
  private readonly weightBuffers: Map<string, GPUBuffer>; // INT8 权重 + Scale/ZeroPoint
  private readonly bindGroup: GPUBindGroup;

  async initialize(modelUrl: string): Promise<void> {
    // 1. 加载 ONNX 模型，转换为 WGSL + 二进制权重
    const { shaderCode, weights } = await this.loadQuantizedModel(modelUrl);
    
    // 2. 创建 Compute Pipeline
    this.computePipeline = await this.device.createComputePipelineAsync({
      layout: 'auto',
      compute: { module: this.device.createShaderModule({ code: shaderCode }), entryPoint: 'main' }
    });
    
    // 3. 权重上传 GPUBuffer (STORAGE, COPY_DST)
    this.weightBuffers = this.uploadWeights(weights);
    this.bindGroup = this.createBindGroup();
  }

  // 解码回调中插帧超分
  async upscale(frame: VideoFrame, targetWidth: number, targetHeight: number): Promise<VideoFrame> {
    const inputTexture = this.importVideoFrame(frame); // GPUExternalTexture
    const outputTexture = this.device.createTexture({
      size: [targetWidth, targetHeight],
      format: 'rgba16float',
      usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING
    });

    const commandEncoder = this.device.createCommandEncoder();
    const pass = commandEncoder.beginComputePass();
    pass.setPipeline(this.computePipeline);
    pass.setBindGroup(0, this.bindGroup);
    pass.setBindGroup(1, this.createFrameBindGroup(inputTexture, outputTexture));
    pass.dispatchWorkgroups(Math.ceil(targetWidth/16), Math.ceil(targetHeight/16));
    pass.end();
    this.device.queue.submit([commandEncoder.finish()]);

    // 返回新 VideoFrame (零拷贝 wrap)
    return new VideoFrame(outputTexture, { timestamp: frame.timestamp });
  }
}

// Shadow Session 启动器（注入到真实会话页面）
class ShadowSessionLauncher {
  static async attachToRealSession(realReceiver: RTCRtpReceiver): Promise<ShadowDecoder> {
    const shadowDecoder = new AdaptiveDecoderController(); // 复用生产逻辑
    const transformStream = new TransformStream({
      transform(chunk, controller) {
        controller.enqueue(chunk); // 透传给真实渲染器
        shadowDecoder.decode(chunk.clone()); // 克隆喂给影子解码器
      }
    });
    
    // Hook Insertable Streams
    const { readable, writable } = realReceiver.readable.pipeThrough(transformStream);
    await realReceiver.setStreams(readable, writable); // 仅部分浏览器支持，需 Polyfill
    
    return shadowDecoder;
  }
}

// C++ 抽象接口 (ume::IVideoDecoder)
class IVideoDecoder {
public:
  virtual ~IVideoDecoder() = default;
  virtual Result<DecoderInfo> initialize(const DecoderConfig& config) = 0;
  virtual Result<Frame> decode(EncodedChunk chunk) = 0;
  virtual void flush() = 0;
  virtual void setPressureCallback(PressureCallback cb) = 0; // 原生层感知压力回调 JS
};

// 平台实现工厂
std::unique_ptr<IVideoDecoder> createPlatformDecoder(Codec codec) {
#if defined(OS_WIN)
  return std::make_unique<MFVideoDecoder>(); // Media Foundation
#elif defined(OS_MAC)
  return std::make_unique<VTVideoDecoder>(); // VideoToolbox
#elif defined(OS_ANDROID)
  return std::make_unique<MediaCodecDecoder>(); // MediaCodec (NDK)
#elif defined(OS_LINUX)
  return std::make_unique<V4L2Decoder>(); // V4L2 Stateless Decoder
#else
  return std::make_unique<Dav1dDecoder>(); // 通用软解兜底
#endif
}

// 统一 JS 门面，对上层业务屏蔽平台差异
export class NativeVideoDecoder implements IStandardDecoder {
  private nativeHandle: number; // 指向 C++ 对象的指针句柄
  
  async configure(config: DecoderConfig): Promise<void> {
    const result = await nativeBinding.decodeInit(this.nativeHandle, config);
    if (result.error) throw new DecoderError(result.error);
    this.capability = result.capability; // 原生层返回完整能力矩阵
  }
  
  decode(chunk: EncodedVideoChunk): void {
    nativeBinding.decodePush(this.nativeHandle, chunk); // 零拷贝传指针
  }
  
  // 原生层主动回调 JS 压力信号
  private onNativePressure(pressure: number): void {
    this.flowController.updatePressure(pressure);
  }
}