workinf_Blender_Wasm/docs/status/N-017.md

N-017 Paint 与权重

状态：BLOCKED（stroke/patch schema、真实 Three raycast 命中、GPU depth 可见性、选择/遮罩门、 单 undo 分块 pointer session、Main 顶点色/权重、浏览器 packed/UDIM 原子资产绑定和 PBVH WASM 入口显式能力门已落地； PBVH brush、Blender Main image tile 写回、完整色彩转换和 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、最多 32 个 influence 的 limit，以及 基于局部坐标 reciprocal map 的 mirror。
5. 顶点色和权重都已通过 Main undo/redo 与 .blend save/reopen；镜像在没有已验证对称映射时 返回 CAPABILITY_MISSING，不会伪造结果。limit/normalize/mirror 的组合已与 Blender 5.2 desktop golden 逐顶点比较。
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。
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、保存重开后保持。
12. M9-09：主线程和 Offscreen Worker 使用同一 WebGL2 RGBA depth pass/readback， 以 Main revision 和稳定顶点索引返回真实可见集；遮挡 fixture 的两后端结果一致。
13. M9-10：WebEngine Worker 可序列化接收有界 color/weight chunks，一次 pointer session 仅在 commit 时对 Main 发一个合并命令；真实 Main 历史只产生一个 undo step。
14. M9-11：Storage Worker 将 packed/UDIM PNG 解码为 RGBA8，复验 dirty range 的 base/result pixel hash，新 PNG 经 OPFS content-addressed 临时写、回读验证后， 才以 IndexedDB 单事务切换 tile binding。中途故障保持旧 binding/旧资产可读， packed 与 UDIM 均已通过 Worker restart 回读。
15. M9-12：WeightPaintOptionsIR 固定 normalize、limit、mirror axis/tolerance 和 1M patch budget；Worker 拒绝重复/越界/非法组合，native 在 Main 内先写入 patch，再做 mirror、limit、normalize。镜像 map 使用 mesh 局部坐标，要求每个顶点都有 reciprocal counterpart，且大于 100k 顶点时结构化预算阻断。rigged_shape_scene.blend 的四步 golden（initial/normalize/limit-normalize/mirror）与 WASM snapshot、save/reopen 逐项一致。
16. M9-13：按 Blender 5.2 DNA_brush_enums.h 冻结 32 个 Sculpt、4 个 Vertex Color、 4 个 Weight 和 6 个 Texture 活跃 brush。生产 WebEngine Worker 探测 _web_engine_apply_pbvh_stroke；当前 stable/single/pthread 均无该 WASM 入口，因此 46 项 全部返回 N-017/BLOCKED/PAINT_PBVH_UNAVAILABLE。即使未来出现入口，session context 和 逐 brush desktop/WASM golden 未就绪时仍分别失败关闭；查询不会修改 Main revision、handle 或 WASM allocated bytes，畸形字段返回完整标准 ErrorReport。

仍然阻断

• N-017-A：真实 PBVH 与 brush falloff 桌面 golden；基础 Mesh/UV hit、uniform-grid 候选 查询、可见性硬门和双后端 GPU depth 可见集已完成。当前不存在 PBVH WASM writer，完整 brush inventory 由 PAINT_PBVH_UNAVAILABLE 明确阻断，不会把 bounded helper 当作成功。
• N-017-B：clean/高级 Blender weight-paint operator、真实 PBVH brush/falloff 与更大拓扑的 桌面对照；当前 bounded limit/normalize/verified mirror 已完成。
• N-017-C：Blender packed/UDIM tile Main transaction、完整色彩转换和 .blend 内 image tile 保存仍阻断；浏览器 dirty tile 的 OPFS 原子 asset/binding 边界已完成。
• N-017-D/E：armature golden、seam bleed、face mask、GPU dispose、quota、坏图和桌面 UI 对照； vertex selection 与数值 mask 门已完成，不等同于完整 Paint 面/纹理遮罩系统。

验收

WEB_TEST_PORT=5203 npm --prefix web run test:e2e -- --grep "N-017 paint"
npm --prefix web run test:paint-roundtrip
WEB_TEST_PORT=5422 npm --prefix web run test:texture-paint-asset
WEB_TEST_PORT=5427 npm --prefix web run test:paint-pbvh-capability

test:paint-roundtrip 覆盖 CORNER color、vertex group patch、normalize、limit、verified mirror、undo/redo 与 save/reopen；test:weight-paint-golden 对比 Blender 5.2 desktop golden。