fix: disable particle speed color by default

docs/50_Step记录/STEP-084_正式粒子速度着色默认关闭与红头修复_v1.md

@@ -0,0 +1,50 @@
+# STEP-084 正式粒子速度着色默认关闭与红头修复 v1
+
+状态：`完成（等待 STEP-085 后由 RDC 统一执行 Native/真机验收）`
+
+## 1. 目标
+
+修复 NavSea 天气正式粒子在 Android/iOS 均出现橙红色“头部”的问题。正式 `RasterParticleLayer` 默认应严格使用宿主显式提供的 `particleColor`；速度着色只作为显式 opt-in 能力保留，不再作为正式粒子的默认行为。
+
+## 2. 基线
+
+- 机器：Mac-mini-tei.lan。
+- 工作仓库：`/Users/tei/dev/MapLibreParticleLab-step084`，独立 worktree，避免触碰主 Mac 工作树既有 dirty/untracked。
+- branch：`step/084-particle-speed-color-default-off`。
+- start commit：`91d4859121afef98e05efac923797b31835a49df`（tag `maplibre-particle/rn/13.4.1-particle.7`）。
+- Integration repo 已同步并核对 `main`；本修正不改变 RN 公共 API、QBIN/Field contract 或 NavSea/Particle 责任边界。
+
+## 3. 根因
+
+正式 fragment/Metal shader 在 `speedColorEnabled=true` 时，会对当前粒子段覆盖 `particleColor`，使用内置速度色带；高速端为橙红色。`RasterParticleLayer::Impl` 当前默认值为 `true`，因此 Host 未显式设置该属性时，Android OpenGL 与 iOS Metal 都会出现同样的红头。
+
+## 4. 必做项
+
+- [x] 将正式 `RasterParticleLayer` 的 `speedColorEnabled` 默认值改为 `false`。
+- [x] 将 `ParticleGpuResources` 初始默认值同步为 `false`，避免资源首次创建后、视觉属性同步前出现单帧速度着色。
+- [x] 保留 shader 中速度着色逻辑和显式 setter，不删除 Validation/Test 能力。
+- [x] 更新 `Layer.RasterParticleVisualProperties` 回归测试：默认必须为 OFF，显式打开后仍可为 ON，再可关闭。
+- [x] 默认 OFF → 显式 ON → 再 OFF 的 Core Layer 回归语义已由定向测试源码断言覆盖；未运行测试二进制。
+- [x] `ParticleGpuResources` 初始值、RenderLayer visual-property 同步和 shader UBO 开关的静态调用链已复核。
+- [x] `git diff --check` 通过。
+- [x] scoped commit 并 push 到 `origin/particle/main`（commit 与远端确认见本轮最终交付）。
+- [ ] Mac Metal 精确编译、Android Native/AAR 编译与 Android/iOS 设备验收：`BUILD_NOT_RUN_BY_CODEX — WAITING_FOR_RDC`。任务书要求与 STEP-085 性能修复合并验收，故本 Step 不单独声称平台 PASS。
+
+## 5. 禁止范围
+
+- 不修改 QBIN V4、FieldProfile、Runtime Window、时间插值或天气数据。
+- 不增加 iOS/Android 专用公共协议，不增加 RN 平台分叉。
+- 不修改 NavSea。
+- 不删除 speed-color 能力；只改变正式层默认值。
+- 不执行 Android Gradle/AAR/APK 编译、安装或 ADB 操作；Android 构建仍由用户手工执行。
+
+## 6. 验收语义
+
+默认情况下 `current ? particleColor : trailColor` 选择完成后，不再进入 `particleSpeedColor(...)` 覆盖分支；只有调用方显式打开 speed-color 时才允许速度色覆盖当前粒子段。由于 OpenGL GLSL 与 Metal shader 共用同一 `speedColorEnabled`/UBO 语义，本修正应在重新构建各平台 Native 后同时生效。
+
+## 7. Codex 静态收尾
+
+- 远端 `origin/particle/main` 在本 Step 开始时与 start commit 一致；现有 dirty 仅含任务书列出的三处源码/测试修改及本 Step 记录，未混入 STEP-085 性能代码。
+- `RasterParticleLayer::Impl` 默认值与 `ParticleGpuResources` 的资源首帧默认值均为 `false`；显式 setter 及 shader speed-color 分支保持不变。
+- `Layer.RasterParticleVisualProperties` 明确覆盖 default OFF、set ON 与 set OFF，因此正式宿主未设属性时不再选择内置速度色带，诊断/显式 opt-in 仍然可用。
+- 未执行任何 Native 编译、链接、artifact、Gradle、ADB、iOS 安装或真机工作；这些项目由 RDC 在 STEP-085 后统一验收。

