feat: bring up particle renderer on ios metal

docs/30_设计/STEP-081_iOS_Metal_Renderer与真机Smoke入口设计_v1.md

@@ -0,0 +1,43 @@
+# STEP-081 iOS Metal Renderer 与真机 Smoke 入口设计 v1
+
+状态：进行中 / WAITING_RDC_DEVICE_BUILD。本文只记录 Codex 静态实现；未进行 iPhoneOS 编译或真机运行。
+
+## 目标和边界
+
+Metal 路径消费既有 `RasterArraySource` V4 renderer projection、`WeatherColorLayer` 与 `RasterParticleLayer`。没有 iOS Field model、QBIN decoder 分支或公开 iOS SDK API。Smoke 代码仅在 `platform/ios/app/MBXViewController.mm`，RN iOS bridge 仍是明确非目标。
+
+## OpenGL → Metal pass 对照
+
+| `u_pass.x` | OpenGL 既有语义 | Metal `ParticleGpuValidationShader` |
+| --- | --- | --- |
+| `< 0.5` | State A/B update / seed / respawn | 同一 T0/T1 decode、timeMix、VELOCITY/DIRECTION advection 与 fail-closed state write |
+| `< 1.5` | Trail fade | 同一 retention fade；legacy validation marker 保留 |
+| `1.5–3.5` | Composite / FrozenComposite | 同一 trail/particle 色彩、mask、speed-color 和 legacy diagnostic 分支 |
+| `> 3.5` | Trail particle line draw | State read/write displacement line，respawn alpha 抑制跨屏线 |
+| `> 4.5` | WeatherColor | 同一 scalar/vector magnitude、stops/ramp 和 invalid discard |
+
+MSL 使用 `ParticleGpuValidationUBO` 的同字段 vec4/float4x4 布局；声明与 C++ 的 `alignas(16)` 相同，并在 MSL 中静态断言 `31 * 16` 字节。此 Step 未改动 C++ UBO、QBIN V4 contract 或 OpenGL source。
+
+## Metal binding
+
+| 类别 | Metal index | Stable ID |
+| --- | ---: | --- |
+| vertex attribute `short2 a_pos` | attribute 0 | `idParticleGpuValidationPosVertexAttribute` |
+| UBO | buffer `drawableReservedUBOCount` | `idParticleGpuValidationUBO` |
+| previous | texture/sampler 0 | `idParticleGpuValidationPreviousTexture` |
+| mask | texture/sampler 1 | `idParticleGpuValidationMaskTexture` |
+| field T0 | texture/sampler 2 | `idParticleGpuValidationFieldTexture` |
+| field T1 | texture/sampler 3 | `idParticleGpuValidationNextFieldTexture` |
+| state | texture/sampler 4 | `idParticleGpuValidationStateTexture` |
+
+这些 index 来自 Metal `ShaderSource` 的 `attributes`/`textures` 表以及 existing shader IDs，而非 OpenGL location 推测。注册位于 `src/mbgl/mtl/renderer_backend.cpp`，CMake source/include list 位于 `cmake/metal.cmake`。
+
+## Smoke 数据链
+
+Test App Runtime Styling 菜单新增 `Particle / QBIN V4 Smoke (T0)`。点击后可选 T0、midpoint、T1 或 clear/release。它从 app bundle `ParticleSmokeFixtures/T0.qbin`、`T1.qbin` 读取现有 RN Wind Golden fixtures；`platform/ios/app/CMakeLists.txt` 在构建后从唯一 fixture 来源复制，不创建第二种数据格式。
+
+private `MLNMapView` seam 提供 `mbglMap`。Smoke 直接创建 `RasterArraySource`，提交 `fixture.wind` T0/T1、Wind profile contract、ColorBinding 与 VectorComponents ParticleBinding，再添加 `WeatherColorLayer` 与 `RasterParticleLayer`。T0=1789239600000、midpoint=1789241400000、T1=1789243200000，全部通过 source-owned requested forecast time 选择窗口/mix。clear 先移除 layers 后移除 source，允许重复创建。
+
+## 后续边界
+
+下一轮如需 iOS RN，必须另行设计桥接；不得把本 App 的 private Core seam 提升为 SDK 或 NavSea API。iPhoneOS 编译、Metal runtime compilation、资源生命周期和视觉验收均由 RDC/GPT 在真实设备完成。