zeroweb-browser-chrome-parity

name	zeroweb-browser-chrome-parity
description	对比 ZeroWeb 与 Chrome 的真实点击、页面状态、事件、几何和生产 GPU 帧。用户要求 Chrome 一致性或交互渲染验收时使用。

ZeroWeb Chrome 一致性验收

本 Skill 用于为页面或交互场景生成可审计的 Chrome-vs-ZeroWeb 证据。视觉一致性和行为一致性是两个独立门禁；只有两者都经过规定的生产路径，才能报告“完整一致”。

硬性规则

1. 不得用 element.click() 充当点击证据。Chrome 必须执行 mouse.move、mouse.down、mouse.up；ZeroWeb 必须走浏览器输入链路或 WebDriver 自动化链路。
2. 不得把 CPU、engine-direct、纯 headless 或单元测试截图描述为生产窗口 GPU 证据。
3. 两端必须使用同一场景、viewport、DPR、locale、颜色主题、字体环境和 scrollbar 策略。
4. 每个稳定检查点分别比较状态、事件序列、几何和像素，不得把四项平均成单一分数。
5. 缺少必需产物时判定失败。只有用户明确要求诊断模式或仅静态模式时才能降级。
6. 全图和控件区域像素阈值都是严格小于关系。3% 表示结果必须 <3%。
7. 验收结束时必须向用户直接展示同一检查点的 Chrome 和 ZeroWeb 两张全帧截图，不得只提供报告路径或文字结论。
8. 字体由其他目标负责时，可对文本控件区域声明 glyphMaskInsetPx，但全图仍须未遮罩比较，报告也必须保留区域的 unmasked 原始结果。checkbox、radio 等非字形控件不得使用该遮罩。

必读资料

创建场景、实现 ZeroWeb 证据生产器或解释报告前，完整阅读 references/evidence-contract.md。

平台支持

核心脚本使用 Node.js ESM，不依赖 Bash、GNU timeout 或 realpath，支持：

• Windows 10/11：PowerShell、CMD 或其他能启动 Node.js 的终端。
• Linux：X11 或 Wayland；无人值守 GUI 验收可使用 Xvfb。
• macOS：原生窗口环境。

跨平台不等于无环境要求。完整生产验收仍要求：

• Node.js 20+；
• 仓库 Rust 工具链和 test-guard；
• Chrome/Chromium 127、Microsoft Edge，或场景指定的版本；
• 可用的窗口系统和 GPU adapter；
• Windows 首次构建前配置 RUSTY_V8_ARCHIVE；
• Linux/macOS 首次构建前执行 make setup-rusty-v8。

浏览器自动探测顺序见 capture-chrome.mjs。各平台均按 Chrome、Chromium、Edge 的顺序探测；也可显式设置 PUPPETEER_EXECUTABLE_PATH。Edge 后备不会放宽场景的 chromeVersionPattern，需要由场景明确接受对应的 Edg/... 版本。

执行流程

1. 选择证据目录。默认使用仓库内已被 .gitignore 忽略的 .acceptance/chrome-parity/<scenario-name>-<timestamp>/，一次性或 CI 诊断也可使用系统临时目录。不得把截图写入受版本控制的源码或文档目录。

2. 准备仓库依赖：

   cd tests/wpt-runner/scripts
   npm ci
   

   构建命令须通过仓库 test-guard 包裹。Linux/macOS 示例：

   ./target/test-guard --time-limit 900 -- cargo build --release \
     -p zero-wpt-runner -p zero-browser -p zero-renderer \
     -p zero-compositor -p zero-webdriver
   

   Windows 使用仓库在该平台提供的等价 test-guard 入口，不得裸跑长时间构建。

3. 通用页面从 templates/generic-page.scenario.json 开始；表单专项验收可使用 templates/form-interaction.scenario.json。修改页面 URL、stateExpression、观察 selector 和动作。页面无需提供 #test-state、特殊 title 或其他验收专用标记；ZeroWeb 会在 live renderer 的真实页面上下文执行观察表达式。observe.selectors 接受任意受页面 querySelector 支持的 CSS selector。点击 selector 无需同时列入观察列表。当前生产采集环境必须使用 locale: "en-US"、reducedMotion: "no-preference"，颜色主题可选 light 或 dark；不支持的值由 validator 明确拒绝。

4. 校验场景：

   node .agents/skills/zeroweb-browser-chrome-parity/scripts/validate-scenario.mjs <scenario.json>
   

5. 采集 Chrome 证据。完整生产验收先在当前进程环境设置 PARITY_ORACLE_MODE=gui，让脚本跨平台启动独立的 GUI Chrome：

   node .agents/skills/zeroweb-browser-chrome-parity/scripts/capture-chrome.mjs \
     --scenario <scenario.json> \
     --out <evidence-dir>/chrome
   

   已有带远程调试的 GUI Chrome 时，设置 ORACLE_CDP_URL=http://127.0.0.1:9222 可复用该实例；它的优先级高于 PARITY_ORACLE_MODE。两者均未设置时脚本启动 headless Chrome，仅用于行为诊断，不满足生产视觉门禁。

6. 用仓库命令生成 ZeroWeb 证据。命令会收到：

   PARITY_SCENARIO
   PARITY_OUTPUT_DIR
   PARITY_REPO_ROOT
   

   命令必须写出 <evidence-dir>/zeroweb/manifest.json。完整验收的 manifest 必须声明：

   {
     "engine": 
      
      
   
   

ZeroWeb 适配器优先级

1. 生产浏览器窗口 + 多进程 renderer/compositor + 浏览器指针输入 + wgpu present + 严格 GPU readback。
2. zero-webdriver 仅用于行为诊断。它持有 live renderer，但不是最终浏览器窗口 compositor 路径。
3. Rust HtmlScenario 测试仅用于快速回归定位。

如果第 1 条无法逐步输出证据，必须报告缺少产品自动化能力并停止完整验收。不得把第 2 条的行为证据与第 1 条无关的初始截图拼接成“端到端通过”。

稳定帧条件

每个动作后等待所有适用条件：

• 页面完成导航和加载；
• 页面状态断言成立；
• snapshot 或 frame sequence 已前进；
• 连续两次采样帧一致；
• 字体和图片完成加载。

使用有上限的轮询并保留诊断信息。不得只依赖固定 sleep。

完整通过标准

• Chrome capturePath 为 chrome-cdp-gui；
• ZeroWeb capturePath 为 production-window-gpu；
• ZeroWeb inputPath 为 browser-pointer；
• 每个检查点的可观察状态一致；
• 归一化事件序列一致；
• 所有观察矩形偏差不超过几何阈值；
• 每张全帧 diff 严格小于 maxDiffPercent；
• 每个控件区域 diff 严格小于 maxRegionDiffPercent；
• 不缺少任何必需产物或检查点。

失败定位

• 状态/事件不一致但几何一致：检查默认动作、焦点所有权、事件取消和 retained form state。
• 几何不一致但状态接近：检查布局、UA 样式、viewport、DPR 和 scrollbar 占位。
• 几何一致但像素不一致：检查边框、绘制顺序、控件 appearance、抗锯齿和字体区域。
• headless 通过但产品窗口失败：检查 compositor IPC、surface 初始化、scale 换算、GPU fallback 和 readback 来源。
• 仅非 1 DPR 点击失败：检查 document → content → physical 坐标换算。

评测样例见 evals/evals.json。