路线图
定位
MoonBit 的轻量跨平台桌面 GUI 框架——窗口原生直连、渲染管线自绘、界面组件齐全、系统接口完备。
- 窗口原生直连：窗口宿主与事件循环直连平台原生接口自研，不套平台控件包装；平台差异收敛在窗口、文字、图像解码、WebView、媒体五处 C 薄层
- 渲染管线自绘：布局、光栅化、文字排印、控件与主题全由本库实现，三平台外观一致；深浅色与系统强调色默认跟随
- 界面组件齐全：控件族、图表、Markdown 视图、WebView 与媒体播放开箱可用；功能各自成包，不 import 不进二进制
- 系统接口完备：托盘、通知、全局快捷键、文件对话框、硬件与桌面设置面按平台后端实现；能力探测 + 语义化降级，不支持的环境给
Unsupported而不是崩
现在能拿到什么
| 入口 | 内容 |
|---|---|
| 库 | moon add NoahLiu/native-gui——16 个子包（G9 Batch 2 拆出 base/shell/widget，core 为迁移期门面），另有 gui-media、gui-webview、gui-examples 三个可选独立模块 |
| 示例 | hello 最小窗口、hello-themed 主题控件集、showcase 全功能演示板 |
| 文档 | 中英双语文档站与各包文档，见文档索引 |
| CI | Linux / Windows / macOS 三条 job 每次推送全绿：库包测试、构建、启动冒烟（Linux 虚拟显示、macOS 登录会话） |
平台现状
- Linux 🟩：X11 为主链路；Wayland 会话可运行，依赖 X11 的能力按会话探测降级。兼容跨度 deepin 20 ~ Ubuntu 26，工具包留守 GTK3（理由见「明确不做」）。
- Windows 🟩：能力族已验，CI 覆盖；真机验证矩阵部分待核。
- macOS 🟨：后端已合流 master（CI 三平台全绿回证）；真机目视验证收口中（Retina 观感、输入法内联、拖窗循环、多屏读数、通知授权等），收口前不纳入对外承诺。
Linux 兼容档位
承诺跨度 deepin 20 ~ Ubuntu 26，验证按「库版本 × 桌面环境 × 会话类型」选代表档位，不按发行版数量堆测：
| 档位 | 代表 | 关键变量 | 状态 |
|---|---|---|---|
| 地板 | deepin 20 | GTK 3.24.5、webkit2gtk-4.0、ffmpeg 4.1、glibc 2.28 | 待验证 |
| 主链路 | Ubuntu 24.04 + X11 + XFCE | 开发机与 CI 所在档 | 已验证 |
| 天花板 | Ubuntu 26 | GTK3 是否仍随发行版提供、webkit 4.1+ | 待验证 |
当前待核项：
- 内嵌 WebView：构建只探测 webkit2gtk-4.1，地板档缺该包时 web 退为占位实现；要承诺地板档需加 4.0 回退探测。
- GTK API 地板：窗口桩用到的 GTK 函数与 3.24.5 逐个核对，确认没有更新版本才引入的调用。
- 媒体线：地板档 ffmpeg 开发包与运行期 so 的版本兼容。
- 命令线能力：音量、夜灯、显示器、空闲所依赖的系统工具在地板档是否默认安装；未装即语义化降级，写进清单而不是当缺陷。
- 工具链：最新 moon 工具链在 glibc 2.28 上的可运行性，是地板档构建的第一道闸。
验证方式：构建与无头判据在 VM / 容器上跑，能不进 GUI 的都不进；需要人眼的项进人工清单。
会话轴（X11 / Wayland）
只有下表四项随会话类型变，其余能力由 GTK3 抽象掉、两会话同值。Wayland 档的口径一律是探测到会话即语义化降级。
| 功能点 | X11 | Wayland | Wayland 侧出路 |
|---|---|---|---|
| 全局快捷键 | ✅ | 无对应面 | 需走 portal / 桌面守护协议 |
| 空闲检测 | ✅ | ❌ | 只能退「有焦点才计时」的近似档 |
| 窗口控制、剪贴板监视 | ✅ | ❌ | 剪贴板读写仍可用，只有监视不行 |
| 显示器与夜灯 | ✅ | ❌ | 可改走 D-Bus / portal 的夜灯服务 |
桌面环境轴（XFCE / KDE / GNOME / DDE）
与发行版无关，且本仓只有 XFCE 一档有实测记录——下表 ？ 就是待核清单，不是「已知能用」。判据按能力线各自立：托盘与通知要真实面板回证，取色要读到非默认值。
| 功能点 | XFCE | KDE | GNOME | deepin / DDE |
|---|---|---|---|---|
| 系统托盘 | ✅ | ？ | ？ | ？ |
| 通知 | ✅ | ？ | ？ | ？ |
| 深浅色与强调色读取 | ✅ | ？ | ？ | ？ |
| 壁纸读写 | ✅ | ？ | ？ | ？ |
| 默认应用 / 应用枚举 | ✅ | ？ | ？ | ？ |
| 文件管理器「打开并选中」 | ⏳ | ？ | ？ | ？ |
未测档的已知缺口：GNOME 默认无 SNI watcher，需装扩展；KDE 的取色路径未接；壁纸与默认应用在 KDE / GNOME / DDE 有代码分支但未实测；「打开并选中」未接 FileManager1，现恒落「打开父目录」。
功能面全景
状态只回答「这个功能点在某平台上成不成」；接口形态与验收细节在 adaptation.md 和各包文档，排期在 TODO.md。
- ✅ 有实现，且有逐项回证
- 🚧 有实现，但回证未到逐项级，或分支尚未合流 master
- ❌ 未接，门面给
Unsupported - — 该平台无对应面
- ？ 查过仍无定论，列在下方便待核清单
Linux 列带 X11 的格只在 X11 会话成立，带 DE 的格行为随桌面环境换配置源或依赖 host 服务；逐条见上方两张轴表。
交付面与工程化
| 功能点 | Windows | Linux | macOS |
|---|---|---|---|
| 示例 | ✅ | ✅ | 🚧 |
| CI 分层门禁 | ✅ | ✅ | ✅ |
| mooncakes 发布 | ✅ | ✅ | ✅ |
gui-media / gui-examples 发布 | ❌ | ❌ | |
| 文档站 | ✅ | ✅ | ✅ |
| 真机验证矩阵 | 部分 | 部分 | 🚧 |
| 性能治理 | 🚧 | ✅ | ？ |
| 无障碍 | ❌ | ❌ | ❌ |
待核清单（查过代码与适配文档仍无定论，不当已验凑数）
- 浮层的原生档 · Windows：交付与回证目前全在 Linux，Windows 侧有无对应的 popup / transient 通道需读桩确认后定档。
- 播放器组件族 · Windows：视频、音频、字幕、歌词、频谱、倍速只到「可编译可运行、音频后端有探针」级。
地基与宿主
| 功能点 | Windows | Linux | macOS |
|---|---|---|---|
| 窗口地基与事件循环 | ✅ | ✅ | 🚧 |
| 软件光栅与 Cairo 后端 | ✅ | ✅ | 🚧 |
| 文字排印 | ✅ | ✅ | 🚧 |
| 图像解码 | ✅ | ✅ | 🚧 |
| 布局 | ✅ | ✅ | 🚧 |
| 焦点栈、键鼠接入与编辑内核 | ✅ | ✅ | 🚧 |
| 平台输入映射层 | ✅ | ✅ | 🚧 |
| 输入法通道 | ✅ | ✅ | 🚧 |
| 应用宿主与多窗口 | ✅ | ✅ | 🚧 |
| 多窗口公开 API（open_window/close_window/window_count/active_window/wid/is_primary） | ✅ | ✅ | 🚧 |
| 窗口隐藏驻留（hide/show 唤回原位） | ✅ | ✅ | 🚧 |
| 窗口透明（set_opacity 0–255） | 🚧 | ✅ | ❌ |
| 窗口背景穿透（set_transparent_bg） | 🚧 | ✅ | ❌ |
| 窗口层级嵌入（Normal/Desktop/AlwaysOnTop/Dock） | 🚧 | ✅ | ❌ |
| 自绘控件宿主 | ✅ | ✅ | 🚧 |
| 声明式层 | ✅ | ✅ | 🚧 |
| 样式层 | ✅ | ✅ | 🚧 |
| 命名样式类（StyleClass 注册表 + 主题变体） | ✅ | ✅ | ✅ |
| 主题系统与跟随系统明暗 / 强调色 | ✅ | ✅ | 🚧 |
| 窗口级按键兜底通道 | ✅ | ✅ | 🚧 |
按键抬起投递（on_key_release 声明制；on_key/兜底通道永不收抬起） | ✅ | ✅ | ✅ |
| 输入法焦点门（焦点控件绑定；fcitx5 两层回证——filter 门 + focus_in/out 同步） | 🚧 | ✅ | 🚧 |
| 组合键解析与 bind_combo 便捷口 | ✅ | ✅ | ✅ |
| 通用双击/三击检测（ClickTracker 挂 Widget） | ✅ | ✅ | ✅ |
| 上屏帧缓冲所有权 | 🚧 | ✅ | ❌ |
| 模块拆分 | ✅ | ✅ | ✅ |
| 窗口内按键路由补齐 | ⏳ | ⏳ |
绘图与资源
| 功能点 | Windows | Linux | macOS |
|---|---|---|---|
| 路径、曲线、变换、裁剪与渐变 | ✅ | ✅ | 🚧 |
Painter.draw_path(Path) 对象直通 | ✅ | ✅ | 🚧 |
Painter.set_line_cap / set_line_join（LineCap/LineJoin 枚举） | ✅ | ✅ | 🚧 |
Painter.set_dashes（数组 marshalling） | ❌ | ❌ | ❌ |
Color::rgb/rgba 构造 + to_hex 序列化 + color_white 常量 | ✅ | ✅ | ✅ |
@widget 门面 re-export 绘图类型（Painter/Color/Bitmap/Gradient/Canvas/Image/Animation） | ✅ | ✅ | ✅ |
| 位图、画布与图像编解码 | ✅ | ✅ | 🚧 |
GIF 动画与 gif 组件 | ✅ | ✅ | ？ |
| 矢量图标 | ✅ | ✅ | 🚧 |
| 富文本、字体枚举与回退 | ✅ | ✅ | ❌ |
组件层与前端化
| 功能点 | Windows | Linux | macOS |
|---|---|---|---|
| 组件命名对齐 Web | ✅ | ✅ | ✅ |
| 样式通道逐组件收口 | ✅ | ✅ | ✅ |
| 展示类信号版组件 | ✅ | ✅ | ✅ |
| CSS 文本与盒模型属性生效面 | ✅ | ✅ | ✅ |
letter_spacing 生效 | ❌ | ❌ | ❌ |
| 响应式补强 | ✅ | ✅ | ✅ |
| 过渡动画 | ✅ | ✅ | 🚧 |
| 全局 alpha 与硬阴影 | ✅ | ✅ | 🚧 |
按钮图标位（button(icon?=…, icon_size?=…)，测量让位 lead_w） | ✅ | ✅ | ✅ |
| chip class 字号参与测量宽（P2-e 收口） | ✅ | ✅ | ✅ |
控件与组件清单
| 家族 | Windows | Linux | macOS |
|---|---|---|---|
| 基础原语 | ✅ | ✅ | 🚧 |
| 文本族 | ✅ | ✅ | 🚧 |
| 表单族 | ✅ | ✅ | 🚧 |
| 输入框全语义 | ✅ | ✅ | ❌ |
| 显示族 | ✅ | ✅ | 🚧 |
| 日期与时间族 | ✅ | ✅ | 🚧 |
| 导航族 | ✅ | ✅ | 🚧 |
| 表格与虚拟列表 | ✅ | ✅ | 🚧 |
| 浮层族 | ✅ | ✅ | 🚧 |
| 容器与滚动、分栏 | ✅ | ✅ | 🚧 |
| 拖放 | ✅ | ✅ | 🚧 |
图表与文档视图
| 功能点 | Windows | Linux | macOS |
|---|---|---|---|
| 共享算法层 | ✅ | ✅ | 🚧 |
| 通用图表 | ✅ | ✅ | 🚧 |
| 交互层与 tooltip、PNG 导出 | ✅ | ✅ | 🚧 |
| 专项图表与地图 | ✅ | ✅ | 🚧 |
| Markdown 视图 | ✅ | ✅ | 🚧 |
| 代码高亮 / 终端 / WebGL 画布 | ❌ | ❌ | ❌ |
系统集成
| 功能点 | Windows | Linux | macOS |
|---|---|---|---|
| JSON、环境与文件原语、子进程 | ✅ | ✅ | ✅ |
| 文件对话框 | ✅ | ✅ | 🚧 |
| 打开与定位 | ✅ | ✅ | 🚧 |
| 应用枚举与最近文件 | 🚧 | ✅ | 🚧 |
| 壁纸与默认应用 | ❌ | ✅ DE | ❌ |
| 单实例 | ❌ | ✅ | ❌ |
| 桌面环境识别 | — | ✅ DE | — |
| 硬件族 | — | ✅ X11 | — |
| 浏览器与编辑器历史 | ✅ | ✅ | ✅ |
| 系统信息 | 🚧 | ✅ | 🚧 |
| 窗口控制、剪贴板监视 | — | ✅ X11 | — |
| 空闲检测 | ✅ | ✅ X11 | ❌ |
| 开机自启 | ✅ | ✅ | 🚧 |
| 通知 | ✅ | ✅ DE | 🚧 |
| 系统托盘 | ✅ | ✅ DE | 🚧 |
| 全局快捷键 | ✅ | ✅ X11 | 🚧 |
| 全局快捷键媒体键（MediaPlay/Prev/Next/Mute；mac 无 Carbon 键位，注册诚实失败） | 🚧 | 🚧 | ❌ |
| 原生消息框与自绘档 | ✅ | ✅ | 🚧 |
| 原生菜单栏 | ✅ | ✅ | 🚧 |
| 任务栏进度 | ✅ | — | — |
| D-Bus 能力模块 | — | ✅ | — |
| Wayland 会话分流 | — | ✅ | — |
| 传感器 / 蓝牙 / 磁盘 | — | ✅ | — |
webview 与原生子表面
| 功能点 | Windows | Linux | macOS |
|---|---|---|---|
| 多窗口宿主与 pane 模型 | ✅ | ✅ | 🚧 |
| 内嵌 WebView | ✅ | ✅ | 🚧 |
| JS 通道、DOM 抓取与导航事件 | ✅ | ✅ | 🚧 |
| 本地内容通道 | ✅ | ✅ | 🚧 |
| 引擎开关与策略面 | ✅ | ✅ | 🚧 |
| 浮层的原生档 | ？ | ✅ | 🚧 |
| 原生弹层 Esc 收起（弹层窗自持按键兜底通道，关窗挪出派发现场） | 🚧 | 🚧 | 🚧 |
cookie 共享与隔离（引擎默认共享；隔离走 pane 级 profile，库层不做同步——2026-10-18 定案＝浏览器默认策略） | ✅ | ✅ | 🚧 |
| 浮层「点外收起」判据 | ⏳ | ⏳ | ⏳ |
媒体播放
| 功能点 | Windows | Linux | macOS |
|---|---|---|---|
| 解码引擎 | ✅ | ✅ | 🚧 |
| 音频输出 | ✅ | ✅ | 🚧 |
| 播放器组件 | 🚧 | ✅ | 🚧 |
| 无头播放接口（HeadlessAudio/HeadlessVideo，注入 schedule 通道自 pump） | ✅ | ✅ | ✅ |
| 无头视频帧取回（current_frame → Bytes） | ✅ | ✅ | ✅ |
| 字幕层 | 🚧 | ✅ | 🚧 |
| 歌词层（audio/video 同源；非 UTF-8 见替换符整篇按空歌词） | 🚧 | ✅ | 🚧 |
实时频谱（audio 舞台 + video spectrum?，引擎 pcm_tap 旁路） | 🚧 | ✅ | 🚧 |
| 倍速、逐帧、缩放与播放/跳转快捷键 | 🚧 | ✅ | 🚧 |
静音与循环（控制条键 + M/L 快捷键，状态机 bar_mute_toggle/bar_vol_apply） | 🚧 | ✅ | 🚧 |
全屏观感三件（双击切换 / 2.5s 收条藏指针 CURSOR_HIDDEN / 活动即恢复） | 🚧 | 🚧 | 🚧 |
播放器换载回收（Widget.on_discard 控件级丢弃回调，free 引擎 + 停时钟链） | ✅ | ✅ | ✅ |
| 硬解与 GPU 合成 | ❌ | ❌ | ❌ |
GPU 合成与 3D 路径
| 功能点 | Windows | Linux | macOS |
|---|---|---|---|
| 软件 Painter（CPU 光栅 / Cairo） | ✅ | ✅ | ❌ |
Widget.on_render(Widget, RenderCtx, Rect) 协议口子 | ✅ | ✅ | ✅ |
@render.RenderCtx 枚举（当前 Cpu(Painter)，Gpu(GpuContext) 变体预留） | ✅ | ✅ | ✅ |
@render.gpu_backend_available() 探测（现恒 false） | ✅ | ✅ | ✅ |
| GPU 合成器（present 走纹理上传 + quad） | ❌ | ❌ | ❌ |
| 控件级 GPU 绘制（shader / vertex buffer） | ❌ | ❌ | ❌ |
| WebGPU 后端（wgpu-native 可选模块） | ❌ | ❌ | ❌ |
架构定案（2026-10-17）：WebGPU 作可选后端，两层落地（合成器 + 控件级 GPU 绘制），三级 fallback（WebGPU → Cairo → Pure）。渲染路径分派的口子（RenderCtx / Widget.on_render）已在协议层留好，未来 GPU 后端上线只扩枚举变体、不改 Widget 契约。选型依据、落地路径、平台兼容档口与设计决策全文见 gpu-architecture.md。
承诺与版本
- 当前版本
0.1.1：0.x 阶段接口随批次演进，破坏性改动在提交信息写明并同步文档。 - 稳定面清单与 1.0 时点待定：落定后本节按「承诺面 / 实验面」逐包列出。
接下来的方向
- 上手门槛：首页给「装 moon →
moon add→ 出窗口」的最短路径；每平台前置依赖一句话说清；缺依赖时构建报错自带修复提示。 - 可信度：CI 门禁 + 真机人工清单 + 版本承诺，能力族验收一律走这三件套。
- 内容：文档站、组件文档、教程与 showcase 持续补齐；组件文档配图，教程给可运行的最小工程。
- 治理：issue 模板与贡献指南随对外投放建立；本文与平台矩阵随每批更新，不积压。
- GPU 合成与 3D 路径：WebGPU 作可选后端（独立模块，不进主链路），两层落地、三级 fallback；
Widget.on_render(RenderCtx)协议口子已就位，后端上线只扩枚举变体。决策全文见 gpu-architecture.md。
待定决策
- macOS 纳入对外承诺的时点：前置是真机验证收口。
- 稳定面清单与 1.0 时点：逐包划分承诺面 / 实验面后，本文与各包文档同步。
明确不做
- 无障碍：自绘文本栈暂不含，只记不办。
- 单平台能力进跨平台门面：只有单一平台实现的能力不做门面，也不留挂账。
- Linux 工具包升级：留守 GTK3，它是 deepin 20 到 Ubuntu 26 的公共交集；不引入 Qt。脱 GTK 的唯一形态是降为可选后端。
- 原生控件皮肤：不作主题化路径；按平台开关的原生兜底例外需逐条登记评审。
- 按参考实现平移接口：接口由真实用例驱动，不为对齐而补。