# Earth Surface Hover Info Plan

Status: Implemented.

## Goal

为 Earth 桌面和 compact 鼠标地表 hover 增加可配置的提示内容，让用户可以选择只看国家信息、只看位置数据，或同时查看国家和经纬海拔。

当前地表 hover 已经具备两类信息：

- 命中国家时显示国家、ISO、大洲，并高亮国界。
- 未命中国家时显示纬度、经度、海拔。

新方案把这两类信息合并成一个清晰的设置项：`悬停提示`。

## User-facing behavior

设置项放在桌面设置和移动端设置的 `视图` 区，使用分段控件：

- `国家`：陆地命中国家时显示国家名、ISO、大洲；太平洋等海洋区域不显示地表 tooltip。
- `位置`：陆地和海洋都显示纬度、经度、海拔；不触发国家 tooltip 和国家边界 hover 高亮。
- `完整`：陆地命中国家时显示国家信息和纬度、经度、海拔；海洋区域显示纬度、经度、海拔。

默认值为 `完整`，因为它保留现有国家识别价值，同时满足 hover 时查看经纬海拔的需求。

海洋在 `国家` 模式下保持沉默，而不是显示大洋名称。原因是当前项目没有海域/大洋边界数据源；用经纬度粗判太平洋、大西洋等范围容易产生误导。如果用户需要海洋位置，使用 `位置` 或 `完整`。

## Implementation plan

### Settings state

在 `frontend/public/earth/js/constants.js` 增加：

```js
export const SURFACE_HOVER_INFO_MODES = {
  COUNTRY: "country",
  POSITION: "position",
  FULL: "full",
};

export const DEFAULT_SURFACE_HOVER_INFO_MODE =
  SURFACE_HOVER_INFO_MODES.FULL;
```

在 `frontend/public/earth/js/controls.js`：

- 将 `EARTH_SETTINGS_VERSION` 从 `10` 升到 `11`。
- 在 shared settings 中新增 `surfaceHoverInfoMode`。
- 新增导出：
  - `getSurfaceHoverInfoMode()`
  - `setSurfaceHoverInfoMode(mode, { persist, suppressStatus })`
- normalize 时只接受 `country | position | full`，否则回退到 `full`。
- reset settings 后恢复为 `full`。

### Settings UI

在桌面设置 `视图` 区和移动端设置 `视图` 区加入同一组按钮：

```html
<button data-surface-hover-info-mode="country">国家</button>
<button data-surface-hover-info-mode="position">位置</button>
<button data-surface-hover-info-mode="full">完整</button>
```

控件同步规则沿用现有卫星显示风格和巡航模块的模式：

- 当前模式按钮添加 `is-active`。
- 当前模式按钮设置 `aria-pressed="true"`。
- 切换后保存到 Earth settings localStorage。

### Hover tooltip logic

在 `frontend/public/earth/js/main.js` 的地表 hover 分支中读取 `getSurfaceHoverInfoMode()`，统一构造 tooltip。

行为规则：

- 如果没有命中地球：清除国家 hover 并隐藏 tooltip。
- `position`：
  - 调用 `clearCountryBoundaryHover()`。
  - 显示 `纬度 / 经度 / 海拔`。
- `country`：
  - 仅当国界图层开启并命中国家时显示国家 tooltip 和国界 hover。
  - 海洋、国界图层关闭、未加载国界数据时隐藏地表 tooltip。
- `full`：
  - 国界图层开启且命中国家时显示国家信息加位置信息。
  - 未命中国家或国界图层关闭时显示位置信息。

海拔继续使用 `sampleElevationAt(lat, lon)`。暂无采样时显示 `—`，不因 hover 主动加载地形瓦片。

## Acceptance criteria

1. `完整` 模式下，hover 陆地显示国家信息和经纬海拔，hover 海洋显示经纬海拔。
2. `国家` 模式下，hover 陆地显示国家信息，hover 太平洋等海洋不显示地表 tooltip。
3. `位置` 模式下，hover 陆地和海洋都显示经纬海拔，国家边界不高亮。
4. 关闭国界图层后，`完整` 模式回退为只显示位置。
5. 船只、BGP、算力中心、海缆等对象 hover tooltip 优先级不变。
6. 移动端中心国家高亮不受这个鼠标 hover 设置影响。
7. 设置刷新后保持，重置后恢复为 `完整`。

## Verification

- 在 `frontend` 下运行 `/home/ray/.bun/bin/bun run build`。
- 手动验证三种模式的陆地和海洋 hover 行为。
- 验证设置持久化和重置。
- 验证对象 hover 仍优先于地表 hover。