pi-one-ui 0.2.2 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.1] - 2026-08-31
+
+### Changed
+
+- Unified the test suite on Vitest and reorganized tests into domain-oriented directories.
+
+### Fixed
+
+- Keep `/oneui` open and focused during in-place Editor changes, restore effective values after persistence failures, and position the panel closer to the top.
+- Reduced global tool expansion latency and preserved pi-subagents' dedicated live progress renderer instead of wrapping and grouping it as a generic tool.
+
+## [0.3.0] - 2026-08-30
+
+### Added
+
+- Added a maintained English README with bidirectional language navigation.
+
+### Changed
+
+- Use `~/.pi/agent/pi-one-ui.json` as the only configuration source.
+- Persist settings with the canonical v1 `components` and `renderer` structure.
+
+### Removed
+
+- Removed automatic loading and migration of `pi-mine-ui.json`, `zentui.json`, and `claude-code-style.json`.
+- Removed legacy flat configuration fields, old style identifiers, and WorkingLine aliases.
+- Removed the legacy `enableWorkingMessage` renderer option.
+
+### Migration
+
+- Before upgrading, recreate or translate supported settings into the canonical `components` and `renderer` structure in `~/.pi/agent/pi-one-ui.json`.
+- Use `/oneui` to write settings in the canonical format, then run `/reload`.
+
+## [0.2.2] - 2026-08-29
+
+### Fixed
+
+- Reduced rendering lag when expanding settled tool groups by reusing cached child output.
+
+[Unreleased]: https://github.com/kerolt/pi-one-ui/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/kerolt/pi-one-ui/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/kerolt/pi-one-ui/compare/v0.2.2...v0.3.0
+[0.2.2]: https://github.com/kerolt/pi-one-ui/compare/v0.2.1...v0.2.2

package/README.en.md

