@muzi3/pi-ui 0.1.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 muzi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+The bundled theme `themes/pi-ui-mocha.json` is derived from the Catppuccin Mocha palette:
+
+- Catppuccin — MIT, https://github.com/catppuccin/catppuccin
+- Catppuccin color values as laid out by the pi theme "catppuccin-tui-mocha" — MIT

package/README.md

@@ -0,0 +1,127 @@
+# @muzi3/pi-ui
+
+Pi 扩展：把页脚换成四行上下文仪表盘，并在编辑器边框上常驻显示模型名与耗时，主题跟着当前主题走。
+
+替代 `pi-catppuccin-tui` 的自实现版本，修掉了原实现的两处问题：指示器颜色和多处 token 写死了 Macchiato
+的十六进制色（换主题后错色），以及自定义 footer 整体替换内置 footer 后、其他扩展的 `setStatus` 状态
+（如 `@muzi3/comate-quota` 的额度）变得不可见。
+
+## 能力
+
+| 能力 | 说明 |
+|------|------|
+| `footer` | 四行仪表盘页脚，两条进度条置顶，替换内置 footer |
+| `indicator` | 闪烁帧 `· • ● ● • ·` @120ms，颜色取自主题 token；关掉后不显示呼吸灯（内置指示器回退为 pi 默认） |
+| `working` | 编辑器边框上常驻显示模型名与耗时，是否在生成只由呼吸灯表达 |
+
+### footer 布局
+
+```
+Comate  ████░░░░░░░░░░  25% / ¥50.00    main
+Context ██░░░░░░░░░░░░  1.7% / 272k  ↑74.7k ↓3.8k $0.009
+```
+
+- 第 1 行：其他扩展通过 `setStatus` 设置的文本（如 `@muzi3/comate-quota` 的额度条）+ git 分支。
+  分支前是 Nerd Font 的 git 图标 `U+E0A0`（nf-pl-branch，与 starship 默认提示符同一字形，
+  `accent` 色），**需要 Nerd Font 字体**，否则显示为豆腐块；分支名本身为 `muted`
+- 第 2 行：上下文进度条（14 格）+ `百分比 / 窗口` + 累计用量（`↑in ↓out $cost`）。
+  进度条配色按占用率分级：`<70%` 绿（`success`）、`70~90%` 黄（`warning`）、`>90%` 红（`error`）；
+  刚压缩完占用未知时显示为暗色 `?`
+- 第 1、2 行的标签列固定 8 列（`Comate  ` / `Context `，含标签后的分隔空格），两条进度条因此左对齐。
+  `Context ` 由本包补齐；扩展状态行是别的包产出的文本，要自己把标签补齐到 8 列
+  （参考 `@muzi3/comate-quota`）——这是跨包视觉契约
+- 行尾的分支与累计用量是次要信息，放不下就整段丢弃（不截断），进度条与百分比不参与降级
+- footer 高度不超过 2 行：没装扩展就没有额度条，不在 git 仓库就没有分支
+- 内核 footer 右侧的“模型名 • 思考等级”两项都不要：模型名在编辑器边框上常驻，思考等级由边框
+  颜色区分（每个等级一个 `thinking*` token，主题里已拉开层次）
+- 累计用量口径与内置 footer 一致：assistant、带 usage 的 toolResult、branch_summary/compaction 求和
+
+### 编辑器边框标题
+
+```
+── claude-sonnet-4-5  ⏱ 12s ────────────────────────────────  空闲
+── ● claude-sonnet-4-5  ⏱ 12s ──────────────────────────────  流式
+ > 
+────────────────────────────────────────────────────────────────────────
+```
+
+- 用自定义编辑器（`PiUiBorderEditor extends CustomEditor`）接管编辑器上边框。pi 自带的
+  `WorkingStatusIndicator` 只在流式期间挂在边框上（`turn_start` 挂、`turn_end` 清），空闲即消失，
+  承载不了“常驻”；所以子类覆写 `setWorkingStatusIndicator`，忽略 pi 的挂/清，恒挂自己的标题。
+  边框拼接、截断、`↑ N more` 滚动提示全部沿用 `CustomEditor.renderTopBorder`，没有重写排版
+- 输入被滚动时不用取舍：`↑ N more` 会与标题并列出现在同一行边框上
+  （`── ● model ⏱ 12s ──── ↑ 5 more ────`），这是继承来的行为，不是额外实现
+- 呼吸灯：流式为 `· • ● ● • ·` @120ms（颜色按主题 token 递进）。不闪的时候完全不显示——空闲、
+  或关掉 `indicator` 时都不留静止的点（静止的点反而更难看出在不在生成）；代价是模型名会左右
+  移 2 列，在以 `─` 为主的边框上几乎看不出来
+- 耗时口径与旧版 footer 一致，只是位置变了：流式为已进行秒数（随呼吸灯帧重绘跳秒），
+  空闲为上一轮总耗时；宽度不足时先丢掉 `⏱ 耗时`，再逐字截断模型名
+- 退出/关闭 `working` 会换回内置编辑器，还原 pi 默认：仅流式期间在边框显示模型名
+- 需要 pi `>= 0.85`（`CustomEditor` 的 `embedWorkingStatus` 与 `setWorkingStatusIndicator` 从该版本才有）；
+  本包不依赖 `@earendil-works/pi-coding-agent` 的本地副本，运行时由 pi 的扩展加载器别名到自身
+
+### 模型名覆盖（跨扩展）
+
+边框标题默认显示当前会话模型，其他扩展可以在自己占用会话期间临时把它换掉：
+
+```typescript
+pi.events.emit("pi-ui:model-override", "glm-4.6"); // 覆盖
+pi.events.emit("pi-ui:model-override", undefined); // 恢复会话模型
+```
+
+通道是软约定：没扩展发布时什么都不发生，空串与 `undefined` 都表示恢复，
+`session_start`/`session_shutdown` 会清空残留值。`@muzi3/compaction-custom-model`
+靠它在压缩期间显示压缩所用模型。
+
+### 宽度不足时的降级顺序
+
+自定义 footer 会整体接管内置 footer，内置第三行（扩展状态）随之消失，所以扩展状态置于页脚最前。
+两行各自独立降级，每行都保住它最有信息量的部分：
+1. 第 1 行：完整（额度条 + 分支）→ 丢分支 → 额度条截断加省略号
+2. 第 2 行：完整（进度条 + 计数 + 累计用量）→ 丢累计用量 → 丢 `Context ` 标签 → 丢百分比/窗口
+   → 只剩进度条；进度条不接受被截断
+
+## 命令
+
+```
+/pi-ui                                  # 查看三块能力的开关状态
+/pi-ui footer|indicator|working on|off  # 单独开关
+```
+
+关闭 `footer` 会恢复 pi 内置 footer；关闭 `working` 会换回内置编辑器（流式期间才显示模型名）；关闭
+`indicator` 会让呼吸灯不再显示。开关只在本次会话内有效，不写盘。
+
+## 主题
+
+`themes/pi-ui-catppuccin.json`（主题名 `pi-ui-catppuccin`）在 Catppuccin Mocha 基础上只改层次关系，
+色板本身不变：
+
+| token | 原值 | 现值 | 原因 |
+|-------|------|------|------|
+| `toolErrorBg` | `surface0` | `redBg` `#493446` | 原来与 `toolSuccessBg` 同为 `surface0`，成功/失败的工具块看不出区别。Catppuccin 没有暗红底色，`#493446` 是在 `base` 上叠 20% `red` 得到的 |
+| `selectedBg` | `surface0` | `surface1` | 原来与 `userMessageBg` 同色，选中行在列表里几乎不可见 |
+| `searchMatchBg` | 未定义（回落 `selectedBg`） | `surface2` | 搜索命中需要比选中行更强的对比 |
+| `searchMatchText` | 未定义（回落 `text`） | `text` | 显式写出，避免跟随 `selectedBg` 改动漂移 |
+| `scrollbarTrack` | 未定义（回落 `muted`） | `surface0` | 全屏模式下滚动条轨道应当几乎不可见 |
+| `scrollbarThumb` | 未定义（回落 `text`） | `overlay0` | 滑块比轨道亮，但不该抢正文 |
+| `mdCodeBlockBorder` | `surface2` | `surface1` | 与主 `border` 同级时，代码块外框噪音过大 |
+| `mdQuoteBorder` | `surface2` | `surface1` | 同上，引用属于次要结构 |
+| `mdHeading` | `mauve` | `lavender` | `mauve` 同时是 `accent`/`mdListBullet`/`syntaxKeyword`/`thinkingHigh`，标题再占用就分不出主次 |
+| `mdListBullet` | `mauve` | `overlay2` | 列表符号属于次要装饰，降为灰色 |
+| `thinkingXhigh` | `red` | `maroon` | 给 `thinkingMax` 让出 `red`，形成 `mauve → maroon → red` 的递进 |
+| `thinkingMax` | 未定义 | `red` | 补上最高档，取代回落的默认色 |
+
+色板与配色思路来自 Catppuccin（MIT）与 pi 主题 `catppuccin-tui-mocha`（MIT）。
+
+## 安装
+
+```bash
+pi install npm:@muzi3/pi-ui
+```
+
+从 `pi-catppuccin-tui` 迁移时，先装本包、把 `~/.pi/agent/settings.json` 的 `theme` 改成 `pi-ui-catppuccin`，
+再卸载前者。两个包都会调用 `setFooter`，后加载者生效，顺序不确定；先卸载可避免页脚互相覆盖。
+
+## 敏感信息
+
+本包不含个人信息、内部工具名与任何凭证。发布前扫描见仓库根 `.pi/RULES.md`。

