Native / Web 渲染一致性检查
历史验证记录：Native / Web 渲染一致性检查。请结合日期、环境和证据限制阅读。
本页保留当时的验证结论，不代表当前完整平台能力。当前状态见项目进展，运行时说明见JavaScriptCore。
本次以 demo 的真实 Web、WGPU 窗口为对象，使用相同的初始剧情和资源，960×540 CSS 窗口、DPR 2，输出 1920×1080 PNG。功能测试与画面一致性分别验证，不以 E2E 通过推断逐像素一致。
已修正的跨层问题
- 单位边界：Web demo 的设置、Backlog、通用系统 UI 原先处于不缩放的 screen 层，Gallery 和剧情处于逻辑舞台；原生均为逻辑坐标。demo 系统层现在统一到 overlay 舞台，同一缩放规则适用于两端。这个改动也会使 Web 小窗口的系统面板随舞台缩放。
- 字体基线：原生 atlas 原先把字号当作字体高度，直接以 ascent 推进基线，导致大 ascent 的 CJK/衬线字体裁切。现在使用 ascent/descent 与 line-height 的半行距计算基线。正文阴影和正文使用相同的顶端对齐。
- 字体来源：系统面板显式使用随 QPK 注册的 Noto Sans / Noto Serif；Web 不再优先使用操作系统私有字体，避免字宽、换行和控制行高随机器变化。
- 对话布局：打字时保留仅供原生 renderer 使用的完整 layoutText，稳定面板尺寸；保留换行、给头像预留固定列；选项使用已投影的实际对话框高度，避免长文本增高后重叠。
- 验证环境：native dev 配置监听比较实际内容，忽略构建期间和内容未变的通知，避免截图过程中循环重启。
功能面板
| 范围 | 本次支持 / 修复 | 仍不能据此宣称的能力 |
|---|---|---|
| 设置 | 有限高度滚动、统一舞台、字体、背景渐变、关闭按钮；512 个离散滑条值覆盖完整合法步长范围 | 通用文本、颜色、对象输入编辑；所有原生控件与 HTML 控件的逐像素相等 |
| Gallery | 有界面板、五列自适应卡片、独立缩略图/文字/徽标、完整滚动内容标签、网格大图预览和关闭、正确的整层 z 顺序 | 原生音视频预览、任意 custom content、浏览器 lightbox 自动隐藏/渐变 chrome 的完全等价 |
| Gallery 权限与资源 | 消费插件已脱敏的 lockedPresentation，保留有意开放的锁定占位内容；合并资产/内容/条目 QPK 来源；视频字节不误送图片解码器 | 渲染层自行解锁或读取隐藏定义 |
| Backlog | 有界滚动面板、按正文长度增长的行、保留换行和全文、保留回溯/重播 intent | 富文本逐 span 样式；所有历史界面的视觉状态组合均已截图覆盖 |
| 对话 / 选项 | 稳定打字布局、头像避让、实际面板避让、文本基线和阴影对齐 | 混合 span 样式、打字音效、任意超长选项的滚动 UI 与 Web 完全等价 |
| 背景 / 角色 / 动画 | 本次真实首段剧情截图覆盖背景、角色、对话及 HUD；现有逻辑坐标和包来源链保持不变 | 所有滤镜、复合动画和媒体格式均已穷尽验证 |
| 主菜单 / 保存读取 / 成就 | demo 系统层统一逻辑舞台，原生现有 pipeline 意图路径保留 | 存档预览、成就面板、所有响应式尺寸及交互状态已达到逐像素一致 |
| QSS / WGPU | 延续显式支持的布局、渐变、阴影、文本及媒体投影 | 任意 CSS 选择器/伪元素、多重阴影、浏览器模糊卷积等同于 WGPU；跨 GPU 字体栅格化逐像素相等 |
可重复验证
- 启动
pnpm --filter demo dev:web和pnpm dev:native，native 保持初始标题界面。 - 运行
node demo/scripts/render-parity.mjs（默认使用本机 Chrome；可设QUA_PARITY_BROWSER/QUA_PARITY_WEB_URL）。 - 检查
demo/dist/native/parity/review.html的拖动对比，以及measurements.json。脚本同时检查设置、Gallery、首张卡片、对话框边界，任一坐标/尺寸误差超过 2 CSS px 则失败。截图必须继续人工审阅，边界检查不等于像素检查。 - 运行
pnpm native:e2e验证完整真实窗口剧情/菜单/资源生命周期。
覆盖的固定画面：标题、设置、Gallery 初始网格、首项大图预览、第一句对话。该覆盖不构成所有分辨率、所有悬停/焦点状态、全部富文本与音视频效果完全一致的证明。后续新增能力应增加相应同状态截图，而非只增加投影结构断言。
本次验证结果
- WGPU renderer（
real-wgpu-noop）807 项测试通过；Gallery 19、设置 16、Backlog 17 项测试通过，相关插件与 demo 类型检查通过。 - 最终
pnpm native:e2e通过：Apple M4 实际 WGPU 窗口、85 句对话、stealth 分支、设置与 Gallery、1920×1080 PNG 回读；纹理上传和字体 atlas 错误均为 0。 - 同状态截图边界检查通过：设置面板最大误差 1.391 CSS px，Gallery 面板 0，首张卡片最大误差 0.121 CSS px，对话框最大误差 0.15 CSS px。上述数字仅衡量已列出的边界，不代表颜色、字形、阴影及所有状态的像素一致率。
UI 编写与绘制链路补充审查
本轮补充处理 padding/border 内容盒、嵌套布局位移、hover 布局同步、延迟过渡、背景/阴影/文字绘制顺序，以及圆角对子绘制与点击区域的统一约束。详见 Native UI 编写能力审查。
新增 pnpm native:ui:compare：真实 WGPU 与 Chrome 使用同一组逻辑坐标绘制阴影、圆角、嵌套裁剪及背景层，输出拖动对比和按区域计算的像素误差。原来的 demo 截图是上一轮产物，不作为本轮所有状态的像素一致性证明。