# 兼容性与验收验证

更新日期：2026-11-18。开发与本地复测使用 moonc 0.10.20、moon 0.1.20261104、Node 24.13.0、Krita 5.3.4 Windows 便携版。本文记录实现行为、互操作证据、平台范围与限制，供核对兼容性和复现测试使用。注册表安装验证单独说明。

## 正确性与回归覆盖

- 26 项核心测试在 JavaScript、wasm、wasm-gc 目标通过。覆盖全部 20 个 SVG 操作的独立数值预期、负偏移、裁剪、组隔离、透明度差异、PNG/ORA 往返、持久化编辑和共享不可变像素。
- 修复保留扩展资源与自动图层路径重名。测试占用连续 19 个旧命名资源，校验每个名字唯一、资源字节不变、保存可重开；24 组固定随机种子的多层/嵌套图使用 Pillow 独立计算结果逐字节核对。
- 内部像素、子树数组、扩展属性和归档资源不再对外暴露。构造与访问器隔离可变数组；包外消费者验证 5 类直接字段改动无法编译，同时运行完整嵌套编辑与往返示例。调用方提供的循环子树在构造、插入和整体替换时均先校验，防止无限复制。
- XML 整数使用整数词法与转换前边界检查。CLI、文件与桥接拒绝小数坐标、错误类型、越界和无效枚举；失败不产生输出或替换已有编辑状态。CLI 省略的属性保留原值。
- 规范化输出使用 OpenRaster 0.0.6，根 stack 省略渲染属性，组省略旧 X/Y，图层坐标保留。根、图像和图层的安全扩展属性及附加资源继续保存。输出也检查条目数、单资源和归档大小预算。
- 独立 ZIP/XML/Pillow 脚本验证压缩输入、精确合成、扩展保留、首条 mimetype、不压缩 mimetype、新预览/缩略图和覆盖保护。矢量只读预览可原样导出归档。

复测入口：`moon test --target js --deny-warn`、`python scripts/check_acceptance.py`、`python scripts/check_interop.py`、`python scripts/check_package.py`。完整接口和可运行消费者见 [中文 API 说明](docs/API.zh-CN.md)。

## 真实绘图软件互通

2026-11-18 重新运行 `scripts/check_krita.py`、`scripts/check_artwork.py`、`scripts/check_sample_pixels.py`，均传入实际 Krita 5.3.4 可执行文件，不仅检查历史记录。

1. Krita 写出的 Light study ORA 由 MoonBit 读取，合成像素与独立 Krita PNG 完全一致。MoonBit 修改嵌套层的位置、透明度和混合方式后写出，Krita 重开并独立导出，最大通道差异为 1（0～255）。
2. Capitole 原始分层绘画包含 7 个栅格层与原组，来自固定哈希的 David Revoy KRA 源文件。MoonBit 编辑、保存后由 Krita 重开，最大通道差异为 1；结构、alpha-preserve 和新预览检查通过。
3. 四个练习参考 ORA 由 Krita 重开，最大通道差异依次为 1、1、1、2，均不超过约定容差 2。四个原始模式的网页尺寸资源与独立 Krita 渲染差异为 1、0、1、1。出处、转换与修改说明在 LICENSES 和 fixtures 中。

Krita 导出时可能重新裁剪图层资源并调整偏移；判断以结构语义、图层属性与实际画面为准，不要求 ZIP 二进制完全相同。

## 16 位栅格验证

[16 位案例](docs/ROUNDTRIP16.zh-CN.md)记录了独立像素验证和 Krita 5.3.4 重开。两个非 8 位可表示的源图层保存后逐样本一致，新合并图维持每通道 16 位，8 位缩略图与新画面对应。完整范围见 [兼容矩阵](docs/COMPATIBILITY.zh-CN.md)。

## 相加模式的明确边界

`svg:plus` 保持 W3C 的预乘颜色与 alpha 相加规则，不用特例模拟 Krita Addition。`scripts/check_plus.py` 自动验证独立公式、CLI 警告、桥接打开/编辑/撤销后的警告保留。2026-11-18 调用真实 Krita 进行独立导出：前景 RGBA=(50,150,250,128)、背景=(200,100,20,64)，MoonBit/W3C 结果为 (100,133,173,192)，Krita 5.3.4 为 (120,159,206,160)，最大差异 33。原始数据见 [数值记录](docs/performance/plus-krita.json)。网页显示中文提示，CLI 在诊断输出中提示，不声称这类文件跨软件像素一致。

此前 20 种操作与 Krita 的对照中，其他 19 种在该小样例容差 1 内；该结论不代替各操作的数值测试，也不是对所有软件/颜色配置的无限兼容承诺。

## 网页与样例

公共库、CLI 和网页桥接使用同一份 Krita ORA 与同一组中文名、负坐标、透明度及混合方式编辑，输出 XML 结构与像素完全一致；真实浏览器应用相同属性后下载 PNG，也与库结果逐字节一致。复测先运行 `python scripts/check_consistency.py`，再运行浏览器脚本。