package/extensions/border-editor.ts

@@ -0,0 +1,158 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { CustomEditor } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth, type TUI } from "@earendil-works/pi-tui";
+import { buildPulseFrames, PULSE_INTERVAL_MS } from "./indicator.ts";
+
+export function formatDuration(seconds: number): string {
+	const total = Math.max(0, Math.floor(seconds));
+	if (total < 60) return `${total}s`;
+	return `${Math.floor(total / 60)}m${total % 60}s`;
+}
+
+/** 边框标题的数据来源，由入口注入，使组件不依赖 ExtensionContext。 */
+export type EditorTitleInputs = {
+	/** 边框上显示的模型名；调用方可以整体替换（如压缩期间换成压缩所用模型）。 */
+	getModelId(): string | undefined;
+	/** 流式中为已进行秒数，空闲时为上一轮耗时秒数，无数据为 undefined。 */
+	getTimerSeconds(): number | undefined;
+	isStreaming(): boolean;
+	/** 关掉后不显示呼吸灯（而不是停在静止帧）。 */
+	isPulseEnabled(): boolean;
+	/** 编辑器主题（getEditorTheme）只有 borderColor/selectList，配色要另取实时主题。 */
+	getTheme(): Theme;
+};
+
+/**
+ * CustomEditor.renderTopBorder 只调用这两个方法，所以标题不必是 pi 的
+ * WorkingStatusIndicator 类型，只要有同样的形状即可。
+ */
+type BorderTitle = {
+	renderInBorder(width: number): string;
+	renderSpinnerInBorder(width: number): string;
+};
+
+/**
+ * 编辑器边框上的常驻标题：`<呼吸灯> <模型名>  ⏱ 耗时`，空闲时也在（呼吸灯不闪则不显示）。
+ *
+ * 帧由自己按时间算，流式时用定时器驱动重绘（pi 的 WorkingStatusIndicator 靠 Loader 同理）。
+ */
+class PiUiBorderTitle implements BorderTitle {
+	private readonly tui: TUI;
+	private readonly inputs: EditorTitleInputs;
+	private ticker: ReturnType<typeof setInterval> | undefined;
+	private framesKey: string | undefined;
+	private frames: string[] = [];
+
+	constructor(tui: TUI, inputs: EditorTitleInputs) {
+		this.tui = tui;
+		this.inputs = inputs;
+	}
+
+	/** 状态或模型变化后调用：立即重绘，并按是否流式启停呼吸灯。 */
+	sync(): void {
+		if (this.inputs.isStreaming()) {
+			if (!this.ticker) {
+				this.ticker = setInterval(() => this.tui.requestRender(), PULSE_INTERVAL_MS);
+			}
+		} else {
+			this.stop();
+		}
+		this.tui.requestRender();
+	}
+
+	dispose(): void {
+		this.stop();
+	}
+
+	/** 标题主体。与边框的拼接、截断由外层 renderTopBorder 负责，这里只要不超过 width。 */
+	renderInBorder(width: number): string {
+		const theme = this.inputs.getTheme();
+		const model = this.inputs.getModelId();
+		const pulse = this.renderPulse(theme);
+
+		// 不闪的时候不占位：留一个静止的点比没有更难看出在不在生成。
+		const parts: string[] = [];
+		if (pulse !== undefined) parts.push(pulse);
+		if (model !== undefined) parts.push(theme.fg("text", model));
+		const head = parts.join(" ");
+
+		const seconds = this.inputs.getTimerSeconds();
+		// 耗时是给模型名做注脚的：没有标题就不单独出现（否则会多出空档）。
+		if (head !== "" && seconds !== undefined) {
+			// 宽度不足时先丢耗时：模型名是这一行的目的，耗时是附带的。
+			const timer = theme.fg("dim", `⏱ ${formatDuration(seconds)}`);
+			if (visibleWidth(head) + 2 + visibleWidth(timer) <= width) return `${head}  ${timer}`;
+		}
+		return truncateToWidth(head, width, "");
+	}
+
+	/** 边框窄到放不下标题时只留呼吸灯；不闪时交给外层画普通边框。 */
+	renderSpinnerInBorder(width: number): string {
+		const pulse = this.renderPulse(this.inputs.getTheme());
+		return pulse === undefined ? "" : truncateToWidth(pulse, width, "");
+	}
+
+	private stop(): void {
+		if (this.ticker) {
+			clearInterval(this.ticker);
+			this.ticker = undefined;
+		}
+	}
+
+	/** 帧是构建期快照（theme.fg 在此刻求值），这里按主题名缓存，换主题自动重建。 */
+	private currentFrames(theme: Theme): string[] {
+		if (theme.name !== this.framesKey) {
+			this.framesKey = theme.name;
+			this.frames = buildPulseFrames(theme);
+		}
+		return this.frames;
+	}
+
+	/** 流式时按时间取帧（与定时器同频，无需自增索引）；不闪时返回 undefined，即完全不显示。 */
+	private renderPulse(theme: Theme): string | undefined {
+		if (!this.inputs.isPulseEnabled() || !this.inputs.isStreaming()) return undefined;
+		const frames = this.currentFrames(theme);
+		return frames[Math.floor(Date.now() / PULSE_INTERVAL_MS) % frames.length];
+	}
+}
+
+type EditorArgs = ConstructorParameters<typeof CustomEditor>;
+type IndicatorSlot = Parameters<CustomEditor["setWorkingStatusIndicator"]>[0];
+
+/**
+ * 把模型名与耗时做成编辑器边框上的常驻标题。
+ *
+ * pi 的 WorkingStatusIndicator 只在流式期间挂在边框上（turn_start 挂、turn_end 清），
+ * 空闲即消失，承载不了"常驻"。这里覆写 setWorkingStatusIndicator，忽略 pi 的挂/清，
+ * 恒挂自己的标题；边框拼接、截断、多行溢出标签全部沿用 CustomEditor。
+ * 重试/压缩等非 working 指示器走 statusContainer 独立行，不经过这里，不受影响。
+ */
+export class PiUiBorderEditor extends CustomEditor {
+	private readonly title: PiUiBorderTitle;
+
+	constructor(tui: EditorArgs[0], theme: EditorArgs[1], keybindings: EditorArgs[2], inputs: EditorTitleInputs) {
+		super(tui, theme, keybindings, { embedWorkingStatus: true });
+		this.title = new PiUiBorderTitle(tui, inputs);
+		this.attachTitle();
+	}
+
+	/** pi 每次 turn_start/turn_end 都会重设指示器，这里一律换成常驻标题。 */
+	setWorkingStatusIndicator(_indicator?: IndicatorSlot): void {
+		this.attachTitle();
+	}
+
+	/** 状态或模型变化后由入口调用。 */
+	sync(): void {
+		this.title.sync();
+	}
+
+	/** 停掉呼吸灯定时器；pi 切换编辑器时不会调用，入口在 shutdown/关闭特性时调用。 */
+	dispose(): void {
+		this.title.dispose();
+	}
+
+	private attachTitle(): void {
+		// 标题只有 renderInBorder/renderSpinnerInBorder，用类型断言补足 pi 的指示器类型。
+		super.setWorkingStatusIndicator(this.title as unknown as IndicatorSlot);
+	}
+}

