┌─────────────────────────────────────────────────────────────┐
│  应用层：业务编排（会议状态机、布局引擎、QoS 策略）           │
├─────────────────────────────────────────────────────────────┤
│  管线调度层：FrameGraph + 资源池 + 自适应降级控制器           │
├─────────────────────────────────────────────────────────────┤
│  算子层：标准化 Compute/Render Pass（去噪、美颜、超分、合成）  │
├─────────────────────────────────────────────────────────────┤
│  硬件抽象层：WebGPU Device / Queue / Buffer / Texture 管理    │
└─────────────────────────────────────────────────────────────┘

// 采集端：MediaStreamTrackProcessor → VideoFrame → GPUExternalTexture
const trackProcessor = new MediaStreamTrackProcessor({ track: videoTrack });
const reader = trackProcessor.readable.getReader();

async function feedExternalTexture() {
  while (true) {
    const { done, value: videoFrame } = await reader.read();
    if (done) break;

    // 直接导入，无需 copyToCanvas
    const externalTexture = device.importExternalTexture({
      source: videoFrame,
      colorSpace: 'srgb',
      usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_SRC
    });

    frameGraph.registerExternalResource(`camera_${frameId}`, externalTexture);
    videoFrame.close(); // 及时释放 CPU 侧内存
  }
}

// denoise_beauty.wgsl
@group(0) @binding(0) var inputTex: texture_2d<f32>;
@group(0) @binding(1) var outputTex: texture_storage_2d<rgba8unorm, write>;
@group(0) @binding(2) var params: uniform DenoiseBeautyParams;

struct DenoiseBeautyParams {
  sigma_spatial: f32,
  sigma_range: f32,
  beauty_strength: f32,
  // ... 其它参数
}

@compute @workgroup_size(16, 16)
fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
  let dims = textureDimensions(inputTex);
  if (gid.x >= dims.x || gid.y >= dims.y) { return; }

  // 双边滤波去噪（简化版）
  let center = textureLoad(inputTex, vec2<i32>(gid.xy), 0);
  var acc = vec4<f32>(0.0);
  var wsum = 0.0;

  for (var dy = -2i; dy <= 2; dy++) {
    for (var dx = -2; dx <= 2; dx++) {
      let offset = vec2<i32>(i32(gid.x) + dx, i32(gid.y) + dy);
      if (offset.x < 0 || offset.x >= i32(dims.x) || offset.y < 0 || offset.y >= i32(dims.y)) { continue; }
      let neighbor = textureLoad(inputTex, offset, 0);
      let spatial_w = exp(-f32(dx*dx + dy*dy) / (2.0 * params.sigma_spatial * params.sigma_spatial));
      let range_w = exp(-distance(center.rgb, neighbor.rgb) / params.sigma_range);
      let w = spatial_w * range_w;
      acc += neighbor * w;
      wsum += w;
    }
  }
  let denoised = acc / wsum;

  // 美颜：简易高频保留平滑 + 肤色调整
  let highFreq = center - denoised;
  let smoothed = center - params.beauty_strength * highFreq;
  let finalColor = mix(center, smoothed, smoothstep(0.2, 0.8, center.g)); // 肤色检测近似

  textureStore(outputTex, vec2<i32>(gid.xy), finalColor);
}

class ResourcePool {
  private texturePools = new Map<string, GPUTexture[]>();
  private bufferPools = new Map<string, GPUBuffer[]>();

  acquireTexture(desc: GPUTextureDescriptor): GPUTexture {
    const key = JSON.stringify(desc);
    let pool = this.texturePools.get(key);
    if (!pool) { pool = []; this.texturePools.set(key, pool); }
    return pool.pop() ?? device.createTexture(desc);
  }

  releaseTexture(tex: GPUTexture) {
    const key = JSON.stringify({
      size: [tex.width, tex.height, tex.depthOrArrayLayers],
      format: tex.format,
      usage: tex.usage,
      dimension: tex.dimension,
      mipLevelCount: tex.mipLevelCount,
      sampleCount: tex.sampleCount
    });
    this.texturePools.get(key)?.push(tex);
  }

