docs: record STEP-057D WeatherRuntime API freeze

docs/50_Step记录/STEP-057D_WeatherRuntime接口收尾与RN桥接前冻结_v1.md

@@ -0,0 +1,31 @@
+# STEP-057D WeatherRuntime 接口收尾与 RN 桥接前冻结
+
+状态：`IMPLEMENTED / READY_ANDROID_COMPILE_CHECK`
+
+基线：`01295df4b814562f569375e7e7cf1f48ce35388f`，分支 `particle/main`。
+
+## 目标与范围
+
+本 Step 只收紧 Android Host `WeatherRuntime` 公共接口，为后续 RN 薄桥接冻结边界；不实现 RN/TurboModule/JSI，不修改 provider、Timeline、Runtime Field Window、canonical field、shader、UBO 或 renderer 架构。
+
+## 已完成
+
+- 新增 `WeatherRuntime.setParticleColor(r,g,b,a)` 与 `setTrailColor(r,g,b,a)`，分别通过 JNI 进入 Core 的独立 `RasterParticleLayer::setParticleColor` / `setTrailColor`。两者不提交 field、不影响 WeatherColor ramp、不重置 Timeline 或粒子模拟。
+- 保留 `setParticleColors(...)` 作为兼容 helper，继续使用原子成对底层提交；新 Host/RN 契约使用两个独立 typed 方法。Core 既有 `particleColor=(0.08,0.55,1,1)`、`trailColor=(1,1,1,1)` 默认值不在 facade 重建或猜测。
+- REAL WEATHER 数据提交改用 `WeatherRuntime.FieldSubmitResult` 与 `accepted()`/enum 名称，不再用 `getCode()` 或整数比较组织正常 Host 路径。
+- REAL WEATHER playback/visual 正常路径遇到不支持命令或 property 时不再回退到 `MapLibreMap` 低层调用。旧 fixture、HOST、diagnostic time-mix/field-window 入口保留为 legacy/diagnostic 路径。
+- 增加独立颜色 API 的现有 JUnit/Mockito 定向源码覆盖，包含独立调用、参数隔离和 native rejection fail-closed。
+
+## 低层入口审计
+
+- A 类（REAL WEATHER）：field submit、play/pause/speed、已支持粒子视觉属性均经 `WeatherRuntime`；独立 particle/trail color 也经 `WeatherRuntime`。
+- B 类（legacy/diagnostic）：fixture/HOST INVALID/DUPLICATE、ADVANCE WINDOW、time-mix 及旧诊断 property 仍可直接使用 `MapLibreMap`，仅供既有验证工具，不构成未来 RN contract。
+
+## 验证与未执行
+
+- 已执行 `git diff --check` 与源码静态审计（typed API、`getCode()` 使用、REAL WEATHER fallback 边界）。
+- 未执行 Android Gradle/APK、ADB、设备/虚拟机测试或 Jest；Android compile check 留待后续统一授权。
+
+## 剩余风险与下一步
+
+JNI/Android Java 编译及 Mockito 配置仍需 Android compile check；设备上的独立颜色视觉效果和 style reload/资源生命周期需后续人工验收。代码边界已冻结，可进入 RN 薄桥接前独立审计。

docs/报告/STEP-057D_WeatherRuntime接口收尾与RN桥接前冻结_Codex完成报告_v1.md