@@ -0,0 +1,256 @@
+# pi-one-ui
+
+[![npm version](https://img.shields.io/npm/v/pi-one-ui?style=flat-square)](https://www.npmjs.com/package/pi-one-ui)
+[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A522.19-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
+[![License](https://img.shields.io/github/license/kerolt/pi-one-ui?style=flat-square)](./LICENSE)
+
+[简体中文](./README.md) | English
+
+`pi-one-ui` is a unified TUI extension package for [Pi](https://pi.dev). It started as an effort to build a simple and polished terminal interface by combining, at the source level:
+
+- the terminal shell capabilities of [pi-zentui](https://github.com/lmilojevicc/pi-zentui)
+- the conversation rendering and productivity features of [pi-cc-extensions](https://github.com/minuque/pi-cc-extensions)
+
+The result is a single installable and configurable Pi package that continues to evolve through module refactoring, tighter ownership, and independent improvements.
+
+## Features
+
+### Unified interface layout
+
+`pi-one-ui` organizes the Pi interface into the following layouts:
+
+```text
+Header → Context → WorkingLine → Editor → Footer
+```
+
+- **Header**: startup information, logo, and shortcut hints.
+- **Context**: the conversation area, including user messages, assistant messages, thinking, tools, diffs, Markdown, and summaries.
+- **WorkingLine**: working state, spinner, token/thought/elapsed information, and turn summaries.
+- **Editor**: input editor, completion, metadata, Accent Rail, and Minimalist styles.
+- **Footer**: current directory, Git, runtime, token, cost, and extension status information.
+- **Overlay**: temporary interfaces such as the settings panel and Context Inspector, managed by a shared OverlayManager.
+
+### Built-in functionality
+
+| Feature | Description | Entry point |
+| --- | --- | --- |
+| Unified settings panel | Organizes settings by Header, Context, WorkingLine, Editor, Footer, and Features | `/oneui` |
+| Context Inspector | Shows context usage and previews the system prompt, memory, skills, tools, and messages | `/context` |
+| Session reference | Searches previous Pi sessions or SubAgents and injects their useful context | `@` completion |
+| Subagent autocomplete | Completes SubAgent names and delegation hints | `@` completion |
+| Tool / Diff renderer | Provides unified rendering for tool calls, results, collapsed content, and Edit/Write diffs | Automatic |
+| Subagent live renderer | Preserves pi-subagents' dedicated progress cards and keeps them out of generic tool groups | Automatic |
+| Markdown enhancement | Adds Mermaid, admonitions, URL linking, and related rendering improvements | Automatic |
+| Built-in themes | Provides CC Dark and CC Light themes | `/theme` |
+| Compatibility aliases | Optionally provides common command aliases | `/clear`, `/exit` |
+
+## Quick start
+
+### Requirements
+
+- Node.js `>=22.19.0`
+- Pi and related runtime packages `>=0.84.0`
+
+### Install from npm
+
+```bash
+pi install npm:pi-one-ui
+```
+
+### Install from GitHub
+
+```bash
+pi install git:github.com/kerolt/pi-one-ui
+```
+
+After installation, reload extensions in Pi:
+
+```text
+/reload
+```
+
+Then open the unified settings panel:
+
+```text
+/oneui
+```
+
+## Configuration
+
+The configuration file is located at:
+
+```text
+~/.pi/agent/pi-one-ui.json
+```
+
+Using the `/oneui` settings panel is recommended. The panel uses a top-centered layout, stays open while Editor enablement or style changes are applied, restores focus after Editor replacement, and restores the effective list value when persistence fails. The current configuration uses the v1 structure, for example:
+
+```json
+{
+  "version": 1,
+  "components": {
+    "editor": {
+      "enabled": true,
+      "style": "opencode"
+    },
+    "userMessages": {
+      "enabled": true,
+      "style": "framed"
+    },
+    "workingLine": {
+      "enabled": true
+    },
+    "footer": {
+      "style": "starship"
+    }
+  },
+  "renderer": {
+    "mode": "on",
+    "diffViewMode": "auto"
+  }
+}
+```
+
+Available layout and renderer options may change between versions, so prefer configuring them through `/oneui`.
+
+### Canonical configuration policy
+
+`pi-one-ui` reads and writes only:
+
+```text
+~/.pi/agent/pi-one-ui.json
+```
+
+It does not automatically read, merge, or migrate historical configuration files, and it does not parse legacy flat fields or old style identifiers. If the file does not exist, runtime defaults are used in memory. The file is created only after the first settings change through `/oneui`. All persisted changes use the current v1 `components` and `renderer` structure.
+
+## Upstream origins and project evolution
+
+`pi-one-ui` originally combined source from the following open-source projects. Many thanks to their maintainers and contributors for providing the initial foundation.
+
+| Upstream project | Capabilities incorporated into `pi-one-ui` | Reference baseline |
+| --- | --- | --- |
+| [pi-zentui](https://github.com/lmilojevicc/pi-zentui) | Starship-style Footer, Opencode-style Editor, layouts, and shell capabilities | v0.21.0, commit `5341b38` |
+| [pi-cc-extensions](https://github.com/minuque/pi-cc-extensions) | Claude Code-style Context renderer, Tool/Diff rendering, Context Inspector, and references | v0.8.67, commit `dba37e5` |
+
+Production code lives in `extensions/`. The project has since unified its entry point, configuration storage, lifecycle, layout ownership, overlays, and input routing. The current implementation is no longer equivalent to either upstream project and does not automatically track upstream changes.
+
+The upstream projects provided the original foundation. Continued development focuses on turning these capabilities into one coherent product with clear seams and sustainable maintenance.
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed module boundaries, event flow, and ownership conventions.
+
+## Local development
+
+### Clone the repository
+
+```bash
+git clone https://github.com/kerolt/pi-one-ui.git
+cd pi-one-ui
+npm install
+```
+
+Node.js `>=22.19.0` is required. If multiple Node.js versions are installed, switch to a compatible version first.
+
+### Run in development mode
+
+Start Pi directly with the current source:
+
+```bash
+npm run pi:dev
+```
+
+This is equivalent to:
+
+```bash
+pi --no-extensions -e ./extensions/index.ts
+```
+
+You can also install the current package as a local link:
+
+```bash
+npm run pi:install-local
+```
+
+After changing the source, run the following command in Pi:
+
+```text
+/reload
+```
+
+### Development commands
+
+| Command | Purpose |
+| --- | --- |
+| `npm install` | Install dependencies |
+| `npm run format` | Format source, tests, and configuration files |
+| `npm run check` | Check formatting and import organization |
+| `npm run fix` | Fix formatting and organize imports |
+| `npm run typecheck` | Run TypeScript type checking |
+| `npm test` | Run all tests with Vitest |
+| `npm run pack:check` | Preview the npm package contents |
+| `npm run verify` | Run Biome checks, type checking, and all tests |
+
+Before submitting changes, run at least:
+
+```bash
+npm run verify
+npm run pack:check
+```
+
+### Test organization
+
+All tests run through Vitest and are organized into domain directories:
+
+- `tests/config/`: canonical configuration, storage, and compatibility boundaries.
+- `tests/context/`: Context content, tools, diffs, thinking, and mouse interaction.
+- `tests/header/`, `tests/working-line/`, `tests/editor/`, and `tests/footer/`: Layout behavior and lifecycle coverage.
+- `tests/runtime/`, `tests/overlay/`, and `tests/integration/`: runtime infrastructure, overlays, and the composed entry point.
+- `tests/services/`: Git, runtime, project, session, and telemetry data.
+- `tests/shell/`: remaining layout lifecycle glue and standalone compatibility.
+- `tests/support/` and `tests/fixtures/`: shared test helpers and fixtures.
+
+Changes involving the TUI lifecycle should specifically cover reloads, session tree rebuilds, compaction, regular/fullscreen TUI modes, headless mode, overlays, and third-party patch ownership.
+
+## Releases
+
+User-visible changes and upgrade notes are maintained in [CHANGELOG.md](./CHANGELOG.md). Changes under development belong in `Unreleased` and are moved to a versioned section only during a release.
+
+The project uses GitHub Actions for continuous integration and npm publishing:
+
+- [`.github/workflows/ci.yml`](./.github/workflows/ci.yml) runs complete verification for pull requests and pushes to `main`.
+- [`.github/workflows/publish.yml`](./.github/workflows/publish.yml) publishes to npm when a `v*.*.*` tag is pushed.
+
+To publish a new version:
+
+```bash
+# Ensure main is checked out and up to date
+git switch main
+git pull --ff-only origin main
+
+# Run release checks
+npm ci
+npm run verify
+npm run pack:check
+
+# Select the SemVer increment
+npm version patch   # Backward-compatible fixes, for example 0.2.1 -> 0.2.2
+# npm version minor # New features or breaking changes while the project is on 0.x
+# npm version major # Breaking changes after a stable 1.x release
+
+# Push the release commit and tag
+git push origin main --follow-tags
+```
+
+After the tag is pushed, the publish workflow verifies that the tag matches `package.json`, runs the full verification suite again, and publishes the public package through npm Trusted Publishing with provenance. Published npm versions cannot be overwritten, so never reuse an existing version or tag.
+
+## Contributing
+
+GitHub issues and contributions are welcome. When submitting changes:
+
+1. Keep each commit focused on one primary purpose.
+2. Use a concise Conventional Commit message, for example `fix: prevent settings panel freeze after editor toggle`.
+3. Add or update tests for behavioral changes.
+4. Run `npm run verify` and `npm run pack:check` before submitting.
+
+## License
+
+This project is released under the [MIT License](./LICENSE).

package/README.md

@@ -4,6 +4,8 @@
 [![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A522.19-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
 [![License](https://img.shields.io/github/license/kerolt/pi-one-ui?style=flat-square)](./LICENSE)
 
+简体中文 | [English](./README.en.md)
+
 `pi-one-ui` 是一个面向 [Pi](https://pi.dev) 的统一 TUI 扩展包。项目的初衷是希望打造一个简单美观的 TUI 界面，最初通过源码级融合，将：
 
 - [pi-zentui](https://github.com/lmilojevicc/pi-zentui)`pi-zentui` 的终端外壳能力
@@ -37,6 +39,7 @@ Header → Context → WorkingLine → Editor → Footer
 | Session reference     | 搜索并注入历史 Pi session 或 SubAgent 的有效上下文                     | `@` 补全          |
 | Subagent autocomplete | 提供 SubAgent 名称补全和委派提示                                       | `@` 补全          |
 | Tool / Diff renderer  | 工具调用、结果、折叠内容和 Edit/Write diff 的统一展示                  | 自动生效          |
+| Subagent live renderer | 保留 pi-subagents 专用进度卡，并避免纳入通用工具分组                    | 自动生效          |
 | Markdown enhancement  | 支持 Mermaid、提示框和 URL 链接化等增强渲染                            | 自动生效          |
 | Built-in themes       | 提供 CC Dark 和 CC Light 主题                                          | `/theme`          |
 | Compatibility aliases | 可选提供常用命令别名                                                   | `/clear`、`/exit` |
@@ -80,7 +83,7 @@ pi install git:github.com/kerolt/pi-one-ui
 ~/.pi/agent/pi-one-ui.json
 ```
 
-推荐通过 `/oneui` 设置面板修改配置。当前配置仍使用 v1 结构，例如：
+推荐通过 `/oneui` 设置面板修改配置。面板采用更靠近顶部的居中布局；切换 Editor 启用状态或样式时会保持打开并在 Editor 替换后恢复焦点，持久化失败时则恢复列表中的有效旧值。当前配置仍使用 v1 结构，例如：
 
 ```json
 {
@@ -103,25 +106,22 @@ pi install git:github.com/kerolt/pi-one-ui
   },
   "renderer": {
     "mode": "on",
-    "diffViewMode": "auto",
-    "enableWorkingMessage": false
+    "diffViewMode": "auto"
   }
 }
 ```
 
 不同布局和渲染器的可用选项会随版本变化，建议优先使用 `/oneui` 面板进行配置。
 
-### 配置迁移与兼容
+### Canonical 配置约定
 
-`pi-one-ui` 通过统一的 `ConfigStore` 读取和写入配置，并兼容读取以下历史配置文件：
+`pi-one-ui` 只读取和写入：
 
 ```text
-~/.pi/agent/zentui.json
-~/.pi/agent/claude-code-style.json
-~/.pi/agent/pi-mine-ui.json
+~/.pi/agent/pi-one-ui.json
 ```
 
-历史配置只作为兼容输入；新的配置写入统一使用 `pi-one-ui.json`。`enableWorkingMessage` 仍可以从旧配置中读取，但统一运行时不会注册第二套 Working Message 实现，WorkingLine 是该 UI seam 的唯一 owner。
+不会自动读取、合并或迁移其他历史配置文件，也不会解析旧版扁平字段和旧 style 名称。配置文件不存在时，运行时直接使用内置默认值；首次通过 `/oneui` 修改设置时才创建文件。所有持久化修改统一写入当前 v1 的 `components` 和 `renderer` 结构。
 
 ## 上游来源与项目演进
 
@@ -182,14 +182,12 @@ npm run pi:install-local
 | ---------------------- | ---------------------------------- |
 | `npm install`          | 安装依赖                           |
 | `npm run format`       | 格式化源码、测试和配置文件         |
-| `npm run format:check` | 检查格式但不修改文件               |
-| `npm run lint`         | 运行 Biome 检查                    |
+| `npm run check`        | 检查格式和 import organization     |
+| `npm run fix`          | 修复格式并整理 imports             |
 | `npm run typecheck`    | 执行 TypeScript 类型检查           |
-| `npm test`             | 运行全部测试                       |
-| `npm run test:node`    | 运行 Node.js test runner 测试      |
-| `npm run test:vitest`  | 运行 Vitest 测试                   |
+| `npm test`             | 使用 Vitest 运行全部测试           |
 | `npm run pack:check`   | 预览 npm 实际打包内容              |
-| `npm run verify`       | 执行格式、lint、类型检查和全部测试 |
+| `npm run verify`       | 执行 Biome check、类型检查和全部测试 |
 
 提交修改前建议至少运行：
 
@@ -200,19 +198,22 @@ npm run pack:check
 
 ### 测试组织
 
-测试按照功能领域划分：
+所有测试统一由 Vitest 执行，并按照功能领域组织在子目录中：
 
-- `tests/context-*`：Context 内容区、Tool、Diff、Thinking 和鼠标交互。
-- `tests/working-line-*`：WorkingLine 和 turn summary。
-- `tests/editor-*`：Editor、completion、metadata、transfer 和 Accent Rail。
-- `tests/footer-*`：Footer、Footer format/layout/status。
-- `tests/services-*`：Git、runtime、project、session 和 telemetry。
-- `tests/shell-*`：剩余布局生命周期 glue 和 standalone compatibility。
+- `tests/config/`：canonical 配置、存储和兼容性边界。
+- `tests/context/`：Context 内容区、Tool、Diff、Thinking 和鼠标交互。
+- `tests/header/`、`tests/working-line/`、`tests/editor/`、`tests/footer/`：各 Layout 的行为和生命周期。
+- `tests/runtime/`、`tests/overlay/`、`tests/integration/`：运行时基础设施、Overlay 和组合入口。
+- `tests/services/`：Git、runtime、project、session 和 telemetry。
+- `tests/shell/`：剩余布局生命周期 glue 和 standalone compatibility。
+- `tests/support/`、`tests/fixtures/`：共享测试工具和 fixtures。
 
 涉及 TUI 生命周期的修改，应特别覆盖 reload、session tree rebuild、compact、regular/fullscreen TUI、headless mode、overlay 和第三方 patch ownership 等场景。
 
 ## 发布
 
+用户可见变更和升级说明统一记录在 [CHANGELOG.md](./CHANGELOG.md)。开发中的变更先写入 `Unreleased`，正式发版时再归档到对应版本。
+
 项目使用 GitHub Actions 进行持续集成和 npm 发布：
 
 - [`.github/workflows/ci.yml`](./.github/workflows/ci.yml)：在 Pull Request 和 `main` 分支提交时执行完整验证。
@@ -231,9 +232,9 @@ npm run verify
 npm run pack:check
 
 # 按 SemVer 升级版本
-npm version patch   # Bug 修复，例如 0.2.1 -> 0.2.2
-# npm version minor # 新增兼容功能
-# npm version major # 破坏性变更
+npm version patch   # 向后兼容的修复，例如 0.2.1 -> 0.2.2
+# npm version minor # 0.x 阶段的新功能或破坏性变更
+# npm version major # 进入稳定 1.x 后的破坏性变更
 
 # 推送版本 commit 和 tag
 git push origin main --follow-tags

package/extensions/app/commands/settings-previews.ts

@@ -1,12 +1,12 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { renderUserMessageStyle } from "../../layouts/context/message/user-message-styles.ts";
 import { renderAccentRailEditorFrame } from "../../layouts/editor/accent-rail-editor.ts";
-import type { PolishedTuiConfig } from "../config/shell.ts";
 import { sanitizeEditorMetadataText } from "../../layouts/editor/editor-metadata-format.ts";
 import { renderMinimalistFrame } from "../../layouts/editor/minimalist-editor.ts";
-import { safeThemeFg } from "../../shared/style.ts";
 import { renderPolishedEditorFrame } from "../../layouts/editor/ui.ts";
-import { renderUserMessageStyle } from "../../layouts/context/message/user-message-styles.ts";
+import { safeThemeFg } from "../../shared/style.ts";
+import type { PolishedTuiConfig } from "../config/shell.ts";
 
 export const SETTINGS_PREVIEW_MAX_WIDTH = 72;
 export const SETTINGS_PREVIEW_MAX_ROWS = 10;

package/extensions/app/config/renderer.ts

@@ -1,5 +1,5 @@
 import type { CompactThinkingConfig } from "../../layouts/context/thinking/compact-thinking.ts";
-import { configStore, type ConfigRecord } from "./store.ts";
+import { type ConfigRecord, configStore } from "./store.ts";
 
 export type CompactStyleMode = "on" | "compact" | "off";
 
@@ -61,7 +61,6 @@ export type Config = {
   enableSubagentAutocomplete: boolean;
   enableContextCommand: boolean;
   enableAgentSummary: boolean;
-  enableWorkingMessage: boolean;
   enableAliases: boolean;
 };
 
@@ -69,7 +68,7 @@ function rendererConfigFrom(record: ConfigRecord): ConfigRecord {
   const renderer = record.renderer;
   return renderer && typeof renderer === "object" && !Array.isArray(renderer)
     ? (renderer as ConfigRecord)
-    : record;
+    : {};
 }
 
 export const DIFF_VIEW_MODES: DiffViewMode[] = ["auto", "split", "unified"];
@@ -166,8 +165,6 @@ export const DEFAULT_CONFIG: Config = {
   enableSubagentAutocomplete: true,
   enableContextCommand: true,
   enableAgentSummary: true,
-  // Zentui is the sole owner of Pi's unkeyed working row in pi-one-ui.
-  enableWorkingMessage: false,
   enableAliases: true,
 };
 
@@ -218,15 +215,8 @@ export function normalizeConfig(input: unknown): Config {
     unknown
   >;
   const mode = source.mode;
-  // 旧 `enabled: boolean` 配置迁移；compact 已恢复为受支持模式，不再回退 on。
-  const migratedMode: CompactStyleMode =
-    mode === "on" || mode === "compact" || mode === "off"
-      ? mode
-      : typeof source.enabled === "boolean"
-        ? source.enabled
-          ? "on"
-          : "off"
-        : "on";
+  const normalizedMode: CompactStyleMode =
+    mode === "on" || mode === "compact" || mode === "off" ? mode : "on";
   const excludeRenderers = Array.isArray(source.excludeRenderers)
     ? [
         ...new Set(
@@ -238,7 +228,7 @@ export function normalizeConfig(input: unknown): Config {
       ]
     : [];
   return {
-    mode: migratedMode,
+    mode: normalizedMode,
     excludeRenderers,
     diffViewMode: pickEnum(
       source.diffViewMode,
@@ -257,7 +247,7 @@ export function normalizeConfig(input: unknown): Config {
       300,
     ),
     editDiffCollapsedLines: pickPositiveInt(
-      source.editDiffCollapsedLines ?? source.diffCollapsedLines,
+      source.editDiffCollapsedLines,
       DEFAULT_CONFIG.editDiffCollapsedLines,
       1,
       500,
@@ -305,7 +295,6 @@ export function normalizeConfig(input: unknown): Config {
     enableSubagentAutocomplete: source.enableSubagentAutocomplete !== false,
     enableContextCommand: source.enableContextCommand !== false,
     enableAgentSummary: source.enableAgentSummary !== false,
-    enableWorkingMessage: source.enableWorkingMessage === true,
     enableAliases: source.enableAliases !== false,
   };
 }
@@ -360,7 +349,6 @@ export function formatConfigStatus(source: Config = config): string {
     `subagentAuto=${source.enableSubagentAutocomplete ? "on" : "off"}`,
     `context=${source.enableContextCommand ? "on" : "off"}`,
     `agentSummary=${source.enableAgentSummary ? "on" : "off"}`,
-    `workingMsg=${source.enableWorkingMessage ? "on" : "off"}`,
     `aliases=${source.enableAliases ? "on" : "off"}`,
   ].join(" · ");
 }
@@ -383,17 +371,18 @@ function loadConfig(): Config {
 /**
  * Persists the in-memory renderer projection through the shared store.
  */
-export function saveConfig() {
+export function saveConfig(next: Config = config) {
   configStore.update((record) => {
     record.version = 1;
-    record.renderer = config;
+    record.renderer = next;
   });
 }
 
-/** 运行时配置写入的唯一入口：合并 + 规范化 + 持久化。 */
+/** 运行时配置写入的唯一入口：规范化并持久化成功后再提交到活动配置。 */
 export function updateConfig(partial: Partial<Config>): void {
-  Object.assign(config, normalizeConfig({ ...config, ...partial }));
-  saveConfig();
+  const next = normalizeConfig({ ...config, ...partial });
+  saveConfig(next);
+  Object.assign(config, next);
 }
 
 /** 整体替换配置（default export 的 configOverride 注入路径；就地覆盖，不持久化）。 */