src/mbgl/renderer/layers/render_particle_validation_layer.cpp

@@ -361,7 +361,9 @@ public:
     float trailOpacity = 1.0f;
     float trailFade = 0.92f;
     float advectionScale = 1.0f;
-    bool speedColorEnabled = true;
+    // Match the formal layer default so a newly allocated resource cannot emit
+    // one speed-colored frame before evaluated visual properties synchronize.
+    bool speedColorEnabled = false;
     std::array<float, 4> particleColor{0.08f, 0.55f, 1.0f, 1.0f};
     std::array<float, 4> trailColor{1.0f, 1.0f, 1.0f, 1.0f};
     uint8_t fixtureMode = 255;

src/mbgl/style/layers/raster_particle_layer_impl.hpp

@@ -28,7 +28,9 @@ public:
     // scale is deliberately independent from field metadata and only applies
     // when VectorSemantics is Direction.
     float advectionScale = 1.0f;
-    bool speedColorEnabled = true;
+    // Formal particles honor the explicit particleColor by default. Speed-based
+    // head coloring remains available as an explicit opt-in diagnostic mode.
+    bool speedColorEnabled = false;
     std::array<float, 4> particleColor{{0.08f, 0.55f, 1.0f, 1.0f}};
     std::array<float, 4> trailColor{{1.0f, 1.0f, 1.0f, 1.0f}};
     DECLARE_LAYER_TYPE_INFO;

test/style/style_layer.test.cpp

@@ -143,8 +143,10 @@ TEST(Layer, RasterParticleVisualProperties) {
     EXPECT_FLOAT_EQ(1.0f, layer.getParticleOpacity());
     EXPECT_FLOAT_EQ(1.0f, layer.getTrailOpacity());
     EXPECT_FLOAT_EQ(0.92f, layer.getTrailFade());
-    EXPECT_TRUE(layer.isSpeedColorEnabled());
+    EXPECT_FALSE(layer.isSpeedColorEnabled());
 
+    layer.setSpeedColorEnabled(true);
+    EXPECT_TRUE(layer.isSpeedColorEnabled());
     layer.setLineWidth(4.0f);
     layer.setParticleLength(0.030f);
     layer.setParticleOpacity(0.45f);

粒子开发记录.md

@@ -1,5 +1,11 @@
 # 粒子开发记录
 
+## 2026-09-19 — STEP-084 正式粒子速度着色默认关闭
+
+- 正式 `RasterParticleLayer` 与初始 `ParticleGpuResources` 的 `speedColorEnabled` 默认值均改为 `false`，使未显式配置时严格使用宿主 `particleColor`，避免内置高速橙红色带在首次资源创建前覆盖粒子颜色。
+- speed-color shader 分支、公开 Core setter 与 Android Validation UI 显式开关均保留；`Layer.RasterParticleVisualProperties` 覆盖默认 OFF → 显式 ON → 再 OFF。
+- Codex 仅完成源码静态审计和 `git diff --check`，未执行 Native 编译、链接、artifact、设备或真机验证；颜色验收将与 STEP-085 renderer 性能修复由 RDC 统一进行。
+
 ## 2026-08-27 — STEP-000
 - 建立正式 Ubuntu MapLibreParticleLab 工作目录。
 - MapLibre core：18545ca10d296704b2cba675b182ff2c8da24588