package/extensions/context-bar.ts

@@ -0,0 +1,29 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+
+/** 进度条总格数。 */
+export const CONTEXT_BAR_CELLS = 14;
+
+const FILLED = "█";
+const EMPTY = "░";
+
+/**
+ * 上下文占用率的语义色。阈值与内置 footer 对齐（>70% 警告，>90% 错误），
+ * 正常档位用 success 而非 accent，让进度条读起来像仪表而不是装饰。
+ * percent 为 null 表示刚压缩完、占用未知。
+ */
+export function contextColor(percent: number | null): ThemeColor {
+	if (percent === null) return "dim";
+	if (percent > 90) return "error";
+	if (percent > 70) return "warning";
+	return "success";
+}
+
+/**
+ * 渲染固定宽度进度条。非零占用至少填一格，否则 1.7% 这类低占用会渲染成全空条，
+ * 看起来像数据缺失而不是"还早"。
+ */
+export function renderContextBar(percent: number | null, cells: number = CONTEXT_BAR_CELLS): string {
+	const ratio = percent === null ? 0 : Math.min(1, Math.max(0, percent / 100));
+	const filled = ratio > 0 ? Math.max(1, Math.round(ratio * cells)) : 0;
+	return FILLED.repeat(filled) + EMPTY.repeat(cells - filled);
+}

