# STEP-058 Weather-local Target FPS 与 Repaint Gate

状态：`IMPLEMENTED / WAITING_ANDROID_VALIDATION`

Starting HEAD：`6d514e3aae68f579af41b10f85efe0f3b28784b2`，分支 `particle/main`。

## 目标

为天气粒子与 WeatherColor 建立 source-local AUTO/30/60 cadence 和 repaint gate，不限制全局 Map FPS，不进入 React Native package。

## 已完成

- `WeatherRuntime.TargetFps`、`setTargetFps()`、`getTargetFps()` typed Host API，经 `MapLibreMap → NativeMapView → JNI → RasterArraySource` 接线。
- `RasterArrayTimelineRuntime` 持有单一 target/deadline authority；Particle 与 WeatherColor 共用 due 判定，真实 `steady_clock` elapsed 驱动 Timeline、particle lifecycle 与 Trail fade。
- 未到 deadline 的地图高频帧不推进天气 State/Trail/Timeline；Android facade 使用既有 `triggerRepaint()` 低频 delayed wake-up，不调用全局 `setMaximumFps()`。
- REAL WEATHER popup 增加 FPS AUTO/30/60，HUD 显示当前选择；两层 visibility、PLAY/PAUSE、clear/disabled 的持续 wake-up 规则已收敛。
- 增加 deterministic cadence 测试，覆盖 AUTO、30/60 deadline、target 切换与单 authority。

## 保护与禁止范围

canonical field、field bytes、submit result、timestamp、playback、WeatherColor ramp、particle/trail color、OFF unload、hidden cleanup、Runtime Field Window、OLD_T1→NEW_T0 reuse、only NEW_T1 upload、simulation/trail reset 保护均未重写；未新增 RN/provider/route/ETA/Jest，也未使用全局 Map FPS cap。

## 验证

- throttle 下 Linux/OpenGL `mbgl-test-runner` 与 `mbgl-render-test-runner` 增量构建：PASS。
- throttle 下 deterministic cadence 测试 `Source.RasterArrayTimelineCadenceUsesOneSharedDeterministicDeadline`：PASS。
- throttle 下 `Source.RasterArray*` 定向测试：PASS。
- `git diff --check`：PASS。
- 未执行 Android Gradle、APK、ADB、设备/虚拟机测试或 Jest。

## 剩余风险

Android JNI/Java compile 与设备上 30/60 tick、camera 并发、visibility/off wake-up 仍需统一人工验收；天气 camera skipped-frame composite 的具体 GPU 视觉连续性需实机确认。

## STEP-058A Shared Cadence 与 WeatherRuntime 生命周期修正

状态：`IMPLEMENTED / WAITING_ANDROID_VALIDATION`。

- 以 `RasterArrayTimelineRuntime::advanceIfDue()` 取代 renderer 单独 `tick()`，在 timeline 锁内原子完成 deadline claim、revision 标记和 wall-time 推进。WeatherColor-only + PLAY 可独立推进 MIX；同一 deadline Particle 后到仅消费相同 frame/revision，不会双推进。
- WeatherColor-only + PAUSE 不主动持续 repaint；Particle visible + PAUSE 保持粒子 cadence；两层 hidden、clear/disable 不再由 facade 保留 delayed wake-up。
- 新增幂等 `WeatherRuntime.dispose()`；disposed 后取消 callback、旧 Runnable 不 repaint/不重排，控制 API 拒绝或 fail-fast。Test App 在 style reload、leave REAL WEATHER、Activity destroy 前显式释放旧 Runtime。
- Linux/OpenGL 增量 build、`Source.RasterArray*` deterministic/source 定向测试和 `git diff --check` 通过；Android Gradle/APK/ADB/设备/Jest 未执行。