  // 定期清理：超过 2s 未复用的资源 destroy()
  startGC(intervalMs = 2000) { /* ... */ }
}

async function createPipeline(): Promise<VideoPipeline> {
  if (!navigator.gpu) {
    return new WebGLFallbackPipeline(); // 旧设备兜底
  }
  const adapter = await navigator.gpu.requestAdapter({ powerPreference: 'high-performance' });
  if (!adapter) { return new WebGLFallbackPipeline(); }

  const device = await adapter.requestDevice({
    requiredFeatures: ['timestamp-query', 'texture-compression-bc', 'shader-f16'],
    requiredLimits: { maxStorageBufferBindingSize: 256 * 1024 * 1024 }
  });

  // 特性探测：是否支持外部纹理零拷贝
  const supportsExternalTexture = adapter.features.has('texture-external');
  return new WebGPUPipeline(device, { zeroCopy: supportsExternalTexture });
}

interface ResourceLifetime {
  // 逻辑帧索引（单调递增）
  firstUseFrame: number;  
  lastUseFrame: number;
  // 物理资源句柄
  physicalHandle: GPUTexture | GPUBuffer;
  // 别名组 ID：同组资源物理内存互斥，不同时段复用
  aliasGroupId: number;    
  // 当前帧引用计数（用于延迟销毁）
  refCount: number;        
}

gantt
    title 单帧 GPU 时间线 (双队列重叠)
    dateFormat  x
    axisFormat %L ms
    section Compute Queue (前处理+AI)
    DenoiseBeauty     :crit, a1, 0, 4
    SuperResolution   :crit, a2, after a1, 8
    section Render Queue (合成+输出)
    LayoutCompose     :crit, b1, 2, 5   %% 与 SuperResolution 重叠
    DisplayPresent    :crit, b2, after b1, 1

// 离线生成的降级查表（示例）
const DEGRADATION_LUT = [
  { tier: 0, desc: "1080p FP16 Full",  res: 1.0,  fp16: true,  sr: true,  beautyIter: 3, estMs: 22, memMB: 120 },
  { tier: 1, desc: "1080p FP16 NoSR",  res: 1.0,  fp16: true,  sr: false, beautyIter: 3, estMs: 14, memMB: 90  },
  { tier: 2, desc: "720p  FP16 Full",  res: 0.75, fp16: true,  sr: true,  beautyIter: 2, estMs: 11, memMB: 68  },
  { tier: 3, desc: "720p  FP32 Lite",  res: 0.75, fp16: false, sr: false, beautyIter: 1, estMs: 7,  memMB: 45  },
  { tier: 4, desc: "540p  FP32 Min",   res: 0.5,  fp16: false, sr: false, beautyIter: 0, estMs: 4,  memMB: 22  },
];

function selectTier(gpuTimeP99: number, memUsageMB: number): number {
  for (const tier of DEGRADATION_LUT) {
    if (tier.estMs <= gpuTimeP99 * 0.85 && tier.memMB <= memUsageMB * 0.8) return tier.tier;
  }
  return DEGRADATION_LUT.length - 1; // 兜底最低档
}

// utils/math.wgsl
fn saturate(x: f32) -> f32 { return clamp(x, 0.0, 1.0); }
fn luminance(rgb: vec3<f32>) -> f32 { return dot(rgb, vec3<f32>(0.2126, 0.7152, 0.0722)); }

// operators/denoise.wgsl
#include "utils/math.wgsl"
#include "utils/bilateral.wgsl"

@group(0) @binding(0) var input: texture_2d<f32>;
@group(0) @binding(1) var output: texture_storage_2d<rgba8unorm, write>;
// ... 具体实现

// 编译期常量（Pipeline Layout 创建时传入）
override ENABLE_SR: bool = false;
override BEAUTY_LEVEL: u32 = 1; // 0/1/2/3

@compute @workgroup_size(16, 16)
fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
  // ... 通用逻辑
  
  // 编译期展开，死代码消除
  if (ENABLE_SR) { 
    // 超分采样逻辑
  }
  
  // 运行时分支（Level 变化频繁，不宜特化）
  if (BEAUTY_LEVEL > 0) { applyBeauty(level); }
}

