From faf7548220e9a1282275711c236987f7faedfa03 Mon Sep 17 00:00:00 2001
From: OpenAI Codex <codex@local>
Date: Sat, 5 Sep 2026 19:02:54 +0800
Subject: [PATCH] docs: record STEP-056 bridge investigation

---
 ...6_RN天气渲染桥接现状调查_Codex完成报告_v1.md | 57 +++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 docs/报告/STEP-056_RN天气渲染桥接现状调查_Codex完成报告_v1.md

diff --git a/docs/报告/STEP-056_RN天气渲染桥接现状调查_Codex完成报告_v1.md b/docs/报告/STEP-056_RN天气渲染桥接现状调查_Codex完成报告_v1.md
new file mode 100644
index 000000000..43f0f1a59
--- /dev/null
+++ b/docs/报告/STEP-056_RN天气渲染桥接现状调查_Codex完成报告_v1.md
@@ -0,0 +1,57 @@
+# STEP-056 React Native 天气渲染桥接现状调查 — Codex 完成报告
+
+## 调查状态
+
+`PASS`（只读调查完成）。本阶段没有实现 React Native bridge。
+
+- Starting HEAD：`44a50e6e4a4e79fae7ddf36af007b5e35e969a92`
+- 分支/远端：`particle/main` / `origin/particle/main`
+- 调查文档提交：`f37f6eea1f7720c64b2cc949938f29539422b480`
+- 提交信息：`docs: investigate React Native weather rendering bridge`
+- Push：成功，`44a50e6e4..f37f6eea1 particle/main -> particle/main`
+- 本报告生成时的已推送调查 Final HEAD：`f37f6eea1f7720c64b2cc949938f29539422b480`
+
+## 范围与实际检查
+
+检查了 canonical field Adapter/Snapshot、RasterArraySource Host submission 与 Timeline、RasterParticle/WeatherColor style 与 renderer、shader 固定色表、Android `MapLibreMap`/`NativeMapView`/JNI、Android Test App REAL WEATHER 调用、Map render request/FPS 以及 layer/source resource destruction。
+
+没有修改功能代码；没有执行 Android Gradle、APK build/install、ADB、App/设备测试或 Jest。
+
+## RN bridge 结论
+
+没有可直接复用的 RN binding：仓库无 tracked React Native、TurboModule、Fabric、JSI 或 NativeModule。已有并可复用的是 Android Host Field path：
+
+`MapLibreMap.submitRasterArraySourceHostField(String, String, byte[])`
+→ `NativeMapView.nativeSubmitRasterArraySourceHostField`
+→ `NativeMapView::submitRasterArraySourceHostField`
+→ `RasterArraySource::submitHostField`
+→ `ParticleFieldDataAdapter`
+→ `ParticleFieldSnapshot`/Core Timeline/Runtime Window。
+
+Test App 的 `ParticleCoreLayerValidationActivity::submitRealWeatherDataset()` 只是使用 Android asset 模拟未来外部 Host，不是 RN bridge。
+
+## 推荐 binary 路径
+
+513×769 canonical U/V 单帧为 3,155,976 bytes（约 3.01 MiB）。当前 payload 经 asset/`ByteArray`、JNI `GetArrayRegion` 到 `vector<char>`、Adapter 到 Snapshot `vector<float>`，存在多次 CPU materialization/copy。
+
+RN v1 推荐 `ArrayBuffer`/`Uint8Array` → Android module `byte[]` → 现有 JNI，优先稳定正确的 canonical contract；不走巨大 JSON。zero-copy 不是现有能力，只有 profiling 证明 copy/GC 是瓶颈时才增加 direct `ByteBuffer` JNI overload 或 JSI native-buffer seam。
+
+## Runtime unload、颜色与性能
+
+- `visibility=none` 可隐藏 layer，粒子层也停止自身持续 repaint，但不会释放已持有 GPU/Native Snapshot。
+- 完整 `setWeatherEnabled(false)` 可行，但需新低频 lifecycle/clear bridge：停止 playback，remove Particle/WeatherColor layers 以触发 GPU release，clear source timeline/pending fields 或 remove RasterArraySource 以释放 Snapshot。当前没有 `clearWindFields()` 或一条正式 runtime unload API。
+- WeatherColor 仅有 opacity；0–30 m/s palette 硬编码在 `particle_gpu_validation.fragment.glsl::weatherSpeedColor`。dynamic color stops 应新增到 WeatherColorLayer style property/model，并以 uniform/texture 交给 shader 插值。
+- RasterParticle 当前仅有 `speed-color-enabled` 与多项数值属性；没有 `particleColor`/`trailColor`。应新增独立 typed properties，令 speedColor 仅为可选模式，不能由 WeatherColor ramp 隐式决定粒子色。
+- 当前约 60 FPS 是 `RenderRasterParticleLayer::needsRepaint()`、`RenderWeatherColorLayer::needsRepaint()` 经 Map `onUpdate()` 与 Android `requestRender()` 的连续链。`MapView#setMaximumFps()` 是全图 cap，不能作为天气专属 targetFps。weather-local gate 应独立性能批次，并以累计 wall elapsed 保持 lifecycle/motion/Timeline 语义。
+
+## 推荐下一阶段
+
+建议进入 **STEP-057 Android Host Weather Runtime Bridge Foundation**，先实现可由未来 RN module 薄包裹的 Android/Native typed facade：runtime lifecycle/clear、binary submit、timestamp playback controls、visibility/style、低频 structured result/error events、dynamic color stops 与独立 particle/trail color。仓库缺少 RN dependency/host app topology，故不应在此仓库凭空建立可编译 RN package。
+
+weather-local targetFps/repaint gate 建议独立为下一性能批次，避免把 render scheduling 风险混入接口开发。
+
+最大风险为：3 MiB payload 多拷贝带来的内存/GC 峰值；hide/suspend/unload 生命周期混同；以及错误 FPS gate 改变当前 State/Timeline 的 wall-time 行为。
+
+完整证据、文件路径、API mapping 与实施拆分见 [STEP-056 调查报告](../20_调查/STEP-056_RN天气渲染桥接现状调查_v1.md)。
+
+无关未跟踪文件（包括 `STEP-046-e48fa087-review.diff` 与既有 `docs/40_任务/` 文件）未修改、未 stage、未提交。