package/extensions/footer.ts

@@ -0,0 +1,171 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth, type Component, type TUI } from "@earendil-works/pi-tui";
+import { contextColor, renderContextBar } from "./context-bar.ts";
+
+/**
+ * Nerd Font 的分支图标 U+E0A0（nf-pl-branch），与 starship 默认提示符同一字形。
+ * 宽度为 1 列，visibleWidth 能正确计算；无 Nerd Font 字体时会显示为豆腐块。
+ */
+const GIT_ICON = "\ue0a0";
+
+/**
+ * 第 1、2 行的标签列宽（含标签后的分隔空格），两条进度条靠它左对齐：`Comate  ` / `Context `。
+ * 第 1 行的标签由产出该状态的扩展自己补齐，这是跨包视觉契约。
+ */
+const LABEL_COLUMN = 8;
+
+/** 会话累计用量，口径与内置 footer 一致。 */
+export type UsageTotals = {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+};
+
+export function createUsageTotals(): UsageTotals {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+}
+
+/** footer 渲染所需的数据来源，由入口注入，使 footer 不依赖 ExtensionContext。 */
+export type FooterInputs = {
+	getContextUsage(): { percent: number | null; contextWindow: number } | undefined;
+	getUsageTotals(): UsageTotals;
+};
+
+/** footerData 的最小结构要求，避免依赖 pi 未公开导出的内部类型。 */
+export type FooterData = {
+	getGitBranch(): string | undefined;
+	getExtensionStatuses(): ReadonlyMap<string, string>;
+};
+
+/** 紧凑的 token 计数格式，与内置 footer 一致。 */
+export function formatTokens(count: number): string {
+	if (count < 1000) return count.toString();
+	if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+	if (count < 1000000) return `${Math.round(count / 1000)}k`;
+	if (count < 10000000) return `${(count / 1000000).toFixed(1)}M`;
+	return `${Math.round(count / 1000000)}M`;
+}
+
+/**
+ * 把扩展状态里的换行/制表符压成空格，避免撑破 footer 行数。
+ * 不动连续空格：第 1、2 行的标签列靠补齐空格对齐，压掉就错位了。
+ */
+function sanitizeStatusText(text: string): string {
+	return text.replace(/[\r\n\t]+/g, " ").trim();
+}
+
+/**
+ * 双行仪表盘 footer，两条进度条置顶。
+ *
+ * 第 1 行：扩展 status 文本（`@muzi3/comate-quota` 的额度条）+ git 分支
+ * 第 2 行：上下文进度条（`Context` 标签 + 14 格条 + 百分比/窗口）+ 累计用量
+ *
+ * 自定义 footer 会整体替换内置 footer，内置第 3 行的扩展状态会跟着消失，所以扩展状态置于最前。
+ * 第 1、2 行都是“标签 + 14 格条 + 计数”，需要对齐，因此约定标签列宽 LABEL_COLUMN：`Context`
+ * 由这里补齐，扩展状态行的标签由各自补齐。行尾的分支与累计用量是次要信息，宽度不足时整段丢掉。
+ *
+ * 空行会被丢掉（没装扩展就没有额度条、不在 git 仓库就没有分支），footer 高度不超过 2 行。
+ *
+ * 内置 footer 右侧会显示“模型名 • 思考等级”，这里两者都不要：模型名在编辑器边框上
+ * 常驻，思考等级由边框颜色区分（每个等级一个 thinking* token）。
+ */
+export class PiUiFooter implements Component {
+	private readonly theme: Theme;
+	private readonly data: FooterData;
+	private readonly inputs: FooterInputs;
+
+	/** `tui` 是 Component factory 签名的一部分，本组件纯函数式渲染，无需持有。 */
+	constructor(_tui: TUI, theme: Theme, data: FooterData, inputs: FooterInputs) {
+		this.theme = theme;
+		this.data = data;
+		this.inputs = inputs;
+	}
+
+	/** 数据都由 inputs 实时读取，无需缓存失效。 */
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		return [this.renderQuotaLine(width), this.renderContextLine(width)].filter(
+			(line) => visibleWidth(line) > 0,
+		);
+	}
+
+	/** 第 1 行：扩展 status 文本 + git 分支。 */
+	private renderQuotaLine(width: number): string {
+		const statuses = this.collectStatuses();
+		const branch = this.renderBranch();
+		if (!statuses) return truncateToWidth(branch, width, "");
+
+		const full = branch ? `${statuses}  ${branch}` : statuses;
+		if (visibleWidth(full) <= width) return full;
+
+		// 进度条是这一行的目的，分支是次要信息：放不下就整段丢掉，不截断。
+		return truncateToWidth(statuses, width, this.dim("…"));
+	}
+
+	/** git 分支，带 Nerd Font 图标；不在 git 仓库时为空串。 */
+	private renderBranch(): string {
+		const branch = this.data.getGitBranch();
+		if (!branch) return "";
+		// 图标用 accent（该主题下为 mauve）保持可扫读，分支名压低为 muted。
+		return `${this.theme.fg("accent", GIT_ICON)} ${this.theme.fg("muted", branch)}`;
+	}
+
+	/** 第 2 行：上下文进度条 + 累计用量，标签补齐到 LABEL_COLUMN 与上一行左对齐。 */
+	private renderContextLine(width: number): string {
+		const theme = this.theme;
+		const stats = this.renderUsageStats();
+		const usage = this.inputs.getContextUsage();
+		if (!usage) return truncateToWidth(stats, width, "");
+
+		const color = contextColor(usage.percent);
+		const gauge = theme.fg(color, renderContextBar(usage.percent));
+		const counter = theme.fg(
+			color,
+			usage.percent === null
+				? `? / ${formatTokens(usage.contextWindow)}`
+				: `${usage.percent.toFixed(1)}% / ${formatTokens(usage.contextWindow)}`,
+		);
+		// 标签自带补位空格，不能再走 join("  ")，否则进度条起点比第 1 行右移 2 列。
+		const labeled = `${theme.fg("dim", "Context".padEnd(LABEL_COLUMN, " "))}${gauge}`;
+
+		// 变窄时依次丢累计用量、丢标签、丢计数器；进度条与百分比是这一行的目的，不接受被截断。
+		const candidates = [
+			[labeled, counter, stats],
+			[labeled, counter],
+			[gauge, counter],
+			[gauge],
+		];
+		for (const parts of candidates) {
+			const text = parts.filter(Boolean).join("  ");
+			if (visibleWidth(text) <= width) return text;
+		}
+		return truncateToWidth(gauge, width, "");
+	}
+
+	/** 会话累计用量；本轮还没发生用量时为空串。 */
+	private renderUsageStats(): string {
+		const totals = this.inputs.getUsageTotals();
+		const stats: string[] = [];
+		if (totals.input) stats.push(`↑${formatTokens(totals.input)}`);
+		if (totals.output) stats.push(`↓${formatTokens(totals.output)}`);
+		if (totals.cost) stats.push(`$${totals.cost.toFixed(3)}`);
+		return this.dim(stats.join(" "));
+	}
+
+	/** 暗色包裹；空串原样返回，避免产生只有 ANSI 码、宽度为 0 的“隐形”内容。 */
+	private dim(text: string): string {
+		return text ? this.theme.fg("dim", text) : "";
+	}
+
+	/** 其他扩展通过 setStatus 设置的状态，按 key 排序后连接。 */
+	private collectStatuses(): string {
+		return Array.from(this.data.getExtensionStatuses().entries())
+			.sort(([a], [b]) => a.localeCompare(b))
+			.map(([, text]) => sanitizeStatusText(text))
+			.filter((text) => text.length > 0)
+			.join("  ");
+	}
+}

