# N-017 Paint 与权重

状态：`BLOCKED`（stroke/patch schema、真实 Three raycast 命中、选择/遮罩门和 Main 顶点色/权重
transaction 已落地；PBVH brush、texture paint 和 GPU/image 生命周期未实现）

## 已验证切片

1. N-017-A（部分）：`PaintStrokeIR` 覆盖 Vertex Color、Weight、Texture Paint，携带
   object/revision、radius/strength、pressure、PBVH face/barycentric hit 和 UV hit。
2. N-017-A（部分）：`WeightPatchIR` 覆盖有界 vertex index/value、normalize 和 mirror 意图。
3. 预算限制为单 stroke 100k samples/64 MiB 估算、单 weight patch 1M entries、单 texture
   tile 256 MiB；非法 barycentric、pressure、color、weight 和非有限数会结构化拒绝。
4. N-017-B（部分）：`setVertexColors` 在单用户 Mesh 上创建/转换 `POINT` 或 `CORNER`
   `FLOAT_COLOR` 属性，并更新 active color；`setVertexWeights` 在真实 Object/Mesh 上创建顶点组、
   写入/移除 `MDeformWeight`，支持逐顶点 normalize。
5. 顶点色和权重都已通过 Main undo/redo 与 `.blend` save/reopen；`mirror:true` 在没有已验证
   对称拓扑映射时返回 `CAPABILITY_MISSING`，不会伪造镜像结果。
6. `paintHitFromIntersection` 消费真实 Three `Raycaster` intersection，按 indexed/non-indexed
   triangle 解析顶点，输出对象/data stable ID、source face、局部 barycentric、世界法线、
   插值 UV 与 pressure；测试使用真实 BufferGeometry 射线，不注入伪命中。
7. Properties paint 面板消费 viewport 的真实 VERT selection，可向选中顶点提交 `POINT`
   `WebPaintColor` 和 vertex group weight；每次操作只发一个既有 Main transaction，继续使用
   revision、undo/redo、save/reopen 边界。它不是 PBVH brush 或 texture paint。
8. N-017-A/C（协议边界）：有界 CPU brush 对候选顶点执行 smoothstep falloff、遮挡标记过滤和
   front-face 法线门；它不宣称 PBVH 加速或桌面 brush 等价。`UdimTilePatchIR` 约束 1001-1999
   tile、RGBA8、色彩空间、尺寸/256 MiB 预算、revision、base/result SHA-256，并在内存中验证
   原子 range patch；尚未绑定 Blender packed image/UDIM Main 写回与保存。
9. N-017-A（空间查询部分）：uniform-grid spatial index 在 1M vertex/1M cell 预算内按 brush AABB
   粗筛候选，再执行球半径、front-face、falloff 精筛；depth-gated 查询必须显式提供已验证可见
   vertex ID 集合，缺失或重复会拒绝。该结构减少全量扫描，但不是 Blender PBVH。
10. N-017-A/B（选择与遮罩部分）：brush query 可要求稳定 vertex identity 的 selection 硬门，并以
    `[0,1]` mask weight 乘入 falloff；重复、未知或越界 identity 会拒绝。颜色和权重 patch 以当前
    revision、当前值、目标值及 brush weight 确定性混合，过期 revision 不会提交。
11. Properties paint 面板可对当前真实 VERT selection 执行 selection-masked `Blend Color` 和
    `Blend Weight`，每次仅提交一个 Main transaction。Blender 5.2 reader 从 Mesh
    `vertex_group_names` 恢复顶点组摘要及 skin weight 名称；新增组经 undo/redo、保存重开后保持。

## 仍然阻断

- N-017-A：真实 PBVH、由 viewport 深度缓冲生成可见 vertex 集合，以及 brush falloff 桌面
  golden；基础 Mesh/UV hit、uniform-grid 候选查询和可见性硬门已完成。
- N-017-B：limit/clean、已验证拓扑映射上的 mirror、桌面 brush/falloff 对照。
- N-017-C：Blender packed/UDIM tile Main transaction、dirty tile、色彩转换和原子保存；当前
  只有内容哈希绑定的浏览器内存 patch 边界。
- N-017-D/E：armature golden、seam bleed、face mask、GPU dispose、quota、坏图和桌面 UI 对照；
  vertex selection 与数值 mask 门已完成，不等同于完整 Paint 面/纹理遮罩系统。

## 验收

```bash
WEB_TEST_PORT=5203 npm --prefix web run test:e2e -- --grep "N-017 paint"
npm --prefix web run test:paint-roundtrip
```

`test:paint-roundtrip` 覆盖 CORNER color、vertex group patch、normalize、mirror 错误门、
undo/redo 与 save/reopen。