flowchart LR
    A[摄像头/视频流] --> B(MediaPipe Hands<br/>21 关键点 @ 30fps)
    B --> C[关键点平滑与归一化<br/>Kalman / OneEuro Filter]
    C --> D[手语语法映射引擎<br/>Gloss→Pose 序列]
    D --> E[WebXR 渲染管线<br/>Three.js + WebGPU]
    E --> F[立体视频流合成<br/>WebRTC Insertable Streams]
    F --> G[会议客户端展示]

// 关键配置：启用 GPU delegate 并限制最大检测手数
const hands = new Hands({
  locateFile: (file) => `https://cdn.jsdelivr.net/npm/@mediapipe/hands/${file}`,
  selfieMode: true,
  maxNumHands: 2,
  modelComplexity: 1,          // 0=Lite, 1=Full, 2=Heavy
  minDetectionConfidence: 0.7,
  minTrackingConfidence: 0.7
});

// WebGPU 加速路径（Chrome 113+）
if (navigator.gpu) {
  await hands.setOptions({ delegate: 'gpu' });
}

// OneEuroFilter.ts
export class OneEuroFilter {
  constructor(
    private freq: number = 30,
    private minCutoff: number = 1.0,
    private beta: number = 0.01,
    private dCutoff: number = 1.0
  ) {}

  filter(value: number, timestamp: number): number {
    // 实现细节省略：低通滤波 + 导数自适应截止频率
  }
}

// 21 点并行滤波
const filters = Array.from({ length: 21 }, () => new OneEuroFilter());
const smoothed = landmarks.map((pt, i) => ({
  x: filters[i * 3].filter(pt.x, now),
  y: filters[i * 3 + 1].filter(pt.y, now),
  z: filters[i * 3 + 2].filter(pt.z, now)
}));

// renderer-setup.ts
const renderer = new Three.WebGPURenderer({
  canvas: document.querySelector('#xr-canvas'),
  antialias: true,
  alpha: true
});
await renderer.init();

renderer.setSize(width, height);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); // 限制高 DPI 成本
renderer.shadowMap.enabled = false; // 手语虚拟人无需阴影，省 15% GPU
renderer.toneMapping = Three.ACESFilmicToneMapping;
renderer.toneMappingExposure = 1.0;

// XR 会话启动
const session = await navigator.xr.requestSession('immersive-ar', {
  requiredFeatures: ['local-floor', 'hand-tracking'],
  depthSensing: { usagePreference: ['cpu-optimized'], dataFormatPreference: ['luminance-alpha'] }
});
renderer.xr.setSession(session);

// 将渲染帧注入 WebRTC 发送轨道
const canvas = renderer.domElement;
const stream = canvas.captureStream(30); // 30fps 足够手语流畅度
const sender = pc.getSenders().find(s => s.track.kind === 'video');

const processor = new VideoFrameProcessor({
  frameCallback: async (frame, controller) => {
    // 可选：服务端录制合流、水印、超分
    controller.enqueue(frame);
  }
});

const transformStream = new TransformStream(processor);
stream.getVideoTracks()[0].readable.pipeThrough(transformStream).pipeTo(
  new WritableStream({
    write(chunk) { sender.sendFrame?.(chunk); }
  })
);

// spatial-topology.ts
interface SpatialAnchor {
  id: string;              // "R-LOC:Speaker_A"
  type: 'REFERENT' | 'BUOY' | 'ROLE_SHIFT';
  position: THREE.Vector3; // 相对虚拟人胸腔坐标系
  semantics: {
    entity: string;        // 关联实体 ID
    role?: 'AGENT' | 'PATIENT' | 'EXPERIENCER';
    temporalScope: [number, number]; // 生效帧区间
  };
  constraints: {
    gazeTarget?: string;   // 注视锚点 ID
    bodyLean?: number;     // 躯干倾斜角度 [-1, 1]
    nonManuals: FacialActionUnit[]; // 面部非手动标记
  };
}

class SpatialTopologyGraph {
  private anchors: Map<string, SpatialAnchor> = new Map();
  private edges: Map<string, Set<string>> = new Map(); // 空间关系边

  // 解析语义表示 -> 生成锚点
  parseFromDRS(drs: DiscourseRepresentationStructure): void {
    drs.referents.forEach(ref => {
      const anchor = this.allocateAnchor(ref);
      this.anchors.set(anchor.id, anchor);
    });
    // 建立空间关系：如 "A 给 B" -> A(AGENT) --TRANSFER--> B(PATIENT)
    drs.conditions.forEach(cond => this.buildRelation(cond));
  }