@@ -0,0 +1,50 @@
+# STEP-057D WeatherRuntime 接口收尾与 RN 桥接前冻结 — Codex 完成报告
+
+状态：`IMPLEMENTED / READY_ANDROID_COMPILE_CHECK`
+
+## 实际完成内容
+
+本轮基于 `01295df4b814562f569375e7e7cf1f48ce35388f`，完成 Host facade 收尾，不进入 STEP-058，不实现 RN/JSI/TurboModule。
+
+- 新增 `WeatherRuntime.setParticleColor(float,float,float,float)` 与 `setTrailColor(float,float,float,float)`，经独立 JNI setter 进入 Core。两者互不提交另一颜色，不影响 WeatherColor ramp、field、Timeline、Runtime Field Window 或粒子模拟。
+- 保留 `setParticleColors(...)` 兼容 helper，继续使用原子成对底层 setter；不在 facade 猜测默认值。Core 默认值仍由 `RasterParticleLayer::Impl` 所有。
+- REAL WEATHER submit 改用 `FieldSubmitResult` 与 `accepted()`/enum 日志，不再使用 `getCode()` 或整数结果做正常 Host 业务判断。
+- REAL WEATHER 的 playback 和 typed visual 属性不再回退到 `MapLibreMap` 低层接口；旧 fixture、HOST、time-mix、field-window 与 diagnostics 入口保留并明确属于 legacy/diagnostic。
+- 增加独立颜色 API、隔离性及 native rejection fail-closed 的既有 JUnit/Mockito 测试源码。
+
+## 修改文件
+
+- `platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/WeatherRuntime.java`
+- `platform/android/MapLibreAndroid/src/main/java/org/libre/android/maps/MapLibreMap.java`
+- `platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMap.java`
+- `platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMapView.java`
+- `platform/android/MapLibreAndroid/src/cpp/native_map_view.hpp`
+- `platform/android/MapLibreAndroid/src/cpp/native_map_view.cpp`
+- `platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt`
+- `platform/android/MapLibreAndroid/src/test/java/org/maplibre/android/maps/WeatherRuntimeStateTest.java`
+- `docs/50_Step记录/STEP-057D_WeatherRuntime接口收尾与RN桥接前冻结_v1.md`
+- `粒子开发记录.md`
+
+## API 与旁路边界
+
+正式 Host/RN API 使用独立 `setParticleColor`/`setTrailColor`、typed field result、typed playback 与 typed visual 方法。A 类 REAL WEATHER 正常控制均经 `WeatherRuntime`。B 类 legacy/diagnostic 仍可直接调用 `MapLibreMap`，仅服务 fixture、HOST INVALID/DUPLICATE、ADVANCE WINDOW、time-mix 和旧诊断，不构成 RN contract。
+
+## 验证
+
+- `git diff --check`：PASS（功能提交前及文档收尾前均执行）。
+- `rg` 源码审计：确认 REAL WEATHER 不再使用 `submitWindField(...).getCode()`，且 REAL WEATHER 不走 timeline/property 低层 fallback。
+- 未执行 Android Gradle、APK build、ADB、设备/虚拟机测试或 Jest。
+- 未执行 noisy compile/test；Android compile check 留待后续统一授权。
+
+## 已知剩余风险
+
+Android Java/JNI 编译、Mockito final-class 配置和设备上的独立颜色视觉效果尚未运行验证；需后续 Android compile check 与人工验收。未改变 Core/render 生命周期，未引入 RN bridge。
+
+## Git
+
+- 功能 commit：`544e4aee3`（完整 SHA 在下方最终交付信息中列出）
+- commit message：`fix: finalize WeatherRuntime host API boundary`
+- 文档提交：待文档收尾提交后记录
+- Push：待文档收尾提交后记录
+- Remote branch：`origin/particle/main`
+- Final HEAD：待文档收尾提交后记录

粒子开发记录.md

@@ -475,3 +475,9 @@ WeatherColorLayer 的 `ParticleGpuValidationUBO` designated initializer 补齐 `
 - Android x86_64 CMake 编译发现 `jni::Array<jfloat>` 误用底层 5 参数 `jni::GetArrayRegion`，导致 `native_map_view.cpp` 四处编译失败。
 - 已改为 `jni::Array::GetRegion()`，只修正 particle/trail 与 WeatherColor stops 的数组读取，不改变业务语义或渲染生命周期。
 - 功能提交：`4f76245533817751f4e24f76e47e856c35fb23c7`；Android Gradle/设备验证由用户重新执行。
+
+## 2026-09-07 — STEP-057D WeatherRuntime 接口收尾与 RN 桥接前冻结
+
+- `WeatherRuntime` 新增独立 typed `setParticleColor()` / `setTrailColor()`，分别委托 Core 独立颜色 setter；保留原 `setParticleColors()` 作为兼容成对提交 helper，不猜测或复制 Core 默认色值。
+- REAL WEATHER submit 使用 `FieldSubmitResult`/`accepted()` 与 enum 日志，不再依赖 `getCode()`；REAL WEATHER 的 playback/visual 不再回退到 MapLibreMap 低层入口，旧 fixture/diagnostic 路径继续保留。
+- 本轮仅执行 `git diff --check` 与源码静态审计；未执行 Android Gradle、APK、ADB、设备测试或 Jest，状态为 `IMPLEMENTED / READY_ANDROID_COMPILE_CHECK`。