docs: record STEP-058 weather cadence

docs/30_设计/STEP-058_WeatherLocalTargetFps与RepaintGate设计_v1.md

@@ -0,0 +1,25 @@
+# STEP-058 Weather-local Target FPS 与 Repaint Gate 设计
+
+## Host contract
+
+`WeatherRuntime.TargetFps` 只提供 `AUTO`、`FPS_30`、`FPS_60`，默认 `AUTO`。`WeatherRuntime.setTargetFps()` 返回 typed `CommandResult`，`getTargetFps()` 返回当前 Host 选择。Host 不接触 RenderLayer、deadline、`needsRepaint()` 或 renderer `requestRender()` 细节；未来 RN 只包裹该 facade 方法。
+
+## Shared cadence authority
+
+天气 cadence 归 `RasterArrayTimelineRuntime` 所有，与 source 的 T0/T1、MIX、playback 共存。它保存 target mode、单一 monotonic last cadence tick、deadline 判定和低频 tick 计数。Particle 与 WeatherColor renderer 都读取同一 timeline authority；没有各自 timer 或 gate。AUTO 始终 due，30/60 使用约 33.33/16.67ms 间隔，且 target 切换重置 cadence deadline，不改变 Timeline/field/window。
+
+`tick()` 仅在 deadline 到达时推进真实 `steady_clock` elapsed；不把 1/30 或 1/60 写入 simulation delta。这样 particle lifecycle、Trail fade、Timeline playback 和速度仍使用真实 wall time。
+
+## Repaint 与 delayed wake-up
+
+`RenderRasterParticleLayer::needsRepaint()` 与 `RenderWeatherColorLayer::needsRepaint()` 共享 source timeline 的 due 判定。Android `WeatherRuntime` 使用已有 `MapLibreMap.triggerRepaint()` 作为最小 delayed wake-up seam，在 READY 且至少一层需要天气持续动画时按目标间隔唤醒；AUTO 不安装天气 wake-up。Runtime disable/clear、两层 hidden 或错误状态会停止 wake-up。未使用 `MapView#setMaximumFps()`，因此 camera/其他 layer 仍可保持地图自身帧率。
+
+地图高频 camera frame 在未到 deadline 时只重用现有粒子/Trail composite，不推进 State、Trail、Timeline 或 field upload；天气到 deadline 后两层再次消费同一 cadence。WeatherColor visibility 不依赖 particle visibility：Particle hidden + WeatherColor PLAY 仍可唤醒；两层 hidden、WeatherColor PAUSE 且 Particle hidden 时不持续唤醒。
+
+## 动态修改与边界
+
+target 切换仅更新 source/timeline cadence，不 reload Style、不重提交 field、不 reset particle State、不 clear Trail、不重建 field texture。clear/disabled 后 timeline 被清空，cadence naturally 无 due frame。Core 保留 canonical U/V、T0/T1/MIX、Runtime Field Window、OLD_T1→NEW_T0 reuse 与 only NEW_T1 upload。
+
+## 测试策略
+
+cadence deadline 通过显式 `steady_clock::time_point`/duration 的 deterministic 测试验证，不使用 sleep：AUTO always due、30/60 deadline 前后、target switch 和 single-authority 行为。Android popup 仅作为 Host 模拟器提供 FPS AUTO/30/60 与 HUD 显示；Android Gradle/设备验收另行执行。