@rainmanhhh/pi-web 0.15.34 → 0.16.0

package/README.md

@@ -83,6 +83,25 @@ bunx --bun pi-web                      # 已全局安装时
 
 ## 开发
 
+### 为什么依赖 @earendil-works/pi-tui
+
+pi-tui 是**传递依赖**（`@earendil-works/pi-coding-agent` 的直接依赖，`pi-coding-agent/package.json` deps 含 `@earendil-works/pi-tui`），因此**不可移除**——它随 pi-coding-agent 原样装进 `node_modules`，删除本项目 `package.json` 里的顶层声明不会减少任何安装体积。它也不是可选/遗留包。
+
+真正承载 `PlainTextTheme` 的类是 `Theme`（`@earendil-works/pi-coding-agent` 导出，见 `src/lib/rpc/plain-theme.ts:1`），**不在** pi-tui 里；项目对 pi-tui 的唯一直接 import 在 `src/lib/rpc/plain-theme.ts:3-6`：
+
+```ts
+import { TUI_KEYBINDINGS, KeybindingsManager } from "@earendil-works/pi-tui";
+export const CUSTOM_UI_KEYBINDINGS = new KeybindingsManager(TUI_KEYBINDINGS);
+```
+
+用途：构造 `CUSTOM_UI_KEYBINDINGS`，经 `src/lib/rpc/extension-ui.ts:59` 作为第三参传给扩展 custom UI factory：`factory(tui, PLAIN_TEXT_THEME, CUSTOM_UI_KEYBINDINGS, done)`。
+
+**现实边界**：本项目**没有真正的 custom TUI 渲染**——`createHeadlessCustomUiTui`（`custom-ui-terminal.ts`）只提供 `{ terminal, requestRender }`，无 `addChild`/`setFocus`/组件树，pi-tui 官方示例式组件（`Input`/`SelectList` 等）跑不起来；custom UI 只桥接自渲染纯文本组件（`{ render, handleInput?, dispose? }` 契约）。因此 `CUSTOM_UI_KEYBINDINGS` **当前无实际消费方**（全项目仅定义点与传参点两处引用，`extension-ui-custom.ts` 的 `handleInput` 不读取它）——它仅为未来支持真实 custom TUI 渲染预留的桥，扩展组件若能按其纯文本契约运行，也可自行 `kb.matches(...)` 解析按键。
+
+**注意**：项目里其它提到 "pi-tui" 的地方（`src/lib/ansi.test.ts`、`src/lib/terminal-input.test.ts`、`src/lib/file-fuzzy.ts` 注释）只是测试名/注释，不是 import；`createHeadlessCustomUiTui`（`custom-ui-terminal.ts`）是本地手写的无头 TUI，也不依赖 pi-tui。
+
+升级时 pi-tui 必须与其他 `@earendil-works/pi-*` 包**同步同版本**（顶层显式声明 0.87.0 钉住版本，避免 `pi-coding-agent` 的 `^0.87` deps 解析出与顶层不一致的版本）。（这段曾写"扩展靠 keybinding 注册按键处理"，经核实不准确：扩展体系里 keybinding 本就走真终端 pi 的 TUI，且 `Theme` 类源自 pi-coding-agent 而非 pi-tui。）
+
 需要 [Bun](https://bun.sh) 和 Node.js 24.0.0+。面向开发者的调试指南（手动端口隔离、fixture URL 参数、手动验证场景、e2e 技巧）见 [docs/development.md](./docs/development.md)，发布流程见 [docs/release.md](./docs/release.md)。
 
 ```bash