  // 运行时动态插值：根据当前帧进度计算目标姿态
  solveFrame(frameIndex: number): Map<string, THREE.Vector3> {
    const targets = new Map<string, THREE.Vector3>();
    this.anchors.forEach(anchor => {
      if (frameIndex >= anchor.semantics.temporalScope[0] && 
          frameIndex <= anchor.semantics.temporalScope[1]) {
        // 叠加注视、躯干倾斜、面部 AU 约束
        const pose = this.computeCompositePose(anchor, frameIndex);
        targets.set(anchor.id, pose);
      }
    });
    return targets;
  }
}

// wgsl: nms_blend.wgsl - 顶点着色器中实现 NMS 与手部姿态融合
@vertex
fn vs_main(
  @location(0) pos: vec3<f32>,
  @location(1) normal: vec3<f32>,
  @location(2) skinIndices: vec4<u32>,
  @location(3) skinWeights: vec4<f32>,
  @builtin(instance_index) instIdx: u32
) -> VSOutput {
  // 1. 标准 GPU Skinning
  var worldPos = vec3<f32>(0.0);
  var worldNormal = vec3<f32>(0.0);
  for (var i: u32 = 0u; i < 4u; i++) {
    let idx = skinIndices[i];
    let w = skinWeights[i];
    if (w > 0.0) {
      let boneMat = bones[idx];
      worldPos += w * (boneMat * vec4<f32>(pos, 1.0)).xyz;
      worldNormal += w * (mat3x3<f32>(boneMat) * normal);
    }
  }

  // 2. NMS 程序化修正（仅影响面部/头部骨骼）
  if (isFaceBone(skinIndices)) {
    let nmsData = nmsBuffer[frameIndex]; // 52 AU 强度
    // 眉头上扬 -> 眉骨骼 Y 向位移
    worldPos.y += nmsData[AU_INNER_BROW_RAISER] * 0.012; 
    // 疑问句头前倾 -> 头部骨骼旋转
    if (nmsData[SYNTAX_YN_QUESTION] > 0.5) {
      worldPos = rotateX(worldPos, -0.15 * nmsData[SYNTAX_YN_QUESTION]);
    }
  }

  // 3. 输出
  var out: VSOutput;
  out.position = viewProjMat * vec4<f32>(worldPos, 1.0);
  out.worldNormal = normalize(worldNormal);
  return out;
}

# consistency_validator.py (Node.js 侧 WASM 模块)
class CoreferenceValidator:
    def __init__(self, tolerance_cm: float = 3.0):
        self.anchor_history: Dict[str, List[np.ndarray]] = defaultdict(list)
        self.tolerance = tolerance_cm / 100.0  # 转米

    def validate_frame(self, frame_idx: int, stg: SpatialTopologyGraph) -> List[Violation]:
        violations = []
        for anchor_id, anchor in stg.anchors.items():
            if anchor.type != 'REFERENT': continue
            current_pos = anchor.position.toArray()
            self.anchor_history[anchor_id].append(current_pos)
            
            # 滑动窗口平滑后检测漂移
            if len(self.anchor_history[anchor_id]) > 30: # 1秒窗口
                recent = np.mean(self.anchor_history[anchor_id][-30:], axis=0)
                initial = self.anchor_history[anchor_id][0]
                drift = np.linalg.norm(recent - initial)
                if drift > self.tolerance:
                    violations.append(Violation(
                        anchor_id=anchor_id,
                        drift_cm=drift * 100,
                        severity='WARN' if drift < 0.1 else 'ERROR',
                        suggestion=f"重新校准 {anchor_id} 定位点"
                    ))
        return violations

// skinning_instanced.wgsl
struct BoneMatrices { m: array<mat4x4<f32>, MAX_BONES> };
struct InstanceData {
  boneOffset: u32,      // 该实例在骨骼纹理中的起始层
  morphWeights: vec4<f32>, // 变形目标权重 (眨眼、嘴型、眉毛)
  colorId: u32,         // 拾取/高亮用
};

@group(0) @binding(0) var<storage, read> boneTexture: texture_2d_array<f32>; // 存储所有实例骨骼矩阵
@group(0) @binding(1) var<storage, read> instances: array<InstanceData>;
@group(0) @binding(2) var<uniform> viewProj: mat4x4<f32>;

