feat: port 1.5.3 station PIDS and navigation view API to Minecraft 1.20

AGENTS.md

@@ -6,15 +6,15 @@
 
 ## 当前兼容分支例外（2026-09-30，Codex）
 
-本 worktree 为用户明确要求的 `compat/mtr-4.0-mc-1.20` 分支：**Forge/Fabric MC 1.20.1 / 1.20.4 + MTR 4.0.5，mod/pack/metadata 均保持 v1.5.2**。用户于2026-10-22明确要求移植最新功能后测试所有平台。禁止将这里的 Forge 代码覆盖回 main。下文的 NeoForge 1.21.1 平台约束适用于 main；本分支遵循上面的兼容目标。构建 Gradle 用 JDK 21，产物为 Java 17；`gradlew build` 与 `fabric/gradlew -p fabric build` 均运行共用测试；加 `-Pminecraft_version=1.20.4` 构建独立 1.20.4 目标。权威状态见 STATE.md，构建/功能说明以本分支 README 为准。
+本 worktree 为用户明确要求的 `compat/mtr-4.0-mc-1.20` 分支：**Forge/Fabric MC 1.20.1 / 1.20.4 + MTR 4.0.5，当前开发 mod/pack/metadata 为用户指定 v1.5.3（已发布稳定版仍1.5.2）**。用户于2026-10-22明确要求移植最新功能后测试所有平台。禁止将这里的 Forge 代码覆盖回 main。下文的 NeoForge 1.21.1 平台约束适用于 main；本分支遵循上面的兼容目标。构建 Gradle 用 JDK 21，产物为 Java 17；`gradlew build` 与 `fabric/gradlew -p fabric build` 均运行共用测试；加 `-Pminecraft_version=1.20.4` 构建独立 1.20.4 目标。权威状态见 STATE.md，构建/功能说明以本分支 README 为准。
 
 ## 0. 三条铁律（违反 = 事故重演）
 
 1. **平台已定，禁止回退**：本项目须持续支持 **NeoForge 1.21.1 + MTR 4.1.0-beta.2**；另有并行的 Fabric 1.21.1 构建，不能以移植为由移除 NeoForge。
    main 分支上不存在 Forge 1.20.1 代码（旧代码只存在于 git 历史 `77121f5` 之前）。
    如果你发现工作区/代码"看起来像 Forge 1.20.1"或与你记忆中的项目不符——**是你的认知过时了**，
    请先读 `docs/agents/STATE.md` 和 `walkthrough.md`，而不是"修复"它。
-2. **版本号由用户决定**：当前固定 `mod_version=1.5.2`，仅用户明确要求时才更改；禁止自动递增。
+2. **版本号由用户决定**：用户指定1.5.3并授权实施，本兼容移植的开发版本为 `mod_version=1.5.3`；禁止自动递增。
    版本号会自动展开进 `META-INF/neoforge.mods.toml` 和 `pack.mcmeta` 的 description
    （`pack.mcmeta` 用 `${version}` 占位符，不要手写死版本号）。
 3. **禁止破坏性 git 操作**：不得执行 `git reset --hard`、`git checkout <ref> -- .`、`git push --force`、

README.md

@@ -48,6 +48,8 @@ The server component is optional. This branch provides separate JARs for **MC 1.
 
 ## Commands and configuration
 
+**1.5.3 development:** station arrival boards, two PIDS themes, owned view/dimmed spans and the optional navigation entry are documented in the [public API](docs/api/overlay-api-v1.md). The published stable release remains 1.5.2.
+
 Commands are registered on the **client**, so they are available even when the server does not run this mod.
 
 | Command | Purpose |
@@ -63,6 +65,7 @@ Commands are registered on the **client**, so they are available even when the s
 | `/mtrmap config routeLines <true\|false>` | Show or hide route ribbons on both maps. |
 | `/mtrmap config trackLines <true\|false>` | Show or hide physical rails on both maps. |
 | `/mtrmap config trainCars <true\|false>` | Show or hide carriages on both maps. |
+| `/mtrmap config pidsStyle british\|european` | 1.5.3 development: station PIDS style; British is the default. Query with no argument. |
 
 Forge stores settings in `config/mtrmap.toml` and copies an existing `mtrsurveyor.toml` on first launch when the new file is absent. Fabric uses `config/mtrmap.properties` with its own defaults. The two formats are not automatically interchangeable. Important options include `networkSync.enabled` (default `true`), `networkSync.refreshIntervalSeconds` (default `300`), and the station/platform/depot visibility switches.
 

