pi-one-ui 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# 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.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.0...HEAD
+[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 |
+| 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 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 format:check` | Check formatting without modifying files |
+| `npm run lint` | Run Biome checks |
+| `npm run typecheck` | Run TypeScript type checking |
+| `npm test` | Run all tests |
+| `npm run test:node` | Run Node.js test runner tests |
+| `npm run test:vitest` | Run Vitest tests |
+| `npm run pack:check` | Preview the npm package contents |
+| `npm run verify` | Run formatting, lint, type checking, and all tests |
+
+Before submitting changes, run at least:
+
+```bash
+npm run verify
+npm run pack:check
+```
+
+### Test organization
+
+Tests are grouped by domain:
+
+- `tests/context-*`: Context content, tools, diffs, thinking, and mouse interaction.
+- `tests/working-line-*`: WorkingLine and turn summaries.
+- `tests/editor-*`: Editor, completion, metadata, transfer, and Accent Rail.
+- `tests/footer-*`: Footer rendering, formatting, layout, and status.
+- `tests/services-*`: Git, runtime, project, session, and telemetry data.
+- `tests/shell-*`: Remaining layout lifecycle glue and standalone compatibility.
+
+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` 的终端外壳能力
@@ -103,25 +105,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` 结构。
 
 ## 上游来源与项目演进
 
@@ -213,6 +212,8 @@ npm run pack:check
 
 ## 发布
 
+用户可见变更和升级说明统一记录在 [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/config/renderer.ts

@@ -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(" · ");
 }