@vertex
fn vs_main(
  @location(0) pos: vec3<f32>,
  @location(1) normal: vec3<f32>,
  @location(2) uv: vec2<f32>,
  @location(3) skinIndices: vec4<u32>,
  @location(4) skinWeights: vec4<f32>,
  @location(5) morphTarget0: vec3<f32>, // 基础变形目标
  @location(6) morphTarget1: vec3<f32>,
  @builtin(instance_index) instIdx: u32,
  @builtin(vertex_index) vertIdx: u32
) -> VSOutput {
  let inst = instances[instIdx];
  
  // 1. 从纹理加载骨骼矩阵 (零拷贝，GPU 侧解码)
  let bone0 = loadBoneMatrix(boneTexture, inst.boneOffset + skinIndices.x);
  let bone1 = loadBoneMatrix(boneTexture, inst.boneOffset + skinIndices.y);
  let bone2 = loadBoneMatrix(boneTexture, inst.boneOffset + skinIndices.z);
  let bone3 = loadBoneMatrix(boneTexture, inst.boneOffset + skinIndices.w);

  // 2. GPU Skinning
  var worldPos = skinWeights.x * (bone0 * vec4<f32>(pos, 1.0)).xyz;
  worldPos += skinWeights.y * (bone1 * vec4<f32>(pos, 1.0)).xyz;
  worldPos += skinWeights.z * (bone2 * vec4<f32>(pos, 1.0)).xyz;
  worldPos += skinWeights.w * (bone3 * vec4<f32>(pos, 1.0)).xyz;

  // 3. 变形目标融合 (Morph Targets for NMS)
  worldPos += inst.morphWeights.x * morphTarget0;
  worldPos += inst.morphWeights.y * morphTarget1;

  // 4. 法线变换 (简化版，忽略变形目标法线)
  var worldNormal = skinWeights.x * (mat3x3<f32>(bone0) * normal);
  worldNormal += skinWeights.y * (mat3x3<f32>(bone1) * normal);
  worldNormal += skinWeights.z * (mat3x3<f32>(bone2) * normal);
  worldNormal += skinWeights.w * (mat3x3<f32>(bone3) * normal);

  var out: VSOutput;
  out.position = viewProj * vec4<f32>(worldPos, 1.0);
  out.normal = normalize(worldNormal);
  out.uv = uv;
  out.colorId = inst.colorId;
  return out;
}

@group(0) @binding(0) var<storage, read> instanceAABBs: array<vec4<f32>>; // min.xyz, max.x
@group(0) @binding(1) var<storage, read_write> instanceVisible: array<atomic<u32>>;
@group(0) @binding(2) var<uniform> frustumPlanes: array<vec4<f32>, 6>; // 平面方程

@compute @workgroup_size(64)
fn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {
  let i = gid.x;
  if (i >= instanceCount) return;

  let aabb = instanceAABBs[i];
  let min = aabb.xyz;
  let max = vec3<f32>(aabb.w, aabb.w, aabb.w); // 简化：球体包围盒

  var visible = true;
  for (var p = 0; p < 6; p++) {
    let plane = frustumPlanes[p];
    let dist = dot(plane.xyz, min) + plane.w; // 最近点距离
    if (dist < 0.0) { visible = false; break; }
  }

  // 原子操作写入可见性标记
  if (visible) {
    atomicStore(&instanceVisible[i], 1u);
  } else {
    atomicStore(&instanceVisible[i], 0u);
  }
}

// 1. 运行 Compute Shader 剔除
passEncoder.dispatchWorkgroups(Math.ceil(instanceCount / 64));

// 2. 间接绘制参数缓冲区 (由 Compute Shader 写入 drawCount)
const indirectBuffer = device.createBuffer({
  size: 16, // drawIndexedIndirect: count, instanceCount, firstIndex, baseVertex
  usage: GPUBufferUsage.INDIRECT | GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
});

// 3. 绘制
renderPass.drawIndexedIndirect(indirectBuffer, 0);

// shader-hot-reload.ts
class WGSLHotReloader {
  private pipelines: Map<string, GPURenderPipeline> = new Map();
  private watchers: Map<string, FileSystemWatcher> = new Map(); // Vite/ESBuild HMR API

  async register(name: string, module: GPUShaderModule, descriptor: GPURenderPipelineDescriptor) {
    const pipeline = await device.createRenderPipelineAsync(descriptor);
    this.pipelines.set(name, pipeline);

    if (import.meta.hot) {
      import.meta.hot.accept(`./shaders/${name}.wgsl`, async (newModule) => {
        console.log(`[HMR] Reloading shader: ${name}`);
        const newPipeline = await device.createRenderPipelineAsync({
          ...descriptor,
          vertex: { ...descriptor.vertex, module: newModule },
          fragment: { ...descriptor.fragment, module: newModule }
        });
        // 无缝切换：下一帧自动生效
        this.pipelines.set(name, newPipeline);
        pipeline.destroy(); // 延迟销毁旧管线
      });
    }
  }

