ADR-0100：显式画刷与离线 SVG 资源

状态

已采纳。

背景

逐次 RGB 透明度不能表达印刷分色、渐变、重复图案或整体透明组。将这些需求隐式栅格化会隐藏精度、油墨名称及资源预算变化；让后端重新解释 SVG 则会破坏绘制列表的共同契约。

决策

1. 图形 API 使用自有不可变 ColorValue、Paint 和 BlendMode。旧 RGB 绘制入口保持；高级绘制使用显式画刷命令、路径绕组与嵌套隔离组。嵌套资源独立平衡状态，并纳入有限递归与累计资源预算。
2. PDF 保留原生颜色空间、函数着色、软蒙版、图案及透明 Form。图案矩阵以所在内容流的默认坐标为基准，组合页面翻转和局部变换；带外层透明度／混合的整幅图案绘制先写入隔离 Form，再合成一次，避免不同阅读器重复应用图案透明度。
3. SVG 输出生成文档内唯一资源 ID，保存画刷、变换、裁剪和混合。PNG 按显式 DPI 完成相同绘制语义，不调用文字塑形或隐式字体选择。
4. 无法保存印刷空间的目标默认拒绝。调用方选择 WARN／IGNORE 加 DEGRADE 后，输出显式 RGB 外观，并在实际报告中保留损失。不同颜色空间的 PDF 渐变同样需要显式转换授权；预算、取消、非法输入和 I/O 错误不服从忽略策略。
5. SVG 导入在组件层解析有限本地资源图，输出通用绘制命令；引用必须为本地 ID，检测循环、悬空与展开预算。渐变、图案、标记和裁剪均在此层解析，不向后端传递 DOM 或外部句柄。

后果

PDF 的矢量和分色资源可独立检查；SVG／PNG 的颜色空间损失可以由调用方选择处理。嵌套图案与组增加了资源遍历要求，字体轮廓转换、预检和后端必须递归处理。SVG 导入保持明确子集，浏览器完整 CSS、过滤器、动画及文字布局不属于此契约。

验收必须同时覆盖原生文件结构和可见内容：最终 PDF 双渲染、最终 SVG 独立渲染、源 SVG Chromium 对照、透明度与混合像素控制、引用／预算拒绝及独立归档合规检查。接口和可复现入口见高级图形 API。