# Ferese 原生 Rime 原型

本地分支：`twilight/rime-service-poc`。基线为 Ferese `v0.1.0`，提交
`f21167e1a22d527460e20a0eb3184790ee9754df`。这是本设备上的架构验证，尚未作为日常桌面版本发布。

## 进程与协议

```mermaid
flowchart LR
    A[原生 Wayland 应用] <-->|text-input-v3| B[Ferese 合成器]
    B <-->|input-method-v2 / virtual-keyboard-v1| C[独立 Rust Rime 服务]
    C <--> D[librime 与独立测试词库]
    B -->|主题 IPC| C
    C -->|原生 input-popup SHM 缓冲区| B
```

`ferese-rime` 是独立进程。它直接调用系统 librime，通过原生 Wayland 协议接收按键、
提交文字和预编辑状态，并用 Rust 光栅化候选内容。候选颜色订阅现有 Ferese 主题 IPC。
Ferese 负责候选弹窗的父窗口关联、层级、坐标和屏幕边界处理。候选不是普通应用窗口。

本设备的字体默认改为 **MiSans**，候选服务优先加载 **MiSans / MiSans TC**。
候选使用紧凑的横向布局，编号和候选字按实际字形边界垂直居中，
圆角、底色、边框和选中态颜色取自 Ferese 主题。
组字时数字行 `-` 翻上页、`=` 或 `+` 翻下页；普通英文状态保留这些字符。

librime 仍是 C++ 引擎，通过一个由安装头文件检查 ABI 的小型 C 接口连接 Rust。
组字、词库和候选光栅化都在服务进程内执行。当前实现没有使用 Fcitx5、IBus 或其 D-Bus 兼容服务。

合成器的改动包括：

- 在输入法开关下增加 `virtual-keyboard-v1`；默认不公开这两个输入法全局接口。
- 为辅助键盘保留独立按键来源；输入法自身转发的按键绕过它自己的 grab，避免回环。
- 拒绝锁屏期间的虚拟按键，并清理离线辅助设备的按键状态。
- 失去嵌套窗口焦点时释放物理来源的按键，清除快捷键重复和拦截状态。
- 区分 input-method 与 xdg popup 的几何语义；候选不再被父窗口的圆角边界裁剪。
- 在输出底部向上展开候选，在左右边界约束位置；缩放使用逻辑坐标与原生 viewport。

## 构建与启动

需要仓库的构建依赖，以及 `librime`、`xkbcommon` 和 Wayland 开发文件。
验证环境使用系统 librime 1.17.0、GTK4 4.24.1、RTX 4090、NVIDIA 615.78.08。
Rust 工具链由仓库固定为 1.95.0。

```sh
cargo build -p ferese -p feresectl -p ferese-rime --locked -j 12
python3 scripts/rime-preview.py start
python3 scripts/rime-preview.py status
```

预览使用开发版合成器、开发版输入法和已安装的 0.1.0 Shell。它会打开原生 GTK 测试框，
并在本机存在 Strata 时打开单独的测试目录。GTK 使用 `GTK_IM_MODULE=wayland`。

`scripts/rime-preview.py restart` 重开开发预览；`stop` 停止它；`ime` 只启动输入法服务。
输入法崩溃后桌面保留，英文可直接输入，执行 `ime` 可重新启用中文。

本机应用菜单中已有“Ferese Rime 开发预览”入口，右键操作可重开或停止。
入口仅调用本仓库脚本；移动仓库后应更新
`~/.local/share/applications/ferese-rime-preview.desktop` 中的路径。

预览的配置、缓存、词库和证据位于 `.artifacts/rime-poc-20261028/`。
运行时套接字位于当前 UID 的 `/run/user/<uid>/ferese-rime-poc/`，目录权限为 0700。
它使用独立 D-Bus 和独立 systemd 用户临时服务，不导入宿主桌面的激活环境。
测试词库由系统方案建立，不导入原有 IBus/Fcitx 个人词库。

## 验证

```sh
cargo test -p ferese input::binding_mode_tests -- --nocapture
cargo test -p ferese handlers::input_method::tests -- --nocapture
cargo test -p ferese-rime --lib --locked
cargo clippy -p ferese-rime -p ferese --all-targets --locked -- -D warnings
./target/debug/ferese-rime --user-data .artifacts/rime-poc-20261028/rime-self-test --self-test
FERESE_TEST_RIME=1 python3 scripts/tests/test_rime_native_isolated.py
```

最后一个测试实际启动构建树预览，操作专用原生 GTK 测试框，验证：

- 组字未提前提交、原生候选不是普通顶层窗口、空格和数字选字。
- 退格、取消、Shift 中英文切换、英文透传和 Ctrl+A 的按下/释放配对。
- 数字行减号、等号及 Shift+等号翻页，翻页后数字选字；候选保持单行横向排列。
- 敏感输入框直接收到测试英文，Rime 未收到这些组字事件。
- 底边候选组字和提交，以及候选主题的实时切换；截图单独检查位置和外观。
- 在组字期间 SIGKILL 输入法：合成器进程保持不变，英文继续输入，重启服务后恢复中文。
- 输入法进程实际映射 librime，未映射 IBus/Fcitx 库。
- 测试输入工具连接真实宿主时拒绝输入。

`ferese-rime-probe` 只供集成测试使用，需要显式 `FERESE_TEST_INPUT=1`，且在创建虚拟键盘前
检查目标确为只有 `ferese-winit` 输出的 Ferese 嵌套实例。测试不向宿主注入键盘事件。
测试框只输入可丢弃样本，其普通字段保存在 `entry-state.json` 便于独立读回；敏感字段只记录长度。
自动结果和截图保存在同一证据目录，不能用单纯的编译通过代替桌面输入验收。

2026-10-28 的本机自动检查全部通过；用户随后使用实际键盘确认
“显示、翻页和选字正常”。底边候选向上展开、浅深色主题已逐张检查截图。
输入法服务在组字时被强制终止后，桌面和英文输入仍工作，单独重启服务后中文恢复。

## 当前边界

- 已覆盖原生 GTK4 输入路径和 Strata 的候选显示，当前默认方案为 `luna_pinyin_simp`。
- 候选支持键盘选字；鼠标点选、配置界面、自动恢复策略仍待实现。
- 使用 US 键盘布局和嵌套输出验证；多布局切换、其他方案、个人词库迁移尚未验收。
- Qt、Electron、Xwayland 和 Shell 的 layer-surface 输入场景尚未验收。
- 独立登录后的 DRM、多屏热插拔、锁屏解锁和长期使用仍需验证。
- 当前为调试构建；字体加载、词库部署和重复绘制尚未进行性能优化。
- `FERESE_ENABLE_INPUT_METHOD=1` 仍沿用上游“受信任会话客户端”的许可边界，
  专用私有连接授权属于后续工作。

后续可以继续复用这套独立进程边界，逐步补齐候选交互和会话管理。