  get(name: string) { return this.pipelines.get(name)!; }
}

import { test, expect } from '@playwright/test';
import { pixelmatch } from 'pixelmatch';
import { PNG } from 'pngjs';

const VIEWPORTS = [
  { name: 'desktop-1080p', width: 1920, height: 1080, dpr: 1 },
  { name: 'mobile-iphone14', width: 390, height: 844, dpr: 3 },
  { name: 'xr-quest3', width: 2064, height: 2208, dpr: 1.5, isXR: true }
];

const GOLDEN_IMAGES_DIR = './tests/golden';
const THRESHOLD = 0.02; // 2% 像素差异容忍度

for (const vp of VIEWPORTS) {
  test(`Visual Regression: Signing "Meeting Schedule" @ ${vp.name}`, async ({ page }) => {
    await page.setViewportSize({ width: vp.width, height: vp.height });
    await page.goto('/test-harness?scenario=meeting_schedule');
    
    // 等待动画稳定 (30帧)
    await page.waitForFunction(() => window.__ANIMATION_STABLE__ === true);
    
    const screenshot = await page.screenshot({ 
      type: 'png', 
      animations: 'disabled' // 关闭 CSS 动画干扰
    });
    
    const goldenPath = `${GOLDEN_IMAGES_DIR}/${vp.name}_meeting_schedule.png`;
    const golden = PNG.sync.read(fs.readFileSync(goldenPath));
    const current = PNG.sync.read(screenshot);
    
    const diff = new PNG({ width: golden.width, height: golden.height });
    const diffPixels = pixelmatch(golden.data, current.data, diff.data, 
      golden.width, golden.height, { threshold: 0.1 });
    
    const diffRatio = diffPixels / (golden.width * golden.height);
    
    // 生成差异报告
    if (diffRatio > THRESHOLD) {
      fs.writeFileSync(`./tests/diff/${vp.name}_diff.png`, PNG.sync.write(diff));
      throw new Error(`Visual regression detected: ${(diffRatio*100).toFixed(2)}% diff > ${THRESHOLD*100}%`);
    }
  });
}

jobs:
  benchmark:
    runs-on: ubuntu-latest
    container: nvidia/cuda:12.2-devel-ubuntu22.04 # GPU Runner
    steps:
      - uses: actions/checkout@v4
      - name: Download Test Data (DVC)
        run: dvc pull data/csl-testbench
      - name: Run Inference (Headless Chrome + WebGPU)
        run: |
          xvfb-run -a node scripts/run-benchmark.mjs 
            --model ./models/hands_mediapipe.task 
            --input ./data/csl-testbench/videos 
            --output ./results/benchmark.json
      - name: Compute Metrics
        run: python scripts/compute_metrics.py ./results/benchmark.json
      - name: Comment PR with Report
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('./results/report.md', 'utf8');
            await github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: report
            })

interface WCAGCriterion {
  id: string;           // "1.2.2"
  level: 'A' | 'AA' | 'AAA';
  title: string;
  technicalEvidence: string[];
  testResult: 'PASS' | 'FAIL' | 'PARTIAL' | 'NOT_APPLICABLE';
  remediation?: string;
}