// dev-server 监听 .wgsl 变更 -> WebSocket 推送新模块源码
if (import.meta.hot) {
  import.meta.hot.accept('./shaders/**/*.wgsl', (modules) => {
    for (const [path, src] of Object.entries(modules)) {
      const newModule = device.createShaderModule({ code: src, label: path });
      // 原子替换：新建 Pipeline -> 校验通过 -> 交换引用 -> 旧 Pipeline 标记销毁
      pipelineManager.hotSwap(path, newModule);
    }
  });
}

// 1. 创建 QuerySet
const querySet = device.createQuerySet({ type: 'timestamp', count: 2 * MAX_PASSES_PER_FRAME });

// 2. CommandEncoder 记录时间戳
const encoder = device.createCommandEncoder();
let queryIndex = 0;
for (const pass of frameGraph.passes) {
  encoder.writeTimestamp(querySet, queryIndex++); // Pass Start
  pass.record(encoder);
  encoder.writeTimestamp(querySet, queryIndex++); // Pass End
}
device.queue.submit([encoder.finish()]);

// 3. 异步解析
const resolveBuffer = device.createBuffer({
  size: querySet.count * 8, usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC
});
encoder.resolveQuerySet(querySet, 0, querySet.count, resolveBuffer, 0);

// 4. 映射读回 -> 计算每 Pass 耗时 -> 反馈给降级控制器 & A/V 同步模块
const timestamps = await readbackTimestamps(resolveBuffer);
const gpuLatencyMs = (timestamps[last] - timestamps[0]) * timestampPeriod; // ns -> ms

// 合成输出帧时，显式设置 presentationTime 锁定显示时刻
const canvasContext = canvas.getContext('webgpu');
canvasContext.configure({ device, format: 'rgba8unorm', alphaMode: 'premultiplied' });

function presentFrame(texture: GPUTexture, targetPresentTime: number) {
  // 1. 等待 GPU 管线完成
  await device.queue.onSubmittedWorkDone(); 
  
  // 2. 计算距离下一个 VSync 的剩余时间
  const now = performance.now();
  const vsyncInterval = 1000 / 60; // 假设 60Hz
  const nextVSync = Math.ceil(targetPresentTime / vsyncInterval) * vsyncInterval;
  
  // 3. 精确休眠（避免提前提交导致丢帧或延迟）
  if (nextVSync - now > 1) await sleep(nextVSync - now - 0.5); // 预留 0.5ms 提交开销
  
  // 4. 提交
  const encoder = device.createCommandEncoder();
  encoder.copyTextureToTexture(
    { texture }, 
    { texture: canvasContext.getCurrentTexture() }, 
    [canvas.width, canvas.height]
  );
  device.queue.submit([encoder.finish()]);
}

// layout.wgsl
struct InstanceData {
  // 目标矩形 (NDC: -1~1)
  dstRect: vec4<f32>,  // x, y, width, height
  // 源纹理坐标 (UV)
  srcRect: vec4<f32>,  // u, v, w, h
  // 颜色校正/透明度
  colorMul: vec4<f32>, // r, g, b, a
  // 纹理索引 (绑定组数组下标)
  texIndex: u32,
  _padding: vec3<u32>,
};

@group(0) @binding(0) var textures: binding_array<texture_2d<f32>>;
@group(0) @binding(1) var samplers: binding_array<sampler>;
@group(1) @binding(0) var<storage, read> instances: array<InstanceData>;

@vertex
fn vs_main(
  @builtin(vertex_index) vid: u32,
  @builtin(instance_index) iid: u32
) -> @builtin(position) vec4<f32> {
  let inst = instances[iid];
  // 单位正方形顶点 -> 目标矩形
  const pos = array<vec2<f32>, 4>(
    vec2<f32>(-1.0, -1.0), vec2<f32>(1.0, -1.0),
    vec2<f32>(-1.0, 1.0),  vec2<f32>(1.0, 1.0)
  );
  let uv = (pos[vid] + vec2<f32>(1.0)) * 0.5; // 0~1
  
  let dst = inst.dstRect;
  let position = vec4<f32>(dst.x + uv.x * dst.z, dst.y + uv.y * dst.w, 0.0, 1.0);
  
  // 传递给片元着色器
  // (需通过 @location 传递 uv, srcRect, texIndex 等)
  // ...
  return position;
}

