docs: document breaking news state machine

docs/technical/en/earth-frontend-context.md

@@ -434,9 +434,21 @@ On mobile, compute uses a compact regional overview in the existing drawer. Rows
 
 Normal borders, coastlines, claim lines, highlights and landing points use `earth-surface.js` to share the HD sphere UV-triangle surface. Borders draw after the texture but before landing points. Highlight lines are always transparent-queue objects with depth testing, preventing through-globe display or overpainting markers. Geometry is computed and cached at construction, not reprojected per frame. See the [render-layer specification](earth-render-layer-order.md).
 
-### News ticker edge fading
+### News ticker edge fading and breaking state machine
 
-A separate pseudo-element paints the ticker background and horizontal rules, fading to full transparency outside the text bounds. The shell has no rectangular backdrop filter, box shadow, or text mask. The region label sizes to its content and the scrolling text follows directly without fading. The ticker stays neutral; breaking levels style the expanded news panel as a whole. Selection, focus and close animation do not mutate the breaking data state, which is recomputed from item expiry timestamps.
+A separate pseudo-element paints the ticker background and horizontal rules, fading to full transparency outside the text bounds. The shell has no rectangular backdrop filter, box shadow, or text mask. The region label sizes to its content and the scrolling text follows directly without fading.
+
+The previous breaking rule was global shell promotion: if the payload contained any unexpired breaking story, the highest level (`critical > breaking > watch`) was applied to the ticker or expanded panel. That made a closed panel, or a ticker currently showing a normal story, retain an orange/red state. `breaking_expires_at` eventually cleared the state, while selection, opening and closing did not change the underlying breaking data.
+
+The current state machine keeps data, ticker visibility, panel lifecycle and selection separate:
+
+- `getNewsBreakingState()` derives the data state from `items` and `cruise_items`, ignores expired stories, and ranks `critical > breaking > watch`. The expiry timestamp only schedules the next recomputation.
+- A ticker viewport watcher runs every 120 ms and chooses the item with the greatest viewport overlap, breaking ties by distance to the viewport center. Only when that current item has a non-`none` level does the ticker switch its horizontal rules to `has-breaking-*`; it returns to neutral as soon as the current item is not breaking.
+- The panel lifecycle is `closed → opening → open → closing → closed`. Opening and closing control morphing, visibility and ticker hiding; they do not mutate the breaking data.
+- `selectedCruiseStoryId` is independent of breaking severity. Selection, focus, hover and close only change the selected story and reading position; close also clears the selection and filter popover.
+- The expanded panel always keeps its blue glass surface. Breaking colors remain on the matching story cards, so opening the panel never turns the entire glass panel red; the ticker can still show a red signal when the currently scrolling story is breaking.
+
+Future visual direction (not implemented yet): when the current ticker story enters a breaking state, add a low-frequency, limited-amplitude red/amber warning pulse that reads like a beacon reflected on the glass. The pulse should affect glass highlights and a local translucent layer, not the panel base color or a permanently flashing full border. This visual sub-state must remain attached to the current breaking story and must not be coupled to whether the panel is open.
 
 Compute cards directly reuse the shared `.hud-panel` background, border, shadow, and glass treatment. Summary, essentials, and detail areas add no separate black surface. Their headers share inset spacing with the layer panel through `.hud-panel__header--inset` / `.layer-panel-header`; primary numbers remain prominent and essential information stays visible.
 

docs/technical/zh/earth-frontend-context.md

@@ -567,9 +567,21 @@ Earth 原有 Roboto Condensed 字体已随 `assets/fonts/` 本地分发，许可
 
 普通国界、海岸、主张线、高亮及登陆点使用 `earth-surface.js` 对齐高清球面的 UV 三角形。国界与高亮在贴图之后、登陆点之前绘制，高亮开启深度测试且始终位于透明渲染队列；不再透过球体显示或盖住登陆点。几何构建时计算并缓存，不增加每帧重投影。具体顺序见[渲染图层规范](earth-render-layer-order.md)。
 
-### 新闻栏端部渐变
+### 新闻栏端部渐变与 breaking 状态机
 
-新闻栏的底色与上下细线由独立伪元素绘制，两端在正文范围之外渐变到完全透明；外框不使用矩形 backdrop-filter、box-shadow 或文字遮罩。地区标签按内容占宽，正文紧接标签，滚动文字不做渐隐。ticker 始终保持中性，breaking 等级只作用于展开的新闻面板整体背景/阴影；选中、焦点和关闭动画不改变 breaking 数据状态，过期后由时间戳重新计算并清除面板状态。
+新闻栏的底色与上下细线由独立伪元素绘制，两端在正文范围之外渐变到完全透明；外框不使用矩形 backdrop-filter、box-shadow 或文字遮罩。地区标签按内容占宽，正文紧接标签，滚动文字不做渐隐。
+
+此前的 breaking 规则是：只要本次 payload 中存在未过期的 breaking 新闻，就按 `critical > breaking > watch` 取最高等级，把等级直接映射到新闻壳层。这样会让整条 ticker 或展开面板在当前显示的新闻并非 breaking、甚至面板已经关闭时仍保留橙/红状态，造成“关闭后残留边缘”和“整个面板变色”。`breaking_expires_at` 到期后才清除该状态；选中、打开和关闭不会改变 breaking 数据本身。
+
+当前状态机将数据态、ticker 显示态、面板生命周期和选中态分开：
+
+- 数据态由 `getNewsBreakingState()` 从 `items` 与 `cruise_items` 合并计算，只接受未过期项目，并按 `critical > breaking > watch` 排序；到期时间只负责安排下一次重新计算。
+- ticker 的显示态由滚动视口 watcher 每 120ms 取视口内重叠最多、距离中心最近的当前项目。只有当前项目的 breaking 等级非 `none` 时，ticker 的上下细线才切换为对应的 `has-breaking-*` 颜色；当前项目离开后立即恢复中性。
+- 面板生命周期 `panelPhase` 只有 `closed → opening → open → closing → closed`。打开/关闭只控制形变、可见性和 ticker 的隐藏，不改变 breaking 数据态。
+- `selectedCruiseStoryId` 独立于 breaking 等级。选择、聚焦、悬停和关闭只更新选中项与阅读位置；关闭时清空选中项及筛选弹层。
+- 展开面板始终使用蓝色玻璃底。breaking 只在对应新闻卡片上使用等级颜色，因此点开面板不会把整块玻璃染成红色，之后滚动到 breaking 新闻时仍可让 ticker 显示红色提示。
+
+后续视觉方向（尚未实现）：breaking 不再依赖静态橙色边框，而是在上述 ticker 当前项目进入 breaking 状态时，驱动一层低频、有限幅度的红/橙警灯脉冲；脉冲应像警灯映照在玻璃材质上的反射，作用于玻璃高光和局部透光层，不改变面板底色，也不使用持续闪烁的整圈边缘。该方向属于视觉子状态，必须挂在当前 breaking 项目上，不能重新耦合到面板是否打开。
 
 算力卡片外观直接复用共享 `.hud-panel` 的背景、边框、阴影和玻璃效果，摘要、基础信息及详情区不再叠加单独黑底。标题栏与图层面板共用 `.hud-panel__header--inset` / `.layer-panel-header` 的内边距；主数字继续突出，基础信息保持常显。