pi-open-tui 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [0.4.4] - 2026-11-06
+
+### Added
+
+- Add `footerSegments.contextBar` to hide the context progress bar and its icon while keeping the percentage and token usage.
+
+### Fixed
+
+- Restore fullscreen Copy clicks when Pi exposes the active renderer through its stable TUI reference, including after switching display modes (#93).
+
+## [0.4.3] - 2026-11-05
+
+### New Features
+
+- Let extensions contribute text to either main footer row through the public `open-tui:footer:*` events, with placement, width priorities, lifecycle cleanup, and a separate visibility setting.
+- Add opt-in compact rows for extension, MCP, and replacement tools through `toolView.extensionTools`, with generic summaries and native rendering on expansion.
+- Add search-specific compact summaries for recognized `@ff-labs/pi-fff` installations, including page match counts, matching file totals, and pagination and fallback hints.
+- Allow selected tools, such as `edit`, to keep their native rendering in compact mode through `toolView.exclude`.
+
+### Breaking Changes
+
+- Require Pi 1.5.0 or later.
+
+### Changed
+
+- Group `/open-tui` settings into sections in English and Simplified Chinese, with non-selectable headings and scrolling that includes heading rows.
+- Keep feature introductions and usage examples in both READMEs, and move complete configuration and implementation details into bilingual reference documents in `docs/`.
+
+### Fixed
+
+- Show code-block Copy labels as soon as streaming ends, without requiring a terminal resize, and hide them when streaming resumes.
+- Preserve each Copy button's code and click region across Markdown block reuse, repeated identical blocks, and mixed cached and new blocks; restore source tabs using the current block occurrence.
+- Cancel pending Copy clicks when buttons are disabled, and suppress clipboard notifications from cleaned-up installations.
+- Make changed-word highlighting for short edit-preview lines independent of scheduling delays, while keeping matching limits for larger diffs.
+
 ## [0.4.2] - 2026-11-03
 
 ### Changed

package/README.md

@@ -8,24 +8,24 @@ A polished terminal interface for the [Pi](https://pi.dev) coding agent.
 
 ![pi-open-tui preview](https://raw.githubusercontent.com/OldSuns/pi-open-tui/main/assets/preview_dashboard_1.png)
 
-Live terminal screenshot with Pi 1.4.0.
-
 ## Highlights
 
 - **Pi header** with model, thinking level, working directory, and useful slash-command hints
-- **Responsive footer** with Git state, detected runtime, context usage, token counts, cost, and extension status
-- **Framed editor** with block, bar, and underline cursor styles; it preserves compatible editors installed by other extensions
-- **Project awareness** for 50+ runtimes and detailed Git states, including ahead/behind, staged, modified, untracked, stashed, and detached HEAD
-- **Turn telemetry** for TPS, time to first token (TTFT), duration, stalls, tokens, and list-price rate
-- **Thinking peek**: an inline ticker replaces Pi's hidden `Thinking...` label with the tail of the model's reasoning while it works
-- **Interactive settings** through `/open-tui`, available in English and Simplified Chinese
+- **Responsive footer** with Git state, detected runtime, context usage, tokens, cost, and extension status
+- **Framed editor** with block, bar, and underline cursors, preserving compatible editors from other extensions
+- **Project awareness** for 50+ runtimes and detailed Git state, including ahead/behind, staged, modified, untracked, stash, and detached HEAD
+- **Turn telemetry** with generation speed, time to first token, duration, stalls, tokens, and cost rate
+- **Thinking peek** with a live preview of hidden reasoning while the model works
+- **Compact tool view** with edit/write previews and optional support for extension and MCP tools
+- **Fullscreen Copy buttons** for code blocks and user messages
+- **Interactive settings** in English and Simplified Chinese through `/open-tui`
 
 ## Requirements
 
-- Pi 1.2.0 or later
+- Pi 1.5.0 or later
 - Node.js 22.19.0 or later (Pi's minimum)
 - A terminal with UTF-8 and color support
-- A [Nerd Font](https://www.nerdfonts.com/font-downloads) for the full icon set (optional; portable Unicode icons are built in)
+- A [Nerd Font](https://www.nerdfonts.com/font-downloads) for the full icon set (optional; Unicode and ASCII modes are available)
 
 ## Install
 
@@ -43,132 +43,64 @@ pi -e npm:pi-open-tui
 
 ## Font and icons
 
-Download any patched font from the official [Nerd Fonts downloads page](https://www.nerdfonts.com/font-downloads) or [latest GitHub release](https://github.com/ryanoasis/nerd-fonts/releases/latest). Install it, select that font in your terminal profile, and restart the terminal.
-
-The default `auto` mode checks the terminal environment, not the installed font file. It uses Nerd Font icons in interactive UTF-8 TTYs, including terminals running through a runner or subshell. If icons appear as boxes or incorrect symbols, open `/open-tui` and choose one of these modes under **Appearance**:
-
-- `nerd`: force Nerd Font icons after configuring a Nerd Font in the terminal
-- `unicode`: portable Unicode icons (folder, branch, laptop, bulb, plug, hourglass, ...) that render without a patched font; emoji glyphs use the terminal's emoji fallback
-- `ascii`: use plain-text icons with no patched font required
-- `auto`: use Nerd Font icons in interactive UTF-8 TTYs; use portable Unicode icons for SSH sessions (the client terminal controls the font and usually has no Nerd Font); use ASCII for non-interactive output, `TERM=dumb`, or an explicitly non-UTF-8 locale
+For the full icon set, install a [Nerd Font](https://www.nerdfonts.com/font-downloads), select it in your terminal profile, and restart the terminal. Installing the font in the OS alone is not enough for apps such as VS Code or Windows Terminal.
 
-If the font is installed but `auto` still selects ASCII, choose `nerd` explicitly. In VS Code, Windows Terminal, and similar apps, configure the font in the terminal profile rather than only installing it in the operating system. If your SSH client terminal does ship a Nerd Font and you want the full icon set over SSH, set the mode to `nerd` explicitly.
+In `/open-tui`, **Appearance → Icons** offers `auto`, `nerd`, `unicode`, and `ascii`. The default `auto` mode checks the terminal environment, not the installed font. If icons appear as boxes, choose `unicode`; if your terminal has a Nerd Font, you can force `nerd`, including over SSH.
 
-If wide Nerd Font icons visually consume the gap before their labels (for example in Kitty), enable `footerSegments.nerdIconSpacing` (**Footer → Extra space after Nerd icons** in `/open-tui`). The footer then reserves an extra blank cell after Nerd Font icons, including runtime icons, and includes it in regular and inline footer width calculations. Unicode/ASCII icons and compact Git status flags are unchanged. In Kitty, `narrow_symbols U+E000-U+F8FF 1` in `kitty.conf` is an alternative.
+See [icon detection and spacing](./docs/configuration.md#icons) for automatic selection rules and the Kitty spacing option.
 
 ## Configuration
 
-Run `/open-tui` to open the settings dialog. It provides **General**, **Appearance**, **Footer**, and **Telemetry** tabs and adapts to the terminal size. Settings are stored in `open-tui.json` inside Pi's agent directory, which defaults to `~/.pi/agent`; `PI_CODING_AGENT_DIR` overrides that directory. If saving fails, a warning explains that the change applies only to the current session.
-
-Example configuration:
-
-```json
-{
-  "enabled": true,
-  "header": true,
-  "inlineFooter": false,
-  "copyButtons": true,
-  "settingsLanguage": "en",
-  "cursorStyle": "block",
-  "icons": {
-    "mode": "auto"
-  },
-  "footerSegments": {
-    "cwd": true,
-    "hostname": false,
-    "sessionName": false,
-    "gitBranch": true,
-    "gitStatus": true,
-    "gitCommit": false,
-    "runtime": true,
-    "context": true,
-    "tokens": true,
-    "cost": true,
-    "liveTps": true,
-    "extensionStatuses": true,
-    "capitalizeProviderName": true,
-    "nerdIconSpacing": false
-  },
-  "telemetry": {
-    "enabled": true,
-    "tps": true,
-    "ttft": true,
-    "duration": true,
-    "tokens": true,
-    "stalls": true,
-    "cost": true
-  },
-  "thinkingPeek": {
-    "lines": 1
-  },
-  "toolView": {
-    "mode": "native"
-  }
-}
-```
+Run `/open-tui` to open the settings dialog. Its **General**, **Appearance**, **Footer**, and **Telemetry** tabs are available in English and Simplified Chinese and adapt to the terminal size. Use Tab/Shift+Tab or ←/→ to switch tabs, ↑/↓ to move, Enter/Space to change a value, and Esc/q to close.
 
-Key options:
+Settings are stored in `open-tui.json` inside Pi's agent directory (default: `~/.pi/agent`; overridden by `PI_CODING_AGENT_DIR`). If saving fails, a warning explains that the change applies only to the current session.
 
-| Option | Values | Notes |
+| Setting | Where to find it | Default |
 | --- | --- | --- |
-| `settingsLanguage` | `en`, `zh` | Changes the `/open-tui` interface language |
-| `header` | `true`, `false` | Overrides Pi's header with the open-tui header; set it to `false` to leave the header slot to Pi or another extension |
-| `inlineFooter` | `true`, `false` | Moves the two main Footer rows into the editor's top and bottom borders; defaults to `false`. Extension status rows remain below the editor |
-| `copyButtons` | `true`, `false` | Frames code blocks and shows a clickable `[Copy]` label on code blocks and user messages in fullscreen mode; defaults to `true`. See [Copy buttons](#copy-buttons) |
-| `cursorStyle` | `block`, `bar`, `underline` | `bar` and `underline` require terminal cursor-shape support |
-| `icons.mode` | `auto`, `nerd`, `unicode`, `ascii` | Controls footer and telemetry icons |
-| `footerSegments` | Boolean flags | Shows or hides individual footer data |
-| `footerSegments.capitalizeProviderName` | Boolean | Capitalizes the first character of the provider name in the footer; set it to `false` to keep the provider's original casing |
-| `footerSegments.nerdIconSpacing` | Boolean | Adds an extra blank cell after Nerd Font icons in the footer; defaults to `false` |
-| `telemetry` | Boolean flags | Enables telemetry and its individual measurements |
-| `thinkingPeek.lines` | `0`, `1`, `2` | Off, one-line, or two-line hidden thinking preview |
-| `toolView.mode` | `native`, `compact` | Pi's native cards (default) or compact call/summary rows with successful edit/write previews. Applies to rows created after the change |
-
-`sessionName` appears only when the session has a name. `hostname` shows the short host name (first label of the machine's host name, e.g. `mba` from `mba.example.com`) with a server icon. In detached HEAD state, `gitBranch` shows `HEAD` with the short commit hash; `gitCommit` appends the tag pointing at that commit and only takes effect while `gitBranch` is on. Disabling `extensionStatuses` hides the entire extension status line, including MCP status. Each status keeps the colours its extension applied with `ctx.ui.theme.fg()`. A status without colours renders in the muted theme colour.
+| Header and settings language | General → Interface | Header on, English |
+| Thinking peek | General → Messages & tools | 1 line |
+| Copy buttons | General → Messages & tools | On, fullscreen only |
+| Tool view | General → Messages & tools | Native |
+| Footer in editor border | General → Footer | Off |
+| Icons and cursor style | Appearance | Auto icons, block cursor |
+| Footer fields and telemetry measurements | Footer / Telemetry | Individually configurable |
 
-Footer token and cost totals include assistant responses, tool-reported usage, compaction and branch summaries, and cache warming. The cache-hit percentage describes the most recent assistant response, not the cumulative session.
+Selecting **Tool view: Compact** reveals **Compact extension tools** as a child setting. Switching back to Native hides it and retains its value. The [configuration reference](./docs/configuration.md#english) contains the complete JSON defaults, every option, and tool exclusions.
 
-When the first Footer row is too narrow, the runtime and context bar are hidden first, then Git, the session name, and the host name and timer. The CWD stays longest, shortened to its folder name.
+## Header, footer, and editor
 
-With `inlineFooter` enabled, the two normal Footer rows are rendered inside the editor frame to save vertical space. The top border places the Git branch on the left and CWD first in the right-hand group; the session title appears on the left too when `sessionName` is enabled. The Header and extension status rows remain separate; narrow terminals truncate lower-priority Footer data first, keeping the right-hand statistics and the border corner.
+The header provides model and project context with command hints. The two main footer rows keep location, Git state, runtime, a working/done timer, context usage, model details, tokens, and cost visible as space allows. Fields can be toggled individually; the layout shortens or hides lower-priority information in narrow terminals.
 
-open-tui frames existing editors that retain Pi’s native editor layout and its cursor, mouse, and padding APIs, including `CustomEditor` extensions. It decorates the same instance, preserving ghost text, key handling, completion, and submit callbacks. Editor extensions using the current `ctx.ui.setEditorComponent()` API can register before or after `pi-open-tui`; runtime replacements, including those made from shortcut callbacks with a fresh UI context, are framed too. Replacements are decorated when Pi mounts them, without calling the extension's factory again; temporary dialogs are left alone. Before decorating, open-tui renders the editor once at the terminal width to check for recognizable native top and bottom borders. Each framed render also checks its actual output; layouts without those borders are rendered again at the full requested width without frame mouse offsets, and framing resumes when native borders return. Editors without those capabilities or borders, or whose layout probe throws, remain unchanged, with the footer displayed separately even when `inlineFooter` is enabled. Disabling open-tui removes its decoration, restores the registration methods, and keeps the latest editor factory, including wrappers registered after open-tui.
+Footer token and cost totals include assistant responses, tool-reported usage, compaction and branch summaries, and cache warming. The cache-hit percentage describes the latest assistant response. Other extensions can use separate status rows or [contribute text directly to the main footer](./docs/footer-segments.md).
 
-This ordering guarantee applies to editor registration, not header or footer replacements. Extensions that bypass the current registration API by calling a previously saved setter or replacing the API methods themselves are outside this guarantee.
+Enable **Footer in editor border** to move the two main rows into the editor's top and bottom borders. Extension status rows remain below the editor. Compatible editors keep their input behavior, completion, and ghost text; editors that cannot be framed retain a separate footer. See [editor compatibility and layout](./docs/implementation.md#editor-and-layout) for the integration boundaries.
 
 ## Turn telemetry
 
-After each complete agent run, pi-open-tui shows one transient result. Tool-call turns are combined into that result:
+After each complete agent run, pi-open-tui shows one transient result, combining its assistant turns:
 
 ```text
 > TPS 42.5 tok/s | ~ TTFT 1.2s | + 29.7s | ↑ 567 | ↓ 1.2k | ! stall 1x / 4.3s | $ $3.60/M
 ```
 
-TPS is calculated from all provider-reported assistant output tokens divided by the total generation time across the run. Timing starts at `turn_start` and ends at the assistant `message_end`, so it includes TTFT, hidden reasoning, buffering, and stalls; tool execution between turns is excluded. Runs without output tokens or measurable generation time show `TPS —`.
+TPS measures provider-reported output tokens over generation time, including waiting and stalls but excluding tool execution between turns. The working timer also shows an estimated live speed such as `~54 tok/s` during streaming. The `$ / M` field is the effective rate per million tokens for the run; the footer shows cumulative session cost.
 
-While a response streams, the working timer also shows the current estimated speed, for example `working 12.3s · ~54 tok/s`. The `~` marks it as an estimate: it is the rate over the last 2 seconds of streamed text, thinking, and tool-call arguments, estimated at about 4 characters per token for Latin text and code and 1 token per CJK character. It drops toward zero during stalls and stays dimmed at its last value during tool execution and between messages. It is controlled by **Footer → Live TPS** (`footerSegments.liveTps`), independently of the telemetry notification. It disappears when the run ends; the exact TPS above is the authoritative value.
-
-The `$ / M` value is the model's list-price rate from `usage.cost.total`, not the cumulative session cost shown in the footer. Every telemetry field can be toggled from the **Telemetry** tab.
+Toggle notification fields under **Telemetry → Measurements**, or live speed under **Footer → Runtime → Live TPS**. See [measurement definitions](./docs/implementation.md#usage-and-telemetry) for formulas, timing boundaries, and cache accounting.
 
 ## Thinking peek
 
-When Pi's **Hide thinking** setting is enabled, pi-open-tui shows a compact ticker in the native hidden thinking block's `Thinking...` position. The `/open-tui` setting offers three modes: **Off**, **1 line**, and **2 lines**.
-
-- while the model is reasoning, the current thinking tail streams by with a spinner (`~ think ⠋ …`);
-- when the answer starts, it settles on a check mark (`~ think ✓`);
-- in 2-line mode, the previous and latest thinking lines share the same text indentation; if the latest line overflows, both rows follow its newest tail as tokens arrive instead of retaining the previous line;
-- after the task settles, the native `Thinking...` label is restored.
+With Pi's **Hide thinking** enabled, pi-open-tui replaces the hidden block's `Thinking...` label with the latest reasoning tail while the model works:
 
 ```text
 ~ think ⠋ previous thought
           latest thought
 ```
 
-The ticker appears only once the model actually streams reasoning, so non-reasoning models never show it. Pi's own Hide thinking toggle controls visibility; changing it takes effect immediately. Each row is truncated by *visible* width, so CJK-wide thinking text cannot overflow. Configure it from **General → Thinking peek** in `/open-tui`, or via `thinkingPeek.lines` in `open-tui.json`.
+Choose **Off**, **1 line**, or **2 lines** under **General → Messages & tools → Thinking peek**. The ticker appears only when the model streams reasoning, settles on a check mark when the answer begins, and returns to Pi's native label after the task settles. It follows Pi's Hide thinking toggle immediately and clips text to fit the available width.
 
 ## Tool view
 
-**Native** remains the default. With **General → Tool view** set to **Compact** (`toolView.mode: "compact"`), Pi's built-in tools (`read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, `ls`) render as one call line and one summary line, with previews for successful edits and writes:
+**Native** remains the default. Select **General → Messages & tools → Tool view → Compact** to display Pi's built-in tools (`read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, `ls`) as call and summary rows:
 
 ```text
 ● Read(extensions/open-tui/footer.ts:1-120)
@@ -179,18 +111,17 @@ The ticker appears only once the model actually streams reasoning, so non-reason
   └  Done · 131 lines · 6.4s
 ```
 
-- Successful calls have dim call/summary text and a green dot. Pending dots are dim; running dots alternate between accent and dim once per second. Errors keep the red dot and summary. Failed shell summaries retain the last output line; while running, shell commands show the newest 3 output lines and elapsed time.
-- Successful `edit` previews parse Pi's actual diff and syntax-highlight old and new code separately. Removed/added rows have red/green background bands ending two columns before the terminal's right edge. Stronger changed-word backgrounds apply only to paired adjacent removed/added lines sharing at least 30% non-whitespace content; exceeding the matching budget falls back to whole-line highlighting. Without a valid diff, the summary stays.
-- Successful `write` previews show syntax-highlighted content with line numbers and no `+` signs on the normal, neutral terminal background. New files and overwrites look the same; no old-file diff is shown. Partial results and errors get no success previews.
-- Preview bodies show at most 16 rows; longer bodies show the first 16 plus a hidden-row count and `Ctrl+O` hint. Edit context and ellipsis rows count toward these limits. In compact mode only, long lines truncate horizontally with `…` instead of wrapping.
-- Clicking a row expands only that row into Pi's native card, and `Ctrl+O` expands all rows. Native expanded rendering, including full output, diffs, and truncation notices, is unchanged. Calls remain separate, with no grouping or extra configuration.
-- Only the display changes. Tools, arguments, results, and what the model sees are untouched. Only tools confirmed by Pi as built-in are wrapped; third-party and MCP tools, including replacements with built-in names, keep their own rendering.
-- Compact summaries flag truncated output, including grep's long-line truncation. Bracketed output and failure messages are preserved rather than mistaken for tool notices.
-- The mode is chosen when Pi creates a row, so switching it affects new rows; `/reload` or a new session applies it to the whole transcript.
+- Successful `edit` and `write` calls show syntax-highlighted previews of up to 16 rows, with a hint to expand longer output.
+- Running shell calls show recent output and elapsed time; errors retain their error summary.
+- Click a row to expand its native card, or use `Ctrl+O` to expand all rows. Tools, arguments, results, and model-visible content are unchanged.
+- Enable **Compact extension tools** to include extension and MCP tools. Use `toolView.exclude` in the config file for tools that should keep native rendering. Recognized `@ff-labs/pi-fff` tools receive search-specific summaries.
+- Changing the mode affects newly created rows. Use `/reload` or a new session to apply it to the whole transcript.
+
+See [tool rendering details](./docs/implementation.md#tool-rendering) for preview rules, extension summaries, and renderer compatibility.
 
 ## Copy buttons
 
-In fullscreen mode (Pi's `tuiMode: "fullscreen"`), every fenced code block is drawn in a rounded frame with its language and an always-visible `[Copy]` label in the top border, and every user message gets a `[Copy]` label too. Click it to put the source text on the clipboard; Pi flashes `Copied!`.
+In fullscreen mode (Pi's `tuiMode: "fullscreen"`), completed code blocks show a clickable `[Copy]` label in their rounded frame when there is enough width. User messages have a Copy label too. Clicking copies the source text and Pi flashes `Copied!`.
 
 ```text
 ╭─ sh ─────────────── [Copy] ╮
@@ -198,15 +129,16 @@ In fullscreen mode (Pi's `tuiMode: "fullscreen"`), every fenced code block is dr
 ╰────────────────────────────╯
 ```
 
-- Code blocks: the frame replaces the two fence rows, so a block keeps its height; long lines wrap inside the frame. The label copies the code without the fences, with indentation and tabs preserved. This applies to code in both user and assistant messages.
-- User messages: the label sits on the bubble's last row and copies the message as you typed it.
-- Whole assistant replies have no label; use Pi's `/copy` for that.
-- While a reply streams, its code blocks are framed without a label, so you cannot copy unfinished code. The label is also dropped when the frame is too narrow; thinking blocks keep Pi's plain fences.
-- Regular mode has no mouse capture, so code blocks keep Pi's plain fences there.
-- Drag-selecting across a frame includes its border characters and the `[Copy]` text.
-- If pi-pretty-tui is installed, its own code-block frames and copy buttons are kept and these are not drawn.
+Code labels copy code without fences, preserving indentation and tabs. User-message labels copy the original message. Streaming code blocks gain their label when streaming finishes; regular mode and thinking blocks keep Pi's plain fences. Use Pi's `/copy` to copy a whole assistant reply.
+
+Toggle **General → Messages & tools → Copy buttons** to enable or disable this feature. [Copy-button details](./docs/implementation.md#copy-button-behavior) cover width limits, cached blocks, and interaction with other renderers.
+
+## Documentation
 
-Toggle it from **General → Copy buttons** in `/open-tui`, or via `copyButtons` in `open-tui.json`.
+- [Configuration reference](./docs/configuration.md#english) — complete defaults, options, and icon selection
+- [Implementation and compatibility](./docs/implementation.md#english) — measurement formulas, layout, rendering, and lifecycle
+- [Extension footer segments](./docs/footer-segments.md) — public events and an integration example for extension authors
+- [Changelog](./CHANGELOG.md) — released and upcoming changes
 
 ## Local development
 
@@ -217,7 +149,7 @@ npm run typecheck
 pi -e .
 ```
 
-CI checks Pi 1.2.0 and the latest release on Node.js 22.19.0 and 24, across Linux, Windows, and macOS. Keep Pi packages on the same version when checking compatibility. Automated tests do not replace checking terminal fonts, mouse interaction, and cursor support with `pi -e .`.
+CI checks Pi 1.5.0 and the latest release on Node.js 22.19.0 and 24 across Linux, Windows, and macOS. Keep all Pi packages on the same version. Use `pi -e .` to check terminal fonts, mouse interaction, and cursor support interactively.
 
 ## Acknowledgements
 

package/README.zh-CN.md

@@ -8,24 +8,24 @@
 
 ![pi-open-tui 预览](https://raw.githubusercontent.com/OldSuns/pi-open-tui/main/assets/preview_dashboard_1.png)
 
-Pi 1.4.0 的真实终端截图。
-
 ## 功能亮点
 
 - **Pi 顶栏**：显示模型、思考等级、当前目录和常用斜杠命令提示
-- **自适应底栏**：集中展示 Git 状态、运行环境、上下文用量、Token、费用和扩展状态
-- **带边框的编辑器**：支持块状、竖线和下划线三种光标样式；保留其它扩展已安装的兼容编辑器
-- **项目环境感知**：识别 50 多种运行环境，并展示 ahead/behind、已暂存、已修改、未跟踪、stash 和 detached HEAD 等 Git 状态
-- **单轮遥测**：展示 TPS、首 Token 延迟（TTFT）、耗时、停顿、Token 数量和模型标价速率
-- **思考预览**：模型工作时，在 Pi 隐藏思考块的 `Thinking...` 位置显示实时字幕，展示推理内容的末尾片段
-- **交互式设置**：通过 `/open-tui` 配置，并支持英文和简体中文界面
+- **自适应底栏**：展示 Git 状态、运行环境、上下文用量、Token、费用和扩展状态
+- **带边框的编辑器**：支持块状、竖线和下划线光标，保留其他扩展的兼容编辑器
+- **项目环境感知**：识别 50 多种运行环境，并展示 ahead/behind、已暂存、已修改、未跟踪、stash 和分离 HEAD 等 Git 状态
+- **单轮遥测**：展示生成速度、首 Token 延迟、耗时、停顿、Token 数量和费用速率
+- **思考预览**：模型工作时实时预览隐藏的推理内容
+- **紧凑工具视图**：提供编辑/写入预览，可选支持扩展和 MCP 工具
+- **全屏复制按钮**：一键复制代码块和用户消息
+- **交互式设置**：通过 `/open-tui` 使用英文或简体中文界面
 
 ## 环境要求
 
-- Pi 1.2.0 或更高版本
+- Pi 1.5.0 或更高版本
 - Node.js 22.19.0 或更高版本（Pi 的最低要求）
 - 支持 UTF-8 和彩色输出的终端
-- 使用完整图标集时需要 [Nerd Font](https://www.nerdfonts.com/font-downloads)（可选；内置可移植 Unicode 图标）
+- 使用完整图标集时需要 [Nerd Font](https://www.nerdfonts.com/font-downloads)（可选，也可使用 Unicode 或 ASCII 模式）
 
 ## 安装
 
@@ -43,132 +43,64 @@ pi -e npm:pi-open-tui
 
 ## 字体与图标
 
-可从 [Nerd Fonts 官方下载页](https://www.nerdfonts.com/font-downloads)或 [GitHub 最新版本](https://github.com/ryanoasis/nerd-fonts/releases/latest)下载任意已修补字体。安装后，请在终端配置中选择该字体，并重启终端。
-
-默认的 `auto` 模式检查终端环境，而不是已安装的字体文件。在支持 UTF-8 的交互式 TTY 中，它会使用 Nerd Font 图标，即使 Pi 运行在 runner 或子 shell 中。如果图标显示为方框、乱码或错误符号，请打开 `/open-tui`，在**外观**页选择合适的模式：
-
-- `nerd`：终端已配置 Nerd Font 时，强制使用 Nerd Font 图标
-- `unicode`：可移植 Unicode 图标（文件夹、分支、笔记本电脑、灯泡、插头、沙漏等），无需修补字体；emoji 字形通过终端的 emoji 回退渲染
-- `ascii`：使用纯文本图标，无需安装修补字体
-- `auto`：在支持 UTF-8 的交互式 TTY 中使用 Nerd Font 图标；SSH 会话使用可移植 Unicode 图标（字体由客户端终端决定，通常没有 Nerd Font）；非交互式输出、`TERM=dumb` 或明确配置为非 UTF-8 的 locale 使用 ASCII
+使用完整图标集时，请安装 [Nerd Font](https://www.nerdfonts.com/font-downloads)，在终端配置中选中它并重启终端。使用 VS Code、Windows Terminal 等应用时，只在操作系统中安装字体还不够。
 
-如果已经安装字体，但 `auto` 仍选择 ASCII，请手动切换为 `nerd`。使用 VS Code、Windows Terminal 等应用时，只在操作系统中安装字体还不够，还需要在对应的终端配置中选中该字体。如果 SSH 客户端终端确实安装了 Nerd Font 并希望在 SSH 下使用完整图标，请将模式显式设为 `nerd`。
+`/open-tui` 的**外观 → 图标**提供 `auto`、`nerd`、`unicode` 和 `ascii`。默认 `auto` 检查终端环境，并不检查实际字体；图标显示为方框时可选 `unicode`，终端已配置 Nerd Font 时可强制选 `nerd`，SSH 会话同样适用。
 
-如果较宽的 Nerd Font 图标占用了图标与文字之间的间隔（例如在 Kitty 中），可开启 `footerSegments.nerdIconSpacing`（`/open-tui` 中的 **底栏 → Nerd 图标后额外留空**）。开启后底栏会在 Nerd Font 图标后额外预留一格空白，包括运行环境图标，常规底栏和内嵌底栏的宽度计算都包含这格留白；Unicode/ASCII 图标与紧凑的 Git 状态标记不受影响。Kitty 用户也可以在 `kitty.conf` 中设置 `narrow_symbols U+E000-U+F8FF 1`。
+自动选择规则和 Kitty 的间距选项见[图标检测与间距](./docs/configuration.md#图标)。
 
 ## 配置
 
-运行 `/open-tui` 打开设置窗口，其中包含**常规**、**外观**、**底栏**和**遥测**四个页面，并会适应终端尺寸。设置保存在 Pi 的 agent 目录内的 `open-tui.json` 中；默认目录为 `~/.pi/agent`，可通过 `PI_CODING_AGENT_DIR` 覆盖。保存失败时会提示：修改仅在当前会话生效。
-
-配置示例：
-
-```json
-{
-  "enabled": true,
-  "header": true,
-  "inlineFooter": false,
-  "copyButtons": true,
-  "settingsLanguage": "zh",
-  "cursorStyle": "block",
-  "icons": {
-    "mode": "auto"
-  },
-  "footerSegments": {
-    "cwd": true,
-    "hostname": false,
-    "sessionName": false,
-    "gitBranch": true,
-    "gitStatus": true,
-    "gitCommit": false,
-    "runtime": true,
-    "context": true,
-    "tokens": true,
-    "cost": true,
-    "liveTps": true,
-    "extensionStatuses": true,
-    "capitalizeProviderName": true,
-    "nerdIconSpacing": false
-  },
-  "telemetry": {
-    "enabled": true,
-    "tps": true,
-    "ttft": true,
-    "duration": true,
-    "tokens": true,
-    "stalls": true,
-    "cost": true
-  },
-  "thinkingPeek": {
-    "lines": 1
-  },
-  "toolView": {
-    "mode": "native"
-  }
-}
-```
+运行 `/open-tui` 打开设置窗口，包含**常规**、**外观**、**底栏**和**遥测**四个页面，支持英文和简体中文，并适应终端尺寸。Tab/Shift+Tab 或 ←/→ 切页，↑/↓ 移动，Enter/Space 修改值，Esc/q 关闭。
 
-主要选项：
+设置保存在 Pi 的 agent 目录内的 `open-tui.json` 中，默认目录是 `~/.pi/agent`，可通过 `PI_CODING_AGENT_DIR` 覆盖。保存失败时会提示：修改仅在当前会话生效。
 
-| 选项 | 可选值 | 说明 |
+| 设置 | 位置 | 默认值 |
 | --- | --- | --- |
-| `settingsLanguage` | `en`、`zh` | 切换 `/open-tui` 设置界面的语言 |
-| `header` | `true`、`false` | 决定是否用 open-tui 顶部信息栏覆盖 Pi 的 Header；设为 `false` 时把顶部栏位置留给 Pi 或其他扩展 |
-| `inlineFooter` | `true`、`false` | 将两条主要 Footer 信息行移入编辑器上下边框以节省垂直空间，默认关闭；扩展状态行仍显示在编辑器外 |
-| `copyButtons` | `true`、`false` | 全屏模式下给代码块加圆角边框，并在代码块和用户消息上显示可点击的 `[Copy]` 标签，默认开启；见[复制按钮](#复制按钮) |
-| `cursorStyle` | `block`、`bar`、`underline` | `bar` 和 `underline` 需要终端支持光标形状转义序列 |
-| `icons.mode` | `auto`、`nerd`、`unicode`、`ascii` | 控制底栏和遥测通知使用的图标 |
-| `footerSegments` | 布尔开关 | 分别控制底栏中的各项数据 |
-| `footerSegments.capitalizeProviderName` | 布尔开关 | 将底栏中提供商名称的首字母大写；设为 `false` 时保留原始大小写 |
-| `footerSegments.nerdIconSpacing` | 布尔开关 | 在底栏 Nerd Font 图标后额外留一格空白；默认 `false` |
-| `telemetry` | 布尔开关 | 控制遥测总开关和各项指标 |
-| `thinkingPeek.lines` | `0`、`1`、`2` | 关闭、单行或双行思考预览 |
-| `toolView.mode` | `native`、`compact` | Pi 原生卡片（默认），或带编辑/写入成功预览的紧凑调用与摘要行。只对切换后新建的行生效 |
-
-`sessionName` 仅在会话有名称时显示；`hostname` 会显示主机名的短名称（主机名的第一个标签，例如从 `mba.example.com` 显示为 `mba`），并使用服务器图标；处于分离 HEAD（detached HEAD）状态时，`gitBranch` 会显示 `HEAD` 和短提交哈希，`gitCommit` 会在其后追加指向该提交的标签，且仅在开启 `gitBranch` 时生效；关闭 `extensionStatuses` 会隐藏整行扩展状态，其中也包括 MCP 状态。每条状态会保留其扩展通过 `ctx.ui.theme.fg()` 设置的颜色；未设置颜色的状态使用 muted 主题色显示。
+| 顶栏与设置语言 | 常规 → 界面 | 顶栏开启、英文 |
+| 思考预览 | 常规 → 消息与工具 | 单行 |
+| 复制按钮 | 常规 → 消息与工具 | 开启，仅全屏模式 |
+| 工具视图 | 常规 → 消息与工具 | 原生 |
+| 底栏嵌入输入框 | 常规 → 底栏 | 关闭 |
+| 图标与光标样式 | 外观 | 自动图标、块状光标 |
+| 底栏字段与遥测指标 | 底栏 / 遥测 | 可分别设置 |
 
-底栏的 Token 和费用总计包含助手回复、工具报告的用量、压缩与分支摘要以及缓存预热；缓存命中百分比表示最近一条助手回复，而非整个会话的累计比例。
+选择**工具视图：紧凑**后，才会显示子选项**紧凑显示扩展工具**；切回原生时隐藏该选项并保留其值。完整 JSON 默认配置、所有选项和工具排除列表见[配置参考](./docs/configuration.md#简体中文)。
 
-底栏第一行宽度不足时，先隐藏运行环境和上下文条，然后依次隐藏 Git、会话名称、主机名和计时器；当前目录保留到最后，并缩短为文件夹名。
+## 顶栏、底栏与编辑器
 
-开启 `inlineFooter` 后，两条常规 Footer 信息行会移入编辑器边框，从而节省垂直空间。顶部边框左侧显示 Git 分支，右侧信息组以当前目录开头；开启 `sessionName` 时，会话标题也会显示在左侧。Header 和扩展状态行保持独立显示；终端较窄时优先截断低优先级 Footer 数据，保留右侧统计信息和边框角。
+顶栏提供模型、项目环境和命令提示。两条主底栏集中显示位置、Git 状态、运行环境、工作/完成计时器、上下文用量、模型详情、Token 和费用。可单独开关各项字段；终端变窄时，布局会缩短或隐藏低优先级信息。
 
-open-tui 会给保留 Pi 原生编辑器布局及光标、鼠标、内边距接口的编辑器加边框，包括基于 `CustomEditor` 的扩展。装饰直接作用于同一实例，因此灰字建议、按键处理、补全和提交回调能够保留。通过当前 `ctx.ui.setEditorComponent()` 接口注册的编辑器扩展可以排在 `pi-open-tui` 前面或后面，运行时替换编辑器也会自动加框，包括在持有新 UI 上下文的快捷键回调中替换。替换后的实例在 Pi 挂载时直接装饰，不会再次调用扩展的创建函数；临时对话框保持原样。装饰前，open-tui 会按终端宽度渲染一次编辑器，检查是否存在可识别的原生上下边界。每次加框也会检查本次实际输出；没有这些边界时按完整请求宽度重新渲染，不应用边框的鼠标坐标偏移，原生边界恢复后再继续加框。缺少这些能力或边界、或在布局检测时抛出异常的编辑器保持原样，即使开启 `inlineFooter`，底栏也会独立显示。关闭 open-tui 会撤销装饰、恢复注册接口，并保留最新的编辑器工厂，包括后注册的扩展包装。
+底栏 Token 和费用总计包含助手回复、工具报告的用量、压缩与分支摘要以及缓存预热；缓存命中率表示最近一条助手回复。其他扩展可以使用独立状态行，也可以[直接向主底栏添加内容](./docs/footer-segments.md)。
 
-顺序无关的保证针对编辑器注册，不包含顶栏或底栏的替换。如果扩展调用预先保存的旧注册函数，或直接替换注册接口本身，则不在此保证范围内。
+开启**底栏嵌入输入框**，可把两条主信息行移入编辑器上下边框，扩展状态行仍显示在编辑器下方。兼容编辑器会保留输入行为、补全和灰字建议；无法加框的编辑器继续使用独立底栏。集成边界见[编辑器兼容性与布局](./docs/implementation.md#编辑器与布局)。
 
 ## 单轮遥测
 
-每次 Agent 完整运行结束后，pi-open-tui 会显示一条临时结果，并将其中的多个工具调用轮次合并统计：
+每次 Agent 完整运行结束后，pi-open-tui 会合并其中的助手轮次，显示一条临时结果：
 
 ```text
 > TPS 42.5 tok/s | ~ TTFT 1.2s | + 29.7s | ↑ 567 | ↓ 1.2k | ! stall 1x / 4.3s | $ $3.60/M
 ```
 
-TPS 的计算方式是：将本次运行中服务商报告的全部 Assistant 输出 Token，除以各个生成轮次的总耗时。计时范围从 `turn_start` 到 Assistant 的 `message_end`，包含 TTFT、隐藏推理、缓冲和停顿，但不包含轮次之间的工具执行时间。没有输出 Token 或无法测得生成时间时，会显示 `TPS —`。
+TPS 用服务商报告的输出 Token 除以生成时间，包含等待和停顿，不包含轮次之间的工具执行时间。流式输出期间，工作计时器还会显示 `~54 tok/s` 这样的实时估算速度。`$ / M` 表示本次运行每百万 Token 的综合费率，底栏则显示会话累计费用。
 
-回复流式输出时，工作计时器还会显示当前的估算速度，例如 `working 12.3s · ~54 tok/s`。`~` 表示估算值：它是最近 2 秒内流式输出的正文、思考内容和工具调用参数的速率，按拉丁文本和代码约 4 个字符 1 个 Token、中日韩字符每字 1 个 Token 估算。停顿时数值会逐渐降向零；工具执行期间和消息之间以暗色保留上一个值。由**底栏 → 实时 TPS**（`footerSegments.liveTps`）控制，与遥测通知的开关互不影响。运行结束后不再显示，以上面的精确 TPS 为准。
-
-`$ / M` 表示根据 `usage.cost.total` 得到的模型标价速率，不是底栏中的会话累计费用。所有遥测字段都可以在**遥测**页单独开关。
+可在**遥测 → 测量指标**中开关通知字段，在**底栏 → 运行环境 → 实时 TPS**中控制实时速度。计算公式、计时边界和缓存统计见[指标定义](./docs/implementation.md#用量与遥测)。
 
 ## 思考预览
 
-开启 Pi 的 **Hide thinking** 后，任务运行期间 pi-open-tui 会在原生隐藏思考块的 `Thinking...` 位置显示紧凑的实时字幕。`/open-tui` 中提供**关闭、单行、双行**三种模式：
-
-- 模型推理时，思考内容的末尾片段会随 spinner 滚动（`~ think ⠋ …`）；
-- 开始输出正文时定格为对勾（`~ think ✓`）；
-- 双行模式中，上一条和最新一条思考内容使用相同的文字缩进；如果最新一行超出宽度，则两行随新 Token 持续显示它的最新末尾片段，不再保留上一条；
-- 任务结束后恢复原生 `Thinking...` 标签。
+开启 Pi 的 **Hide thinking** 后，模型工作时 pi-open-tui 会用最新推理片段替换隐藏思考块的 `Thinking...` 标签：
 
 ```text
 ~ think ⠋ 上一条思考
           最新一条思考
 ```
 
-该字幕仅在模型真正输出推理内容后出现，非推理模型不会显示。可见性由 Pi 自身的 Hide thinking 开关控制，切换后立即生效。每一行都按*显示宽度*截断（全角字符计 2 列），因此包含中文的思考文本也不会溢出终端。可在 `/open-tui` 的**常规 → 思考预览**中切换，或直接修改 `open-tui.json` 中的 `thinkingPeek.lines`。
+在**常规 → 消息与工具 → 思考预览**中选择**关闭、单行或双行**。字幕仅在模型真正输出推理时出现，正文开始后变为对勾，任务结束后恢复原生标签。可见性随 Pi 的 Hide thinking 开关立即变化，文字会按可用宽度截断。
 
 ## 工具视图
 
-默认仍为**原生**模式。将**常规 → 工具视图**设为**紧凑**（`toolView.mode: "compact"`）后，Pi 内置工具（`read`、`bash`、`powershell`、`edit`、`write`、`grep`、`find`、`ls`）显示为一行调用加一行摘要，编辑和写入成功时附带预览：
+默认使用**原生**模式。在**常规 → 消息与工具 → 工具视图**中选择**紧凑**后，Pi 内置工具（`read`、`bash`、`powershell`、`edit`、`write`、`grep`、`find`、`ls`）显示为调用行和摘要行：
 
 ```text
 ● Read(extensions/open-tui/footer.ts:1-120)
@@ -179,18 +111,17 @@ TPS 的计算方式是：将本次运行中服务商报告的全部 Assistant
   └  Done · 131 lines · 6.4s
 ```
 
-- 成功后调用与摘要文字变暗，圆点为绿色；等待时圆点变暗，运行时圆点每秒在主题强调色与暗色之间切换。错误继续显示红色圆点与摘要。Shell 失败摘要保留最后一行输出；运行中显示最新 3 行输出和已用时间。
-- `edit` 成功预览解析 Pi 的真实 diff，分别对旧代码和新代码做语法高亮。删除/新增行使用红/绿整行背景色带，在终端右边缘前留出两列。仅相邻且配对、共享非空白内容至少占 30% 的删除/新增行使用更强的变更词背景；超出匹配预算时回退到整行高亮。没有有效 diff 时保留摘要。
-- `write` 成功预览使用正常、中性的终端背景，显示行号和语法高亮，不带 `+` 号。新建与覆盖写入显示相同，不对比旧文件。部分结果和错误不显示成功预览。
-- 预览正文最多显示 16 行；超过时显示前 16 行，加上隐藏行数与 `Ctrl+O` 提示。编辑的上下文行和省略行也计入行数。仅紧凑模式下，长行以 `…` 横向截断，不自动换行。
-- 点击某行只展开这一行为 Pi 原生卡片，`Ctrl+O` 展开全部行；原生展开视图的完整输出、diff 和截断提示保持不变。各次调用独立显示，不分组，也不增加配置项。
-- 只改变显示：工具、参数、结果以及模型看到的内容都不受影响。仅接管 Pi 确认来源为内置的工具；第三方和 MCP 工具（包括替换内置同名工具的扩展）保持各自的渲染。
-- 紧凑摘要会标记输出截断，包括 grep 的长行截断；方括号正文和失败信息会保留，不会被误当成工具通知删除。
-- 模式在 Pi 创建某行时确定，因此切换只影响新建的行；执行 `/reload` 或新开会话后整个记录都会应用。
+- `edit` 和 `write` 成功后显示带语法高亮的预览，最多 16 行，较长输出会提示展开。
+- Shell 运行时显示近期输出和已用时间；出错时保留错误摘要。
+- 点击某行展开其原生卡片，`Ctrl+O` 展开全部行。工具、参数、结果和模型看到的内容都不改变。
+- 开启**紧凑显示扩展工具**可包含扩展和 MCP 工具；需要保留原生显示的工具可写入配置文件中的 `toolView.exclude`。识别到的 `@ff-labs/pi-fff` 工具使用专门的搜索摘要。
+- 切换模式只影响新建的行；执行 `/reload` 或新开会话后，整个记录都会应用。
+
+预览规则、扩展摘要和渲染器兼容性见[工具渲染细节](./docs/implementation.md#工具渲染)。
 
 ## 复制按钮
 
-全屏模式（Pi 的 `tuiMode: "fullscreen"`）下，每个代码块都会画在圆角边框里，顶边显示语言和始终可见的 `[Copy]` 标签；每条用户消息也有 `[Copy]` 标签。点击即可把原始文本放入剪贴板，Pi 会短暂提示 `Copied!`。
+全屏模式（Pi 的 `tuiMode: "fullscreen"`）下，完成的代码块会在宽度足够时，在圆角边框中显示可点击的 `[Copy]` 标签；用户消息也有复制标签。点击后复制原文，Pi 会短暂提示 `Copied!`。
 
 ```text
 ╭─ sh ─────────────── [Copy] ╮
@@ -198,15 +129,16 @@ TPS 的计算方式是：将本次运行中服务商报告的全部 Assistant
 ╰────────────────────────────╯
 ```
 
-- 代码块：边框替代了上下两行围栏，代码块高度不变；过长的行在边框内换行。标签复制不含围栏的代码，保留缩进和制表符。用户消息和助手回复里的代码块都适用。
-- 用户消息：标签位于气泡最后一行，复制你输入的原文。
-- 整条助手回复没有标签，请使用 Pi 的 `/copy`。
-- 回复输出过程中代码块只有边框、没有标签，避免复制到不完整的代码；边框太窄时也不显示标签；思考块保留 Pi 原生的围栏。
-- 普通模式不捕获鼠标，代码块保留 Pi 原生的围栏。
-- 拖动选择经过边框时会包含边框字符和 `[Copy]` 文字。
-- 如果同时安装了 pi-pretty-tui，则保留它自己的代码块边框和复制按钮，不再绘制这些内容。
+代码标签复制不含围栏的代码，保留缩进和制表符；用户消息标签复制输入原文。流式代码块会在输出结束后显示标签；普通模式和思考块保留 Pi 原生围栏。复制整条助手回复请使用 Pi 的 `/copy`。
+
+可在**常规 → 消息与工具 → 复制按钮**中开关此功能。宽度限制、代码块缓存和与其他渲染器共存的细节见[复制按钮说明](./docs/implementation.md#复制按钮行为)。
+
+## 文档
 
-可在 `/open-tui` 的**常规 → 复制按钮**中切换，或直接修改 `open-tui.json` 中的 `copyButtons`。
+- [配置参考](./docs/configuration.md#简体中文) — 完整默认值、配置项和图标选择规则
+- [实现与兼容性](./docs/implementation.md#简体中文) — 指标公式、布局、渲染和生命周期
+- [扩展底栏接口（英文）](./docs/footer-segments.md) — 面向扩展开发者的公开事件和接入示例
+- [更新日志](./CHANGELOG.md) — 已发布和待发布的改动
 
 ## 本地开发
 
@@ -217,7 +149,7 @@ npm run typecheck
 pi -e .
 ```
 
-CI 在 Linux、Windows、macOS 上，使用 Node.js 22.19.0 和 24，检查 Pi 1.2.0 及最新版本。核对兼容性时应让各个 Pi 包保持同一版本。自动化测试不能替代通过 `pi -e .` 检查终端字体、鼠标交互和光标支持。
+CI 在 Linux、Windows、macOS 上，使用 Node.js 22.19.0 和 24 检查 Pi 1.5.0 及最新版本。核对兼容性时应让所有 Pi 包保持同一版本。终端字体、鼠标交互和光标支持可通过 `pi -e .` 实际检查。
 
 ## 致谢