@fragment
fn fs_main(@location(0) uv: vec2<f32>, @location(1) srcRect: vec4<f32>, @location(2) texIndex: u32, @location(3) colorMul: vec4<f32>) -> @location(0) vec4<f32> {
  let tex = textures[texIndex];
  let samp = samplers[texIndex];
  let sampleUV = srcRect.xy + uv * srcRect.zw;
  let color = textureSample(tex, samp, sampleUV);
  return color * colorMul;
}

// 1. 计算布局 (Flex/Grid/自定义) -> 生成 InstanceData 数组
const instances = layoutEngine.computeLayout(participants, canvasSize);

// 2. 上传 Instance Buffer (STORAGE, 动态更新)
device.queue.writeBuffer(instanceBuffer, 0, new Float32Array(instances.flatMap(i => [
  i.dstRect.x, i.dstRect.y, i.dstRect.z, i.dstRect.w,
  i.srcRect.x, i.srcRect.y, i.srcRect.z, i.srcRect.w,
  i.colorMul.x, i.colorMul.y, i.colorMul.z, i.colorMul.w,
  i.texIndex, 0, 0, 0
])));

// 3. 更新 BindGroup (纹理数组绑定)
// 仅当参会者增减时重建 BindGroup，逐帧仅更新 Buffer

// 4. Indirect Draw 命令
const indirectBuffer = device.createBuffer({
  size: 20, // 5 * u32
  usage: GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_DST
});
device.queue.writeBuffer(indirectBuffer, 0, new Uint32Array([
  4,                    // indexCount (quad = 2 triangles = 6 indices, 但用 triangle strip 仅 4)
  instances.length,     // instanceCount
  0, 0, 0               // firstIndex, baseVertex, baseInstance
]));

// 5. 记录 RenderPass
pass.setPipeline(layoutPipeline);
pass.setBindGroup(0, textureBindGroup);
pass.setBindGroup(1, instanceBindGroup);
pass.setIndexBuffer(indexBuffer, 'uint16');
pass.drawIndexedIndirect(indirectBuffer, 0);

PyTorch (FP32) 
  → ONNX (opset 17+) 
  → ONNX Runtime Web (ORT Web) / WebNN (实验) 
  → **或** 自定义 WGSL 算子 (极致性能/体积)

# calibrate.py (离线运行)
import onnxruntime as ort
from onnxruntime.quantization import quantize_static, CalibrationDataReader

class VideoFrameCalibrator(CalibrationDataReader):
    def __init__(self, video_paths, input_name, size=(640, 360)):
        self.frames = self._extract_frames(video_paths, size)
        self.input_name = input_name
        self.idx = 0
    def get_next(self):
        if self.idx >= len(self.frames): return None
        data = {self.input_name: self.frames[self.idx]}
        self.idx += 1
        return data

quantize_static(
    model_input='esrgan_fp32.onnx',
    model_output='esrgan_int8.onnx',
    calibration_data_reader=VideoFrameCalibrator(['test.yuv'], 'input'),
    quant_format=QuantFormat.QDQ,      # 支持逐通道量化
    activation_type=QuantType.QInt8,
    weight_type=QuantType.QInt8,
    per_channel=True,                  # 权重逐通道，激活逐张量
    optimize_model=True
)

// int8_gemm.wgsl
struct QuantParams {
  scale: f32,      // 输入 scale
  zero_point: i32, // 输入 zero_point
  w_scale: f32,    // 权重 scale (逐通道，需数组)
  w_zero_point: i32,
  out_scale: f32,  // 输出 scale
  out_zero_point: i32,
};

@group(0) @binding(0) var<storage, read> input_i8: array<i32>;  // 打包 4xi8 -> i32
@group(0) @binding(1) var<storage, read> weight_i8: array<i32>; // 同上
@group(0) @binding(2) var<uniform> qparams: QuantParams;
@group(0) @binding(3) var<storage, write> output_f32: array<f32>;

