原生 UI¶
职责¶
原生 UI 层协调 screen region stack、resize/redraw 失效、curses 兼容 window、SDL/tile
渲染、list、popup 与较新的 ImGui surface；ui_adaptor 是核心生命周期和重绘边界。
入口点¶
从 src/ui_manager.h / .cpp 开始，再看 ui_helpers、uilist 与具体 screen。注册
on_screen_resize、on_redraw，声明 adaptor 区域，并通过 input_context 驱动。
数据所有权¶
栈上的 ui_adaptor 通过 RAII 拥有 callback 与 UI stack 成员资格。screen function
拥有 window/view model；renderer backend 拥有 texture/buffer；全局 uistate 只保存
明确需要持久化的显示选择。
依赖¶
UI 依赖 input context、translation、color/font/terminal metric、renderer backend、游戏 view model、Android UI mode 与可选 Lua UI/ImGui 集成。
生命周期¶
构造 adaptor 时入栈；resize 建立 geometry；redraw 只绘制声明区域；input 可能触发更多 resize/redraw；析构时出栈。callback 不能在 redraw 中改变 adaptor stack。
不变量¶
声明 geometry 包含全部绘制；callback 遵守 manager 的重入规则；顶层 UI 获得 input focus；除非显式 absolute pixel API，window 尺寸使用 cell；resize 先失效布局再绘制。
扩展点¶
原生 screen 使用局部 adaptor 与 input context，可复用布局进入 helper。向 Lua 暴露数据 只能通过有边界公共 API，不能泄露 native UI pointer。
序列化¶
adaptor、window、callback 与 renderer resource 都是临时的。只持久化明确用户配置或
uistate 字段，提供默认和测试；读取后重建布局。
测试¶
使用 UI profile 与具体 screen 测试，并按需覆盖 resize、窄 terminal、keyboard、 tiles/curses、Android touch 与 Lua-disabled 路径。
性能¶
redraw 调用频繁。限制失效区域，不要在 paint callback 重建昂贵 view model，并防止 透明 ImGui layer 在 SDL buffer 留下旧像素。
CCB 差异¶
CCB 把旧原生 screen 与项目专属 Lua UI、ImGui、Android HUD 路径结合。上游 UI 移植 必须保持所有启用 backend 与 input-mode 边界。
技术债务¶
cell、pixel、curses、SDL、ImGui 与 Android 抽象并存。新 screen 应显式管理 geometry， 不要再引入全局 redraw 或 input shortcut。