fix: display formal particle trails

docs/50_Step记录/STEP-040_Android离线Fixture正式粒子最小闭环_v1.md

@@ -36,4 +36,4 @@
 
 ## 当前结果、阻塞与下一步
 
-正式 Source/Layer/RenderLayer 已不依赖 source-less `particle-validation` Layer；历史 validation Layer 只保留为既有验证工具。Android 首次实际启动的 RasterArray source RenderItem 空指针已在 source 内补为合法 no-op RenderItem，保持全局 RenderSource 契约。随后实机日志发现 ACTIVE/STATIC 每帧重置：RenderOrchestrator 的按 source 可渲染性扫描会短暂调用 `markLayerRenderable(false)`，它不是持久 disabled；粒子层原先却在该回调中 `resetSequence()`，每帧清空跨 render 的 frame/slot/seed 状态。已删除该错误 reset 边界，真实重建仍限于 field、viewport、context 与 layer removal；新增状态转换及前 3 帧采样日志。Linux 精确编译、format 与 diff 已通过；Android OpenGL APK 已由本轮构建，最终实机验收仍由用户执行。
+正式 Source/Layer/RenderLayer 已不依赖 source-less `particle-validation` Layer；历史 validation Layer 只保留为既有验证工具。Android 首次实际启动的 RasterArray source RenderItem 空指针已在 source 内补为合法 no-op RenderItem，保持全局 RenderSource 契约。随后实机日志发现 ACTIVE/STATIC 每帧重置：RenderOrchestrator 的按 source 可渲染性扫描会短暂调用 `markLayerRenderable(false)`，它不是持久 disabled；粒子层原先却在该回调中 `resetSequence()`，每帧清空跨 render 的 frame/slot/seed 状态。已删除该错误 reset 边界，真实重建仍限于 field、viewport、context 与 layer removal；新增状态转换及前 3 帧采样日志。最新实机日志确认 simulation 已正常推进但画面静止，根因是正式 layer 的 Composite 仍输出旧 validation stripe/anchors，Trail RGB 只影响 alpha。已以 GLSL source 为唯一输入重新生成 OpenGL header；正式 display mode 现在输出当前 Trail RGB，legacy validation display 保留原 stripe/anchor/world-wrap 分支。Linux 精确编译、shader generator 幂等、format 与 diff 已通过；Android 实机验收仍由用户执行，40-01 保持 `WAITING_MANUAL_VALIDATION`。

docs/报告/40_01_Android正式粒子Trail显示修复_Codex完成报告_v1.md

@@ -0,0 +1,35 @@
+# 40-01 Android 正式粒子 Trail 显示修复 Codex 完成报告 v1
+
+## 1. 结论
+
+已修复“simulation 正常推进但正式 RasterParticle 屏幕主体静止”的 Composite 显示路径。40-01 仍为 `WAITING_MANUAL_VALIDATION`；未运行 Android Gradle、ADB 或真机。
+
+## 2. 实际根因
+
+`RenderRasterParticleLayer` 的 State A/B 与 Trail A/B 已按日志正常推进，Trail pass 也读取当前 State write texture。但是 `particle_gpu_validation` 的 Composite 只把 `u_previous`（Trail）的 RGB 折算为 alpha intensity，最终 RGB 仍无条件输出 30-03 的蓝色 stripe 和黄色 anchors；并且 ACTIVE Composite 的 legacy stripe frame 参数为零。于是 GPU 粒子没有成为可见输出。
+
+## 3. 修复
+
+- `ParticleGpuResources::formalDisplay` 只在正式 `RasterParticleLayer` 建立资源时设为 true，并经现有 UBO 的 `u_mask.z` 传入 shader；不增加第二套 simulation。
+- `FORMAL_PARTICLE` Composite 以当前 Trail texture RGB 为最终 premultiplied color，并以 Trail intensity 决定 alpha。uniform-east 的 State 位置经 Trail 进入 Composite，因此屏幕应可见连续向 east 的 marker/trail 运动；STATIC/FrozenComposite 继续采样最后一个 Trail read slot。
+- `LEGACY VALIDATION DISPLAY` 保留原有 30-03 stripe、anchors、mask、world-wrap 与 antimeridian 分支，不受正式显示模式影响。
+- shader 源唯一为 `shaders/particle_gpu_validation.fragment.glsl`；使用 `node shaders/generate_shader_code.mjs` 生成 `include/mbgl/shaders/gl/particle_gpu_validation.hpp`。生成器会同步规范化 `src/mbgl/shaders/shader_source.cpp`，已保留该生成物以保证二次运行无差异。
+- 增加一次性 `displayMode=FORMAL_PARTICLE|VALIDATION` 日志，以及低频 `trailStateSource` / `compositeTrailSource` 日志，诊断 State→Trail→Composite 的正式数据流。
+
+未改变 Offline fixture adapter、RasterArraySource、RasterParticleLayer、field/NoData、State/Trail ping-pong、mask、ACTIVE/STATIC lifecycle、zero-step bootstrap、FrozenComposite、rotation resource recreation、world wrap、antimeridian 或 RasterArray source RenderItem contract。
+
+## 4. 静态验证
+
+- Linux OpenGL：`render_particle_validation_layer.cpp.o` 精确编译 PASS。
+- 相关现有 C++：`test/style/source.test.cpp.o` 精确编译 PASS。
+- shader generator：连续运行两次后 `particle_gpu_validation.hpp` 与 `shader_source.cpp` 哈希一致，PASS。
+- `clang-format --dry-run --Werror`（受影响 C++）和 `git diff --check`：PASS。
+- 未运行完整 `mbgl-test`：该 target 在本 build tree 仍需 312 个对象，属于与本次 shader 显示修复无关的广泛构建，未把未执行测试描述为 PASS。
+
+## 5. 后续人工验收
+
+用户下一轮仅验收 GLOBAL + ACTIVE + `uniform-east`：正式 RasterParticle 必须肉眼清楚、连续地向 east 移动。通过后再测试 STATIC、uniform-north、Rotation 与 T1-T12。
+
+## 6. Git 收尾
+
+本次修复 commit、push 结果与 `origin/particle/main` 最终 HEAD 在交付收尾后回填。