// 解包 4 个 i8
fn unpack4(packed: i32) -> vec4<i32> {
  return vec4<i32>(
    (packed & 0xFF) - 128,
    ((packed >> 8) & 0xFF) - 128,
    ((packed >> 16) & 0xFF) - 128,
    ((packed >> 24) & 0xFF) - 128
  );
}

@compute @workgroup_size(64)
fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
  // ... 矩阵乘法累加 (i32 累加器防溢出) ...
  let acc_i32 = dot(i32_vec, w_i32_vec); 
  // 反量化
  let acc_f32 = f32(acc_i32) * qparams.scale * qparams.w_scale;
  output_f32[gid.x] = acc_f32 * qparams.out_scale + f32(qparams.out_zero_point);
}

        ┌─────────────────────┐
        │  E2E 视觉回归测试    │  (Percy/Chromatic: 对比渲染结果图片 SSIM > 0.98)
        ├─────────────────────┤
        │  集成测试            │  (Playwright + Chrome Headless --enable-webgpu)
        │  - 管线完整跑通      │
        │  - 降级触发验证      │
        │  - 内存泄漏压测      │
        ├─────────────────────┤
        │  单元测试            │  (Vitest + @webgpu/types 模拟 Device)
        │  - FrameGraph 拓扑   │
        │  - 资源池分配逻辑    │
        │  - 降级策略决策      │
        └─────────────────────┘

# .github/workflows/webgpu-test.yml
jobs:
  webgpu-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with: { node-version: '20' }
      - name: Install Chrome (with WebGPU support)
        run: |
          sudo apt-get update
          sudo apt-get install -y google-chrome-stable
          # 启用 Vulkan 支持 (GitHub Actions runner 通常有 GPU)
      - name: Run Tests (xvfb + WebGPU)
        run: |
          xvfb-run -a -s "-screen 0 1920x1080x24" 
            google-chrome-stable 
            --headless=new 
            --enable-webgpu 
            --use-vulkan=native 
            --disable-gpu-sandbox 
            --remote-debugging-port=9222 
            --user-data-dir=/tmp/chrome-profile 
            "http://localhost:3000/test-harness.html" &
          sleep 5
          npm run test:playwright

// test/visual-regression.spec.ts
import { test, expect } from '@playwright/test';
import pixelmatch from 'pixelmatch';
import { PNG } from 'pngjs';

test('Denoise+Beauty pipeline visual fidelity', async ({ page }) => {
  await page.goto('/test-harness.html?case=denoise_beauty');
  // 等待管线预热稳定
  await page.waitForFunction(() => window.pipelineWarmedUp === true);
  
  const screenshot = await page.screenshot({ type: 'png' });
  const baseline = PNG.sync.read(require('fs').readFileSync('baselines/denoise_beauty.png'));
  const current = PNG.sync.read(screenshot);
  
  const diff = new PNG({ width: baseline.width, height: baseline.height });
  const diffPixels = pixelmatch(baseline.data, current.data, diff.data, baseline.width, baseline.height, {
    threshold: 0.05, // 5% 色差容忍
    includeAA: true
  });
  
  const diffRatio = diffPixels / (baseline.width * baseline.height);
  expect(diffRatio).toBeLessThan(0.001); // 差异像素 < 0.1%
  
  if (diffRatio > 0.001) {
    require('fs').writeFileSync('artifacts/diff.png', PNG.sync.write(diff));
  }
});

// benchmarks/pipeline.bench.ts
import { bench, describe } from 'vitest';
import { createPipeline } from '../src/pipeline';

describe('Pipeline Frame Budget', () => {
  const pipeline = await createPipeline({ width: 1920, height: 1080 });
  const frame = generateTestFrame(1920, 1080);

  bench('Full Pipeline 1080p', () => {
    pipeline.processFrame(frame);
  }, {
    time: 10000, // 运行 10 秒
    warmup: 1000,
    setup: () => { /* 重置统计 */ },
    teardown: (result) => {
      // CI 门禁：P99 < 16.6ms (60fps)
      if (result.p99 > 16.6) throw new Error(`P99 ${result.p99}ms exceeds 16.6ms budget`);
    }
  });
});