package/extensions/index.ts

@@ -0,0 +1,211 @@
+import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { PiUiBorderEditor } from "./border-editor.ts";
+import { createUsageTotals, PiUiFooter, type UsageTotals } from "./footer.ts";
+import { buildPulseFrames, PULSE_INTERVAL_MS } from "./indicator.ts";
+
+/** 可单独开关的三块能力，值即为 /pi-ui 的子命令名。 */
+const FEATURES = ["footer", "indicator", "working"] as const;
+
+type Feature = (typeof FEATURES)[number];
+
+const COMMAND = "pi-ui";
+const USAGE = `用法：/${COMMAND} <footer|indicator|working> <on|off>`;
+
+function isFeature(value: string): value is Feature {
+	return (FEATURES as readonly string[]).includes(value);
+}
+
+type Usage = {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: { total: number };
+};
+
+function addUsage(totals: UsageTotals, usage: Usage): void {
+	totals.input += usage.input;
+	totals.output += usage.output;
+	totals.cacheRead += usage.cacheRead;
+	totals.cacheWrite += usage.cacheWrite;
+	totals.cost += usage.cost.total;
+}
+
+/** 累计用量口径与内置 footer 一致：assistant + toolResult + branch_summary/compaction。 */
+function totalsFromEntries(entries: SessionEntry[]): UsageTotals {
+	const totals = createUsageTotals();
+	for (const entry of entries) {
+		if (entry.type === "message" && entry.message.role === "assistant") {
+			addUsage(totals, entry.message.usage);
+		} else if (entry.type === "message" && entry.message.role === "toolResult" && entry.message.usage) {
+			addUsage(totals, entry.message.usage);
+		} else if ((entry.type === "branch_summary" || entry.type === "compaction") && entry.usage) {
+			addUsage(totals, entry.usage);
+		}
+	}
+	return totals;
+}
+
+export default function (pi: ExtensionAPI) {
+	const enabled: Record<Feature, boolean> = { footer: true, indicator: true, working: true };
+
+	/** 事件里的 ctx 会被新会话替换，footer 通过它读取实时数据，所以每收到事件就刷新引用。 */
+	let current: ExtensionContext | undefined;
+	let footer: PiUiFooter | undefined;
+	let borderEditor: PiUiBorderEditor | undefined;
+	let syncedTheme: string | undefined;
+
+	/** 其他扩展临时替换的边框模型名；undefined 表示用当前会话模型。 */
+	let modelOverride: string | undefined;
+
+	// agent_start → agent_settled 覆盖整轮（含工具调用与重试），空闲时保留上一轮耗时。
+	let turnStartedAt: number | undefined;
+	let lastTurnSeconds: number | undefined;
+
+	const timerSeconds = (): number | undefined =>
+		turnStartedAt === undefined ? lastTurnSeconds : (Date.now() - turnStartedAt) / 1000;
+
+	const installFooter = (ctx: ExtensionContext): void => {
+		ctx.ui.setFooter((tui, theme, footerData) => {
+			footer = new PiUiFooter(tui, theme, footerData, {
+				getContextUsage: () => current?.getContextUsage(),
+				getUsageTotals: () => totalsFromEntries(current?.sessionManager.getEntries() ?? []),
+			});
+			return footer;
+		});
+	};
+
+	const removeFooter = (ctx: ExtensionContext): void => {
+		ctx.ui.setFooter(undefined);
+		footer = undefined;
+	};
+
+	/**
+	 * 闪烁帧是构建期快照，换主题后不会自动更新；这里按主题名做一次惰性重建。
+	 * 边框标题自己按主题名缓存帧（见 PiUiBorderTitle.currentFrames），不需要这步；
+	 * 这里只为内置指示器重新配置，即 working 关闭时的回退路径。
+	 */
+	const syncIndicator = (ctx: ExtensionContext): void => {
+		const name = ctx.ui.theme.name;
+		if (name === syncedTheme) return;
+		syncedTheme = name;
+		if (!enabled.indicator) return;
+		ctx.ui.setWorkingIndicator({ frames: buildPulseFrames(ctx.ui.theme), intervalMs: PULSE_INTERVAL_MS });
+	};
+
+	/** 用自己的编辑器子类接管边框标题，让模型名与耗时在空闲时也留在边框上。 */
+	const installBorderEditor = (ctx: ExtensionContext): void => {
+		ctx.ui.setEditorComponent((tui, theme, keybindings) => {
+			borderEditor = new PiUiBorderEditor(tui, theme, keybindings, {
+				getModelId: () => modelOverride ?? current?.model?.id,
+				getTimerSeconds: timerSeconds,
+				isStreaming: () => turnStartedAt !== undefined,
+				isPulseEnabled: () => enabled.indicator,
+				getTheme: () => ctx.ui.theme,
+			});
+			return borderEditor;
+		});
+		// 内置指示器只在流式期间出现，且已被标题接管，别再让它每轮建/销毁一个 Loader。
+		ctx.ui.setWorkingVisible(false);
+	};
+
+	/** 换回内置编辑器，还原 pi 默认行为：流式期间在边框显示模型名。 */
+	const removeBorderEditor = (ctx: ExtensionContext): void => {
+		borderEditor?.dispose();
+		borderEditor = undefined;
+		ctx.ui.setEditorComponent(undefined);
+		ctx.ui.setWorkingVisible(true);
+		ctx.ui.setWorkingMessage(ctx.model?.id);
+	};
+
+	const apply = (ctx: ExtensionContext, feature: Feature, on: boolean): void => {
+		enabled[feature] = on;
+		switch (feature) {
+			case "footer":
+				if (on) installFooter(ctx);
+				else removeFooter(ctx);
+				return;
+			case "indicator":
+				syncedTheme = undefined;
+				if (on) syncIndicator(ctx);
+				else ctx.ui.setWorkingIndicator(undefined);
+				borderEditor?.sync();
+				return;
+			case "working":
+				if (on) installBorderEditor(ctx);
+				else removeBorderEditor(ctx);
+				return;
+		}
+	};
+
+	/**
+	 * 其他扩展在占用会话期间临时替换边框上的模型名（典型场景：压缩用了另一个模型）。
+	 * 传非空字符串覆盖，传 undefined 恢复；没扩展发布时这条通道无副作用。
+	 * 订阅由 pi 在会话替换/重载时统一退订（loader 跟踪 eventBus 订阅），这里不手动清理。
+	 */
+	pi.events.on("pi-ui:model-override", (data) => {
+		modelOverride = typeof data === "string" && data.length > 0 ? data : undefined;
+		borderEditor?.sync();
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		current = ctx;
+		syncedTheme = undefined;
+		modelOverride = undefined;
+		syncIndicator(ctx);
+		if (enabled.working) installBorderEditor(ctx);
+		else removeBorderEditor(ctx);
+		if (enabled.footer) installFooter(ctx);
+	});
+
+	pi.on("model_select", (_event, ctx) => {
+		current = ctx;
+		if (!enabled.working) ctx.ui.setWorkingMessage(ctx.model?.id);
+		borderEditor?.sync();
+	});
+
+	pi.on("agent_start", (_event, ctx) => {
+		current = ctx;
+		syncIndicator(ctx);
+		turnStartedAt = Date.now();
+		borderEditor?.sync();
+	});
+
+	pi.on("agent_settled", (_event, ctx) => {
+		current = ctx;
+		if (turnStartedAt !== undefined) {
+			lastTurnSeconds = (Date.now() - turnStartedAt) / 1000;
+			turnStartedAt = undefined;
+		}
+		// 停下呼吸灯，并重绘一次让耗时定格为上一轮结果。
+		borderEditor?.sync();
+	});
+
+	pi.on("session_shutdown", () => {
+		borderEditor?.dispose();
+		borderEditor = undefined;
+		footer = undefined;
+		current = undefined;
+		modelOverride = undefined;
+	});
+
+	pi.registerCommand(COMMAND, {
+		description: "查看或开关 pi-ui 的 footer、呼吸灯与编辑器边框标题",
+		handler: async (args, ctx) => {
+			current = ctx;
+			const [feature, value] = args.trim().toLowerCase().split(/\s+/);
+
+			if (!feature) {
+				const lines = FEATURES.map((key) => `${key}: ${enabled[key] ? "on" : "off"}`);
+				ctx.ui.notify(`${lines.join("  ")}\n${USAGE}`, "info");
+				return;
+			}
+			if (!isFeature(feature) || (value !== "on" && value !== "off")) {
+				ctx.ui.notify(USAGE, "warning");
+				return;
+			}
+			apply(ctx, feature, value === "on");
+			ctx.ui.notify(`${feature} ${value}`, "info");
+		},
+	});
+}

