feat: add ios particle field runtime facade

docs/30_设计/STEP-082_iOS_Native_FieldRuntime_Facade与XCFramework发行设计_v1.md

@@ -0,0 +1,27 @@
+# STEP-082 iOS Native FieldRuntime Facade 与 XCFramework 发行设计 v1
+
+状态：IMPLEMENTED / WAITING_MAC_XCFRAMEWORK_VALIDATION
+
+## 公开边界
+
+新增 `MLNParticleFieldRuntimeConfiguration`、`MLNParticleFieldRuntime` 和 `MLNMapView (ParticleFieldRuntime)`。公开头只依赖 Foundation 与已有 public Objective-C 前置类型；QBIN 以 `NSData` 传入，不暴露 `mbgl`、STL、Core 指针或 `MLNMapView_Private.h`。
+
+Configuration 保存 Host-neutral 的 `sourceIdentifier`、`weatherColorLayerIdentifier`、`particleLayerIdentifier`。它不硬编码 RN ID；后续 RN 可继续传 `rn-weather-fields`、`rn-weather-color`、`rn-weather-particles`。
+
+## 生命周期与 fail-closed
+
+Runtime 被 `MLNMapView` 的 associated object 持有，Runtime 只弱引用 MapView。replace 先 dispose 并移除旧实例，attach 仅在当前 style 同时存在正确 Core 类型的 `RasterArraySource`、`WeatherColorLayer`、`RasterParticleLayer` 且两个 layer 都引用该 source 时成功。任何不满足条件的 style-ready/source/type/layer 错误都以 `NSError` 返回，不创建 source/layer，不替换 style。
+
+每条命令重新从 current MapView/current style 查找并验证三对象；不缓存 `RasterArraySource*` 或任何跨 style 生命周期 Core pointer。因此 style reload 后旧 runtime 不会操作悬空对象，而是 fail-closed，Host 应在 style ready 后 replace/attach。
+
+## V4 转发
+
+`submitEncodedField` 先守住与 Android 相同的 UTF-8 ID 1..64、contract 1..256 KiB、QBIN 1..64 MiB、generation>0 边界，再调用 Core `parseResolvedFieldProfileContractJson(...)` 和 `RasterArraySource::submitEncodedField(...)`。十个 Core stable result 逐值映射为 ObjC enum；facade 生命周期错误不会伪装成 submit result。
+
+Color binding 传递 fieldKey、semantic/group、SCALAR/VELOCITY_COMPONENT/DIRECTION_ANGLE 和 expected unit。Particle binding 保留 VECTOR_COMPONENTS 与 DIRECTION_ANGLE，inactive selector 严格为 `(0, 0)`。forecast time/play/pause/speed 和 clear 都只转发给 Core；T0/T1/mix、boundary reuse、QBIN decoder 与 renderer 不在 ObjC 实现重写。
+
+## 导出与 distribution
+
+`MLNParticleFieldRuntime.h` 列入 `MLN_IOS_SDK_HEADERS`，由现有 `public_hdrs` 进入 `MapLibre.dynamic`，并由 `Mapbox.h` 导入。`MLNMapView_Private.h` 继续仅列于 private list。
+
+`release/maplibre-particle/ios/` 建立 module 名不变的 SwiftPM binary template。后续 STEP-083 的链路固定为：`reactTag -> React View Registry -> Fabric ComponentView -> contentView -> MLNMapView -> public MLNParticleFieldRuntime`。当前 peer dependency 是 MLRN 11.3.6；STEP-083 不建立第二个 Map registry、不把 MLRN private header 作为长期 API，并用 `$MLRN_SPM_SPEC` 令 MLRN 与 Bridge 消费同一 MapLibre binary。

docs/50_Step记录/STEP-082_iOS_Native_FieldRuntime_Facade与XCFramework发行基线_v1.md

@@ -0,0 +1,32 @@
+# STEP-082 iOS Native FieldRuntime Facade 与 XCFramework 发行基线 v1
+
+状态：IMPLEMENTED / WAITING_MAC_XCFRAMEWORK_VALIDATION
+
+## 目标与基线
+
+起始分支 `particle/main`，起始 HEAD `3e03949d3411c830cfff4bf320cd350f5b6a7527`。本 Step 只新增 iOS public V4 facade 和 XCFramework distribution 基线；不重做 STEP-081，也不进入 STEP-083/RN。
+
+## 执行清单
+
+- [x] iOS public Native FieldRuntime facade。
+- [x] MapView-owned replace/current/dispose 生命周期。
+- [x] V4 submit、binding、forecast、clear 转发。
+- [x] style reload/source missing fail-closed 与 public header 无 Core/STL 泄漏。
+- [x] XCFramework public header 构建图接线。
+- [x] distribution-ready 模板和中文设计文档。
+- [ ] macOS XCFramework 成功构建、Headers/symbol/zip SHA-256 验证。
+- [ ] `git diff --check`、scoped commit、push 与最终 HEAD（在实现和文档收尾后执行）。
+
+## 允许与禁止
+
+允许修改 iOS public header/implementation、Bazel public export、release 模板以及指定中文文档。禁止改 QBIN V2、FieldProfile、BindingProjection、renderer/Metal physics、STEP-081 smoke、Android/RN/NavSea；本 Step 未修改这些范围。
+
+## 构建记录与阻塞
+
+macOS 15.7.7 / Xcode 26.3 / Bazel 8.6.0。已执行 `bazel build //platform/ios:MapLibre.dynamic`；在本 facade 编译前，基线 `//:generated_style_code` 失败：`bazel/core.bzl` 要求 generator 输出 `src/mbgl/style/layers/particle_validation_layer.cpp`，但 `scripts/generate-style-code.mjs` 不生成该文件。该 Core/Bazel codegen 问题不属于本 Step 允许范围，未以扩大修改规避。
+
+iPhoneOS arm64 CMake `ios-sdk-static` 编译正在以现有 `build-ios` 进行；最终结果必须在完成报告据实更新。未生成 zip，manifest 为 `NOT_BUILT`。
+
+## 下一步
+
+先由独立允许范围处理 Bazel style-codegen 基线，随后在相同 commit 重跑 XCFramework 并检查 Headers、public ObjC symbol 和 zip SHA-256。通过前不得写 CLOSED/PASS 或进入 STEP-083。