class VPATGenerator {
  async generateReport(buildId: string): Promise<VPATReport> {
    const criteria: WCAGCriterion[] = [
      {
        id: '1.2.2',
        level: 'A',
        title: 'Captions (Prerecorded)',
        technicalEvidence: [
          'SignLanguageAvatarRenderer.ts: L.120-145 (SRT/VTT dual-track output)',
          'E2E Test: tests/e2e/captions.sync.spec.ts (Passed 2024-05-20)',
          'Benchmark: CSL-TestBench Sync Accuracy 98.7%'
        ],
        testResult: 'PASS'
      },
      {
        id: '2.1.1',
        level: 'A',
        title: 'Keyboard',
        technicalEvidence: [
          'AvatarControlPanel.tsx: Full keyboard navigation (Tab/Enter/Space/Arrows)',
          'FocusVisible CSS: :focus-visible { outline: 3px solid #005fff }',
          'Axe-core CI: 0 violations (WCAG21AA)'
        ],
        testResult: 'PASS'
      },
      {
        id: '1.4.3',
        level: 'AA',
        title: 'Contrast (Minimum)',
        technicalEvidence: [
          'Design Token: --color-avatar-skin-bg contrast 7.2:1 (APCA)',
          'Shader: avatar.frag ensures outline contrast in all lighting',
          'Automated Check: Lighthouse CI score 100/100 Accessibility'
        ],
        testResult: 'PASS'
      },
      // ... 完整 50 条标准
    ];

    // 自动跑 axe-core + lighthouse + 自定义规则
    const auditResults = await this.runAutomatedAudits();
    
    return {
      productName: 'SignLanguage Avatar SDK',
      version: process.env.npm_package_version,
      date: new Date().toISOString(),
      criteria: criteria.map(c => ({
        ...c,
        testResult: auditResults[c.id] || 'NOT_TESTED'
      })),
      conformanceLevel: 'AA',
      remarks: 'Supports real-time sign language interpretation for video conferencing.'
    };
  }
}

export async function createRendererAdapter(canvas: HTMLCanvasElement): Promise<RendererAdapter> {
  // 1. WebGPU 优先
  if (navigator.gpu) {
    const adapter = await navigator.gpu.requestAdapter({ powerPreference: 'high-performance' });
    if (adapter) return new WebGPURenderer(canvas, adapter);
  }

  // 2. WebGL 2.0 回退 (Safari/Firefox/旧版移动端)
  const gl = canvas.getContext('webgl2', { 
    antialias: true, 
    alpha: true, 
    preserveDrawingBuffer: false,
    powerPreference: 'high-performance'
  });
  if (gl) return new WebGL2Renderer(canvas, gl);

  // 3. 终极兜底：CSS 3D Transform + Canvas 2D 合成 (极低端设备)
  console.warn('[Adapter] Falling back to CSS 3D Renderer');
  return new CSS3DRenderer(canvas);
}

// MediaPipe 后端自动选择
export async function createHandDetector(): Promise<HandDetector> {
  if (navigator.gpu && (await navigator.gpu.requestAdapter())) {
    return new MediaPipeHands({ delegate: 'webgpu', modelComplexity: 1 });
  }
  // Safari/WebView 使用 WASM SIMD 优化版
  return new MediaPipeHands({ delegate: 'wasm-simd', modelComplexity: 1 });
}

// avatar.glb (扩展片段)
{
  "extensionsUsed": ["EXT_sign_language_avatar"],
  "extensions": {
    "EXT_sign_language_avatar": {
      "skeletonProfile": "SL_AVATAR_1.0", // 标准骨骼命名: "wrist.L", "index.01.L", "brow_inner.L"
      "morphTargetMap": {
        "AU_1_Inner_Brow_Raiser": 0,
        "AU_4_Brow_Lowerer": 1,
        "AU_12_Lip_Corner_Puller": 2,
        "Viseme_AA": 10,
        "Viseme_EE": 11,
        "Viseme_OH": 12
      },
      "spatialAnchors": [
        { "name": "R_LOC_SPEAKER", "bone": "spine.003", "offset": [0.15, 0.0, -0.2] },
        { "name": "L_LOC_LISTENER", "bone": "spine.003", "offset": [-0.15, 0.0, -0.2] }
      ],
      "lodLevels": [
        { "screenCoverage": 1.0, "mesh": "mesh_lod0", "triangles": 48000 },
        { "screenCoverage": 0.3, "mesh": "mesh_lod1", "triangles": 12000 },
        { "screenCoverage": 0.05, "mesh": "mesh_lod2", "triangles": 3000 }
      ]
    }
  }
}

flowchart TB
    A[租户配置中心] --> B(配置清单 JSON)
    B --> C{运行时加载器}
    C --> D[基础模型<br/>通用骨骼/动画]
    C --> E[租户覆盖层<br/>形象/材质/词汇表]
    C --> F[动态词汇包<br/>专业术语 Gloss->Pose]
    D --> G[虚拟人实例]
    E --> G
    F --> G

// package.json 关键依赖
{
  "dependencies": {
    "three": "0.160.0",
    "@mediapipe/tasks-vision": "0.10.3",
    "onnxruntime-web": "1.17.0",
    "webgpu-utils": "1.0.0-beta.12",
    "axe-core": "4.8.4",
    "pixelmatch": "5.3.0",
    "playwright": "1.42.0"
  },
  "resolutions": {
    "webgl-matrix": "3.4.3" // 修复已知内存泄漏
  }
}