package/extensions/indicator.ts

@@ -0,0 +1,27 @@
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+
+/** 帧间隔，与原版 pi-catppuccin-tui 保持一致。 */
+export const PULSE_INTERVAL_MS = 120;
+
+/**
+ * 闪烁序列 `· • ● ● • ·`，帧形沿用原版。
+ *
+ * 原实现把 Macchiato 的十六进制色写死在帧字符串里，换主题后指示器颜色不会跟着变；
+ * 这里保留帧形，颜色改为当前主题的 token（dim → accent → borderAccent）。
+ */
+const PULSE: ReadonlyArray<readonly [ThemeColor, string]> = [
+	["dim", "·"],
+	["dim", "•"],
+	["accent", "●"],
+	["borderAccent", "●"],
+	["muted", "•"],
+	["dim", "·"],
+];
+
+/**
+ * 构建闪烁帧。帧是构建期快照（`theme.fg()` 在此刻求值），
+ * 主题切换后需要重新调用本函数才会生效。
+ */
+export function buildPulseFrames(theme: Theme): string[] {
+	return PULSE.map(([color, glyph]) => theme.fg(color, glyph));
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@muzi3/pi-ui",
+  "version": "0.1.0",
+  "description": "Pi extension: 双行仪表盘 footer + 主题化工作指示器 + Catppuccin Mocha 层次增强主题",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-theme",
+    "catppuccin",
+    "footer"
+  ],
+  "license": "MIT",
+  "author": "muzi",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/muzi/pi-packages.git",
+    "directory": "packages/pi-ui"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ],
+    "themes": [
+      "./themes"
+    ]
+  },
+  "files": [
+    "extensions",
+    "themes",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/themes/pi-ui-catppuccin.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "name": "pi-ui-catppuccin",
+  "vars": {
+    "rosewater": "#f5e0dc",
+    "flamingo": "#f2cdcd",
+    "pink": "#f5c2e7",
+    "mauve": "#cba6f7",
+    "red": "#f38ba8",
+    "redBg": "#493446",
+    "maroon": "#eba0ac",
+    "peach": "#fab387",
+    "yellow": "#f9e2af",
+    "green": "#a6e3a1",
+    "teal": "#94e2d5",
+    "sky": "#89dceb",
+    "sapphire": "#74c7ec",
+    "blue": "#89b4fa",
+    "lavender": "#b4befe",
+    "text": "#cdd6f4",
+    "subtext1": "#bac2de",
+    "subtext0": "#a6adc8",
+    "overlay2": "#9399b2",
+    "overlay1": "#7f849c",
+    "overlay0": "#6c7086",
+    "surface2": "#585b70",
+    "surface1": "#45475a",
+    "surface0": "#313244",
+    "base": "#1e1e2e",
+    "mantle": "#181825",
+    "crust": "#11111b"
+  },
+  "colors": {
+    "accent": "mauve",
+    "border": "surface2",
+    "borderAccent": "lavender",
+    "borderMuted": "surface1",
+    "success": "green",
+    "error": "red",
+    "warning": "yellow",
+    "muted": "subtext0",
+    "dim": "overlay1",
+    "text": "text",
+    "thinkingText": "subtext1",
+    "selectedBg": "surface1",
+    "searchMatchBg": "surface2",
+    "searchMatchText": "text",
+    "scrollbarTrack": "surface0",
+    "scrollbarThumb": "overlay0",
+    "userMessageBg": "surface0",
+    "userMessageText": "text",
+    "customMessageBg": "mantle",
+    "customMessageText": "text",
+    "customMessageLabel": "mauve",
+    "toolPendingBg": "mantle",
+    "toolSuccessBg": "surface0",
+    "toolErrorBg": "redBg",
+    "toolTitle": "blue",
+    "toolOutput": "overlay2",
+    "mdHeading": "lavender",
+    "mdLink": "blue",
+    "mdLinkUrl": "sapphire",
+    "mdCode": "peach",
+    "mdCodeBlock": "subtext1",
+    "mdCodeBlockBorder": "surface1",
+    "mdQuote": "subtext0",
+    "mdQuoteBorder": "surface1",
+    "mdHr": "surface2",
+    "mdListBullet": "overlay2",
+    "toolDiffAdded": "green",
+    "toolDiffRemoved": "red",
+    "toolDiffContext": "subtext0",
+    "syntaxComment": "overlay2",
+    "syntaxKeyword": "mauve",
+    "syntaxFunction": "blue",
+    "syntaxVariable": "maroon",
+    "syntaxString": "green",
+    "syntaxNumber": "peach",
+    "syntaxType": "yellow",
+    "syntaxOperator": "sky",
+    "syntaxPunctuation": "overlay2",
+    "thinkingOff": "surface1",
+    "thinkingMinimal": "surface2",
+    "thinkingLow": "blue",
+    "thinkingMedium": "sapphire",
+    "thinkingHigh": "mauve",
+    "thinkingXhigh": "maroon",
+    "thinkingMax": "red",
+    "bashMode": "peach"
+  },
+  "export": {
+    "pageBg": "#11111b",
+    "cardBg": "#1e1e2e",
+    "infoBg": "#313244"
+  }
+}