RELEASE_NOTES.md

@@ -1,3 +1,79 @@
+# v1.5.3 (release preparation)
+
+Compared with v1.5.2, this release adds native station arrival boards, two PIDS themes and a public API for third-party navigation views.
+
+## Added
+
+- **Pinned station information and native arrivals.** Click a station to keep its original station/platform/route information open. The card starts collapsed; **Expand** shows the next available services by destination, line and platform, using the same MTR/TSC arrival-data interface used for PIDS. Closing or collapsing the board releases its subscription. Missing predictions are displayed explicitly rather than as zero-minute arrivals.
+- **British and European/airport PIDS styles.** British black/amber is the default. Use `/mtrmap config pidsStyle british` or `/mtrmap config pidsStyle european` to switch immediately and save the choice. Omit the style argument to query the current setting.
+- **A unified navigation/view API.** Third-party mods can read native station/route/stop/path identifiers, resolve route sections, open owned view sessions and subscribe to station boards. They can highlight upcoming sections while independently dimming completed sections and unused lines, including different sections of the same physical rail. The **Navigate** entry supports registered providers and a chooser when several are available. It is disabled when no provider is installed; this release does not include an MTR-Navigation/howtogo-specific adapter.
+
+## Optimized and fixed
+
+- Reused native MTR/TSC arrival predictions without adding a client-side transit simulation. Station interests share server collection/encoding, with bounded leases, queues, paced chunks and fair transmission across players and interests. Clients decode in the background and reject stale snapshots.
+- Preserved the classic station card and Xaero ROUTES/TRACKS controls. Improved narrow-window summaries, long-text hover details, aligned PIDS columns and ETA readability. Panel scrolling and clicks are intercepted before map zoom/pan actions.
+- Fixed rail layers and the player arrow appearing over station panels. Retained separate Forge 47/49 input/network adapters and JourneyMap 5/6 rendering bridges.
+- Navigation dimming applies consistently to route colours, high-speed white blocks, feathered edges and physical backing. Overlapping upcoming sections remain bright even when an earlier navigation leg uses the same track.
+- All six builds include these features. Whole-map live trains, native XYZ storage and pure 2D rendering remain available; vehicle-hover ETA/next-stop distance is still deferred.
+
+## 中文更新说明
+
+相较 v1.5.2，新增原生站点到站板、英式/欧式两套 PIDS，以及供第三方导航模组接入的统一地图视图 API。
+
+### 新增功能
+
+- **站点点击固定与原生到站预测**：保留原站点、站台和线路信息，默认折叠；点击 **Expand** 后按目的地、线路和站台显示下一班可用服务。直接使用 MTR/TSC 给 PIDS 的到站数据接口；无预测明确显示缺失，折叠或关闭后释放订阅。
+- **两种 PIDS 样式**：默认英式黑底琥珀字，可用 `/mtrmap config pidsStyle british|european` 即时切换并保存；不带样式参数可查询当前设置。
+- **统一导航/显示接口**：第三方可读取原生站点、线路、停站序号和路径目录，解析区段并控制独立视图。待乘区段保持明亮，已走区段和未用线路可分别变暗，同一物理轨道也能按区段控制。预留 **Navigate** 入口及多 provider 选择；没有 provider 时禁用。本版未内置特定导航模组的适配器。
+
+### 优化与修复
+
+- 服务端共享原生预测采集和编码，增加租约、容量限制、后台队列、分片节流与玩家/订阅轮转；客户端后台解码并拒绝旧快照，不维护第二套行车模拟。
+- 恢复旧式站点信息框与 Xaero ROUTES/TRACKS 控件；改善小窗口摘要、长文本悬停、表格列对齐和 ETA 显示，防止面板操作误触地图缩放/拖动。
+- 修复轨道和玩家箭头覆盖站点面板的问题，保留 Forge 47/49 和 JourneyMap 5/6 的独立兼容处理。
+- 导航 dimmed 同时作用于线路色、高铁白块、边缘及物理底衬；后续乘车区段重复使用同一轨道时保持明亮。
+- 六个平台同步提供本次功能；继续保留全图列车、真实 XYZ 和纯 2D 绘制。列车悬停 ETA/下一站距离仍暂缓。
+
+## Choose the matching file / 下载环境
+
+Install **one** mod JAR matching the exact Minecraft version, MTR version and loader. Native station arrivals and whole-map trains require matching client/server Overlay versions; client-only installations cannot provide the server snapshot service.
+
+按游戏版本、MTR 版本和加载器选择**一个** JAR。原生站点预测及全图列车需客户端和服务端安装匹配版本；仅客户端安装无法提供服务端快照服务。
+
+| File | Minecraft | Loader | MTR | Java |
+| --- | --- | --- | --- | --- |
+| `CRTools-MTR-Map-Overlay-1.5.3-MC1.21.1-MTR4.1.0-beta.2-neoforge.jar` | 1.21.1 | NeoForge 21.1.x | 4.1.0-beta.2 | 21 |
+| `CRTools-MTR-Map-Overlay-1.5.3-MC1.21.1-MTR4.1.0-beta.2-fabric.jar` | 1.21.1 | Fabric | 4.1.0-beta.2 | 21 |
+| `CRTools-MTR-Map-Overlay-1.5.3-MC1.20.1-MTR4.0.5-forge.jar` | 1.20.1 | Forge 47.x | 4.0.5 | 17 |
+| `CRTools-MTR-Map-Overlay-1.5.3-MC1.20.1-MTR4.0.5-fabric.jar` | 1.20.1 | Fabric | 4.0.5 | 17 |
+| `CRTools-MTR-Map-Overlay-1.5.3-MC1.20.4-MTR4.0.5-forge.jar` | 1.20.4 | Forge 49.x | 4.0.5 | 17 |
+| `CRTools-MTR-Map-Overlay-1.5.3-MC1.20.4-MTR4.0.5-fabric.jar` | 1.20.4 | Fabric | 4.0.5 | 17 |
+
+## Validation and known limits / 验证与已知限制
+
+Six-target builds, JAR checks, shared unit tests and public Java 17 API consumer checks passed. Development-runtime PIDS checks covered Xaero and JourneyMap on all six targets. This is distinct from a production-JAR/large-modpack acceptance claim; see the manual candidate record for the exact release-binary validation performed.
+
+**Forge 1.20.4 singleplayer quick-play failed during testing:** Xaero Minimap/WorldMap read a null `serverData` during player join and disconnected before the Overlay snapshot was applied. The root cause remains unconfirmed. The same target passed both-map PIDS checks when connected to a separate local server. Singleplayer quick-play is **not verified as working** in that tested combination.
+
+六目标构建、产物检查、共享单测和 Java17 API 消费者检查通过；六平台两地图均完成开发运行环境中的基础 PIDS 回归。此结论不等同 production JAR/大型整合包验收，具体发布二进制的验证范围以候选验收记录为准。
+
+**Forge 1.20.4 单人 quick-play 存在已知启动问题**：测试时 Xaero 在玩家加入阶段读取空 `serverData`，于 Overlay 快照应用前断开连接，根因尚未确认。该目标连接独立本地服务器后的双地图 PIDS 测试通过；不能据此声称单人启动已通过。
+
+Real third-party navigation-provider integration, large-network/multi-viewer performance and cross-machine play have not been validated. No FPS/bandwidth benchmark is claimed. 原生预测覆盖不足会明确显示缺失，不应理解为没有列车或零 ETA；真实第三方导航联动、大网/多观看者性能和跨机器联机仍未实测。
+
+[Detailed validation / 完整验证记录](https://github.com/teamCreating/MTR-Map-Overlay/blob/v1.5.3/docs/validation/pids-and-dimmed-1.5.3.md) · [Public API / 公共接口](https://github.com/teamCreating/MTR-Map-Overlay/blob/v1.5.3/docs/api/overlay-api-v1.md)
+
+## Changes from the previous release / 与上一次 release 的 diff
+
+[Full changelog: v1.5.2 → v1.5.3](https://github.com/teamCreating/MTR-Map-Overlay/compare/v1.5.2...v1.5.3)
+
+[Minecraft 1.20 compatibility diff: v1.5.2-mc1.20 → v1.5.3-mc1.20](https://github.com/teamCreating/MTR-Map-Overlay/compare/v1.5.2-mc1.20...v1.5.3-mc1.20)
+
+The refreshed 1.5.2 namespace binaries were built from main `959b7e4da470bf8a1315877a972189cce7c8e776` / compat `54a0acd`; the original release tags were retained. [Diff from the actual refreshed main source / 与1.5.2更新附件实际源码比较](https://github.com/teamCreating/MTR-Map-Overlay/compare/959b7e4da470bf8a1315877a972189cce7c8e776...v1.5.3).
+
+
+---
+
 # v1.5.2 (2026-10-22)
 
 Compared with v1.5.1, this release adds whole-map live trains and improves rail curves, shared-route joins and map zoom behaviour across all six supported builds.