Chromium 回归覆盖并通过：真正的拖动中像素更新、松手只提交一次、撤销重做、键盘操作、缩放保持、锁定、复制/跨组移动、PNG 插入/替换/提取、中文名称、ORA 保存重开、失败导入恢复、移动宽度和相加模式提示。一次本机拖动初次响应为 198 ms；这不是 60 fps 保证。

四幅真实分层作品都有原始模式与单独标记的练习变体，层数分别为 7、7、10、9。练习改动来自原图的图层；背景替换素材也来自作者原图，不给一张平面海报叠加虚构图层。雨城原 KRA 的两种调整效果由 Krita 烘焙为导出栅格，不作为可编辑调整层。

桥接回放四个任务全部得到与参考 PNG 完全一致的结果，并保存重开无像素变化。浏览器测试覆盖任务的真实状态、撤销后失效、替换素材、导出版本、样例切换取消、移动布局。完成条件是练习参考状态，不是艺术质量评分。

预览最长边 384，拖动事件合并且忽略过期回复，松手才按完整分辨率提交。撤销最多 20 步，按逻辑像素量保守缩短，至少一步；实际运行时内存另含对象、当前/预览文档和编码缓冲。文件切换清空历史；失败导入保留原文档。[性能记录](PERFORMANCE.md) 给出相同机器前后数据及 24 层隔离组观测。

三套原创格式练习覆盖 JPEG、透明 WebP、PNG、16 位 TIFF、BMP、GIF、ICO 和受支持的静态 SVG。Chromium 自起点逐步执行真正的新增、替换、属性修改及导出，逐字节比较下载的 PNG 和参考成图，并验证撤销后任务状态更新。地形测绘图的导出 PNG 保留 16 位；独立脚本还检查 TIFF 通道值、GIF 首帧、WebP 透明度、JPEG 方向及七种格式保存 ORA 后的重开。执行 `python scripts/check_image_import.py` 和浏览器样例测试可复现。

## SVG 图层往返

`python scripts/check_svg.py` 独立生成 SVG 与 16 位栅格混合 ORA，执行嵌套层移动和透明度修改，再逐通道核对新合并图、图层属性和原始 SVG 字节。浏览器重放地形测绘图，导入真正的 SVG 源，保存后独立核对源文件和 16 位地形，再打开保存的 ORA，确认工作台仍识别同一 SVG 图层。核心测试覆盖透明边缘、视口、路径、渐变、剪裁、未知资源和尺寸限制。SVG 的渲染边界见 [兼容矩阵](docs/COMPATIBILITY.zh-CN.md)。

## 平台、分发与发布状态

[GitHub Actions](https://github.com/gywcs101/MoonOpenRaster/actions/workflows/ci.yml) 配置 Linux 的四目标检查/构建/测试、独立互操作、许可、浏览器与原生 CLI；Windows 2022（MSVC）和 macOS 15 的原生测试、中文路径读写及独立消费者。每个提交以自己的实际运行结果为准，不能把历史绿灯当作最新提交的结果。

功能版本 `0b171c8` 的 [完整检查运行](https://github.com/gywcs101/MoonOpenRaster/actions/runs/44226215888) 已通过 Linux 全套、Windows 2022 原生和 macOS 15 原生三项任务。后续提交应检查其各自运行。

本机 Windows 尚缺完整 MSVC/SDK，因此本机执行证据是 JS、wasm、wasm-gc 与浏览器，Windows 原生证据来自 CI。macOS 14 运行环境已经退役，配置已调整为 macOS 15。

`.moonignore` 排除网页资源、桥接、浏览器测试与开发脚本，保留核心库、CLI、示例、核心测试、说明和完整许可证；GitHub 完整仓库仍含全部样例。文件清单与独立源码消费者检查不产生供用户下载的最终发行物。当前工具链的 `--list` 会顺带写临时归档，检查脚本将它隔离到临时目录并自动清理，不把它当作最终包或包验收证据。

`gywcs101/MoonOpenRaster@0.1.0` 已可在 Mooncakes 查询。本次文档整理在仓库外的独立目录按 README 安装该版本，并执行原样代码，完成编辑、保存、重开和 PNG 合成。此项使用注册表依赖，没有本地工作区覆盖；不等于验证独立离线网页 ZIP 或其他发行物。

## 支持范围与资源限制

编辑和准确合成范围包括 8 位、16 位及混合位深的 sRGB RGBA 栅格、嵌套组、规范 20 个 SVG 操作与已实现的 alpha-preserve 扩展。未知属性保存不等于支持其语义。未支持的矢量特性、未知操作、未支持的色彩配置与其他编码可按条件查看结构或已有预览；不承诺转换、栅格化或重新渲染，不能静默丢层或导出旧预览。

输入归档 256 MiB、最多 4096 条目、单条展开 64 MiB、总展开 256 MiB；解码图层总像素预算 128 MiB。每张图与画布最多 16,777,216 像素、单边 16,384；树深 128。合成有 256 MiB 保守逻辑缓冲预算，实际对象开销另计。浏览器导入上限 32 MiB。

许可证检查继续覆盖 29 个二进制资源、10 个运行组件、完整 Apache/OFL/CC 文本与上游 NOTICE，并测试缺失全文和截短 NOTICE 必须失败。
