@buyi1net/pi-toolkit 0.0.1

package/modules/tui/plugin/editor.ts

@@ -0,0 +1,396 @@
+import {
+	CustomEditor,
+	type ExtensionContext,
+	type KeybindingsManager,
+	type Theme,
+} from "@earendil-works/pi-coding-agent";
+import {
+	CURSOR_MARKER,
+	stripTerminalSequences,
+	truncateToWidth,
+	visibleWidth,
+	type Component,
+	type EditorTheme,
+	type OverlayHandle,
+	type OverlayMargin,
+	type OverlayOptions,
+	type TUI,
+	type TuiMainScreenRenderState,
+} from "@earendil-works/pi-tui";
+import type { UsageRuntimeState } from "../kernel/usage-node.ts";
+import {
+	splitNativeEditorRender,
+	insertTopBorderStatus,
+} from "../renderer/editor.ts";
+import { resolveGlyphs, type IconGlyphs } from "../renderer/icons.ts";
+import {
+	durationStatusColor,
+	formatElapsed,
+	layoutEditorStatus,
+	thinkingStatusColor,
+	type StatusSegment,
+	type TurnTimerSnapshot,
+} from "../status/status-segments.ts";
+import {
+	resolveStatusSettings,
+	type EditorLeftSegmentId,
+	type ResolvedStatusSettings,
+} from "../status/status-config.ts";
+import { buildEditorProviderSegments } from "../status/provider-status.ts";
+import type {
+	EditorLayoutSource,
+	ProviderUsageSource,
+	SessionStatusSource,
+	StatusAppearance,
+} from "./status-sources.ts";
+import { isMainScreenTui, isSafeRenderState } from "./screen-transition.ts";
+import { sanitizeSingleLine } from "../status/project-status.ts";
+
+const MIN_DECORATED_WIDTH = 6;
+
+function cropAutocompleteLines(lines: readonly string[], maxHeight: number): string[] {
+	const height = Math.max(0, Math.floor(maxHeight));
+	if (height === 0) return [];
+	if (lines.length <= height) return [...lines];
+	const selectedIndex = lines.findIndex((line) =>
+		stripTerminalSequences(line).trimStart().startsWith("→ "),
+	);
+	const targetIndex = selectedIndex >= 0 ? selectedIndex : 0;
+	const start = Math.max(
+		0,
+		Math.min(targetIndex - Math.floor((height - 1) / 2), lines.length - height),
+	);
+	return lines.slice(start, start + height);
+}
+
+export function formatModel(ctx: ExtensionContext): string {
+	const model = ctx.model;
+	if (!model) return "no model";
+	return sanitizeSingleLine(model.provider ? `${model.provider}/${model.id}` : model.id) || "no model";
+}
+
+function formatCompactModel(ctx: ExtensionContext): string {
+	return sanitizeSingleLine(ctx.model?.id ?? "no model") || "no model";
+}
+
+function getFrameStatus(
+	ctx: ExtensionContext,
+	theme: Theme,
+	glyphs: IconGlyphs,
+	width: number,
+	settings: ResolvedStatusSettings,
+	providerState: UsageRuntimeState | undefined,
+	timer: TurnTimerSnapshot,
+): { left: string; right: string } {
+	const thinking = ctx.thinkingLevel ?? "off";
+	const color = (role: Parameters<Theme["fg"]>[0], text: string): string => theme.fg(role, text);
+	const provider = providerState
+		? buildEditorProviderSegments(providerState, theme)
+		: null;
+	const leftById: Record<EditorLeftSegmentId, StatusSegment> = {
+		provider: provider?.provider ?? {
+			id: "provider",
+			text: "",
+			priority: 4,
+		},
+		model: {
+			id: "model",
+			text: color("accent", formatCompactModel(ctx)),
+			compactText: color("accent", formatCompactModel(ctx)),
+			priority: 0,
+			required: true,
+		},
+		thinking: {
+			id: "thinking",
+			text: color(thinkingStatusColor(thinking), thinking),
+			priority: 2,
+		},
+		duration: {
+			id: "duration",
+			text: timer.state === "idle"
+				? ""
+				: color(durationStatusColor(timer.state), formatElapsed(timer.elapsedMs)),
+			priority: 1,
+		},
+		balance: provider?.balance ?? {
+			id: "balance",
+			text: "",
+			priority: 3,
+		},
+		subscription: provider?.subscription ?? {
+			id: "subscription",
+			text: "",
+			priority: 3,
+		},
+	};
+	const left = settings.editorLeft.map((id) => leftById[id]).filter((segment) => segment.text);
+	// 顶边右侧已让位：会话遥测整体移入 Footer 第二行，顶边只保留左侧身份段
+	return layoutEditorStatus(left, [], width);
+}
+
+export interface PiUiEditorHooks {
+	onReloadSubmit?: () => void;
+	onFrameRendered?: () => void;
+}
+
+export class PiUiEditor extends CustomEditor {
+	private readonly ctx: ExtensionContext;
+	private readonly getGlyphs: () => IconGlyphs;
+	private readonly settings: ResolvedStatusSettings;
+	private readonly getFooterHeight: () => number;
+	private readonly getProviderStatus: () => UsageRuntimeState | undefined;
+	private readonly getTimer: () => TurnTimerSnapshot;
+	private readonly appKeybindings: KeybindingsManager;
+	private readonly autocompleteOverlay: Component & { setLines(lines: readonly string[]): void };
+	private readonly autocompleteOverlayOptions: OverlayOptions;
+	private autocompleteOverlayLines: readonly string[] = [];
+	private autocompleteOverlayHandle: OverlayHandle | undefined;
+	private autocompleteOverlayToken = 0;
+	private frameHeight = 0;
+	private frameCursorRow = -1;
+	private suppressAutocompleteOverlay = false;
+	private disposed = false;
+	private readonly hooks: PiUiEditorHooks;
+
+	// 前四个参数由宿主编辑框工厂签名与基类要求保持原位；其余按数据源分组，
+	// 缺省时回落到与旧位置参数一致的默认行为。
+	constructor(
+		tui: TUI,
+		theme: EditorTheme,
+		keybindings: KeybindingsManager,
+		ctx: ExtensionContext,
+		appearance: StatusAppearance = {},
+		provider: ProviderUsageSource = {},
+		session: SessionStatusSource = {},
+		layout: EditorLayoutSource = {},
+		hooks: PiUiEditorHooks = {},
+	) {
+		super(tui, theme, keybindings);
+		this.ctx = ctx;
+		this.getGlyphs = appearance.getGlyphs ?? (() => resolveGlyphs("unicode"));
+		this.settings = appearance.settings ?? resolveStatusSettings({});
+		this.getFooterHeight = layout.getFooterHeight ?? (() => 0);
+		this.getProviderStatus = provider.getState ?? (() => undefined);
+		this.hooks = hooks;
+		this.getTimer = session.getTimer ?? (() => ({ state: "idle", elapsedMs: 0 }));
+		this.appKeybindings = keybindings;
+		this.autocompleteOverlay = {
+			setLines: (lines) => { this.autocompleteOverlayLines = [...lines]; },
+			invalidate() {},
+			render: (overlayWidth) => this.autocompleteOverlayLines.map((line) => {
+				const clipped = truncateToWidth(line, overlayWidth, "");
+				return `${clipped}${" ".repeat(Math.max(0, overlayWidth - visibleWidth(clipped)))}`;
+			}),
+		};
+		const margin: OverlayMargin = {};
+		// Footer 高度会随遥测和供应商数据变化；Overlay 在合成阶段读取最新值，
+		// 始终贴在输入框上方，不进入正文布局，也不覆盖输入框和 Footer。
+		Object.defineProperty(margin, "bottom", {
+			enumerable: true,
+			get: () => this.frameHeight + Math.max(0, this.getFooterHeight()),
+		});
+		this.autocompleteOverlayOptions = {
+			anchor: "bottom-left",
+			width: 1,
+			margin,
+			nonCapturing: true,
+		};
+	}
+
+	override render(width: number): string[] {
+		if (width < MIN_DECORATED_WIDTH) {
+			const baseLines = super.render(width);
+			return this.finishRender(this.renderWithAutocompleteOverlay(baseLines, baseLines, width));
+		}
+
+		const baseLines = super.render(width);
+		const renderedLines = insertTopBorderStatus(baseLines, {
+			left: getFrameStatus(
+				this.ctx,
+				this.ctx.ui.theme,
+				this.getGlyphs(),
+				width,
+				this.settings,
+				this.getProviderStatus(),
+				this.getTimer(),
+			).left,
+			borderColor: (text) => this.borderColor(text),
+		});
+		return this.finishRender(this.renderWithAutocompleteOverlay(baseLines, renderedLines, width));
+	}
+
+	override handleInput(data: string): void {
+		const submitsInput = this.appKeybindings.matches(data, "tui.input.submit");
+		const submitsAutocomplete =
+			this.tui.mode === "regular" &&
+			this.autocompleteOverlayHandle &&
+			submitsInput;
+		if (!submitsAutocomplete) {
+			if (submitsInput && this.getText().trim() === "/reload") this.hooks.onReloadSubmit?.();
+			super.handleInput(data);
+			return;
+		}
+
+		// 补全确认和命令提交发生在同一次同步调用中。先撤下 Overlay，但不提交旧 Editor 帧；
+		// 等父类给出补全后的完整命令，再决定进入 reload 过渡或恢复普通底图。
+		const originalOnSubmit = this.onSubmit;
+		let didSubmit = false;
+		this.suppressAutocompleteOverlay = true;
+		this.hideAutocompleteOverlay();
+		this.onSubmit = (text) => {
+			didSubmit = true;
+			if (text.trim() === "/reload") this.hooks.onReloadSubmit?.();
+			else this.tui.renderNow(false);
+			originalOnSubmit?.(text);
+		};
+		try {
+			super.handleInput(data);
+			if (!didSubmit) this.tui.renderNow(false);
+		} finally {
+			this.onSubmit = originalOnSubmit;
+			this.suppressAutocompleteOverlay = false;
+		}
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.hideAutocompleteOverlay();
+	}
+
+	private finishRender(lines: string[]): string[] {
+		this.hooks.onFrameRendered?.();
+		return lines;
+	}
+
+	private renderWithAutocompleteOverlay(
+		baseLines: readonly string[],
+		renderedLines: readonly string[],
+		width: number,
+	): string[] {
+		const autocompleteCount = splitNativeEditorRender(baseLines).autocomplete.length;
+		const frameEnd = Math.max(0, renderedLines.length - autocompleteCount);
+		const frameLines = renderedLines.slice(0, frameEnd);
+		this.frameHeight = frameLines.length;
+		this.frameCursorRow = frameLines.findIndex((line) => line.includes(CURSOR_MARKER));
+
+		if (this.tui.mode !== "regular") {
+			this.updateAutocompleteOverlay([], width);
+			return [...renderedLines];
+		}
+
+		const autocompleteLines = this.suppressAutocompleteOverlay ? [] : renderedLines.slice(frameEnd);
+		const layout = autocompleteLines.length > 0
+			? this.resolveAutocompleteOverlayLayout(autocompleteLines.length)
+			: undefined;
+		if (layout?.maxHeight === 0) {
+			// Editor 已贴到可见区顶部时没有安全的覆盖空间，保留原生内联补全。
+			this.updateAutocompleteOverlay([], width);
+			return [...renderedLines];
+		}
+		this.updateAutocompleteOverlay(autocompleteLines, width, layout);
+		return frameLines;
+	}
+
+	private hideAutocompleteOverlay(): void {
+		this.autocompleteOverlayToken += 1;
+		this.autocompleteOverlay.setLines([]);
+		delete this.autocompleteOverlayOptions.row;
+		this.autocompleteOverlayHandle?.hide();
+		this.autocompleteOverlayHandle = undefined;
+	}
+
+	private updateAutocompleteOverlay(
+		lines: readonly string[],
+		width: number,
+		initialLayout = this.resolveAutocompleteOverlayLayout(lines.length),
+	): void {
+		const initialLines = initialLayout
+			? cropAutocompleteLines(lines, initialLayout.maxHeight)
+			: [...lines];
+		this.setAutocompleteOverlayLines(initialLines);
+		this.setAutocompleteOverlayRow(initialLayout);
+		this.autocompleteOverlayOptions.width = Math.max(1, width);
+		const token = ++this.autocompleteOverlayToken;
+		if (initialLines.length > 0) {
+			// 当前正文渲染结束后再定位和挂载，避免在组件 render 中读取旧坐标或修改 Overlay 栈。
+			queueMicrotask(() => {
+				if (this.disposed || token !== this.autocompleteOverlayToken) return;
+				const layout = this.resolveAutocompleteOverlayLayout(lines.length);
+				const visibleLines = layout
+					? cropAutocompleteLines(lines, layout.maxHeight)
+					: [...lines];
+				const linesChanged = this.setAutocompleteOverlayLines(visibleLines);
+				const positionChanged = this.setAutocompleteOverlayRow(layout);
+				if (visibleLines.length === 0) {
+					this.autocompleteOverlayHandle?.hide();
+					this.autocompleteOverlayHandle = undefined;
+					return;
+				}
+				if (!this.autocompleteOverlayHandle) {
+					this.autocompleteOverlayHandle = this.tui.showOverlay(
+						this.autocompleteOverlay,
+						this.autocompleteOverlayOptions,
+					);
+				} else if (positionChanged || linesChanged) {
+					this.tui.requestRender();
+				}
+			});
+			return;
+		}
+		if (lines.length === 0 && this.autocompleteOverlayHandle) {
+			queueMicrotask(() => {
+				if (token !== this.autocompleteOverlayToken || !this.autocompleteOverlayHandle) return;
+				this.autocompleteOverlayHandle.hide();
+				this.autocompleteOverlayHandle = undefined;
+			});
+		}
+	}
+
+	private resolveAutocompleteOverlayLayout(
+		autocompleteHeight: number,
+	): { row: number; maxHeight: number } | undefined {
+		if (!isMainScreenTui(this.tui) || this.frameCursorRow < 0) {
+			return undefined;
+		}
+
+		let state: TuiMainScreenRenderState;
+		try {
+			state = this.tui.captureRenderState();
+		} catch {
+			return undefined;
+		}
+		if (!isSafeRenderState(this.tui, state)) return undefined;
+
+		const editorTop = state.hardwareCursorRow - this.frameCursorRow - state.previousViewportTop;
+		const maxHeight = Math.max(0, Math.min(editorTop, this.tui.terminal.rows));
+		return {
+			row: Math.max(0, editorTop - Math.min(autocompleteHeight, maxHeight)),
+			maxHeight,
+		};
+	}
+
+	private setAutocompleteOverlayLines(lines: readonly string[]): boolean {
+		if (
+			lines.length === this.autocompleteOverlayLines.length &&
+			lines.every((line, index) => line === this.autocompleteOverlayLines[index])
+		) {
+			return false;
+		}
+		this.autocompleteOverlay.setLines(lines);
+		return true;
+	}
+
+	private setAutocompleteOverlayRow(
+		layout: { row: number; maxHeight: number } | undefined,
+	): boolean {
+		if (!layout) {
+			if (this.autocompleteOverlayOptions.row === undefined) return false;
+			delete this.autocompleteOverlayOptions.row;
+			return true;
+		}
+		if (this.autocompleteOverlayOptions.row === layout.row) return false;
+		this.autocompleteOverlayOptions.row = layout.row;
+		return true;
+	}
+}

package/modules/tui/plugin/footer.ts

@@ -0,0 +1,161 @@
+import type { ContextUsage, ReadonlyFooterDataProvider, Theme } from "@earendil-works/pi-coding-agent";
+import {
+	truncateToWidth,
+	visibleWidth,
+	type Component,
+	type TUI,
+} from "@earendil-works/pi-tui";
+import type { UsageRuntimeState } from "../kernel/usage-node.ts";
+import { formatLeadingIcon, resolveGlyphs, type IconGlyphs } from "../renderer/icons.ts";
+import {
+	renderProjectStatusLine,
+	sanitizeStyledSingleLine,
+} from "../status/project-status.ts";
+import type { TurnTimerSnapshot } from "../status/status-segments.ts";
+import {
+	buildEditorUsageSegments,
+	renderStatusLineSegments,
+	type SessionStatusSnapshot,
+} from "../status/session-status.ts";
+import {
+	resolveStatusSettings,
+	type ResolvedStatusSettings,
+} from "../status/status-config.ts";
+import type {
+	FooterLayoutSource,
+	ProjectEnvironmentSource,
+	SessionStatusSource,
+	StatusAppearance,
+} from "./status-sources.ts";
+
+const FOOTER_PADDING_X = 1;
+
+/** 生命周期钩子：卸载前的宿主过渡动作，不属于任何数据源，单独成组。 */
+export interface ProjectStatusFooterHooks {
+	beforeDispose?: () => void;
+}
+
+export class ProjectStatusFooter implements Component {
+	private readonly theme: Theme;
+	private readonly footerData: ReadonlyFooterDataProvider;
+	private readonly getProjectStatus: ProjectEnvironmentSource["getProjectStatus"];
+	private readonly cwd: string;
+	private readonly beforeDispose: (() => void) | undefined;
+	private readonly getGlyphs: () => IconGlyphs;
+	private readonly settings: ResolvedStatusSettings;
+	private readonly getRuntimeStatus: ProjectEnvironmentSource["getRuntimeStatus"];
+	private readonly reportHeight: ((height: number) => void) | undefined;
+	private readonly getTimer: () => TurnTimerSnapshot;
+	private readonly getSessionStatus: () => SessionStatusSnapshot;
+	private readonly getContextUsage: () => ContextUsage | undefined;
+	private readonly getContextWindow: () => number | undefined;
+	private readonly getAutoCompactionEnabled: () => boolean;
+	private disposed = false;
+
+	// 宿主回调参数（tui/theme/footerData）保持原位；其余入参按数据源分组，
+	// 缺省时回落到与旧位置参数一致的默认行为。
+	constructor(
+		_tui: TUI,
+		theme: Theme,
+		footerData: ReadonlyFooterDataProvider,
+		appearance: StatusAppearance = {},
+		project: ProjectEnvironmentSource = {},
+		session: SessionStatusSource = {},
+		layout: FooterLayoutSource = {},
+		hooks: ProjectStatusFooterHooks = {},
+	) {
+		this.theme = theme;
+		this.footerData = footerData;
+		this.getGlyphs = appearance.getGlyphs ?? (() => resolveGlyphs("unicode"));
+		this.settings = appearance.settings ?? resolveStatusSettings({});
+		this.getProjectStatus = project.getProjectStatus;
+		this.getRuntimeStatus = project.getRuntimeStatus;
+		this.cwd = project.cwd ?? process.cwd();
+		this.reportHeight = layout.reportHeight;
+		this.getTimer = session.getTimer ?? (() => ({ state: "idle", elapsedMs: 0 }));
+		this.getSessionStatus = session.getSessionStatus ?? (() => ({
+			sessionId: "",
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: 0,
+			cacheWriteTokens: 0,
+			cost: 0,
+			turns: 0,
+			compactions: 0,
+		}));
+		this.getContextUsage = session.getContextUsage ?? (() => undefined);
+		this.getContextWindow = session.getContextWindow ?? (() => undefined);
+		this.getAutoCompactionEnabled = session.getAutoCompactionEnabled ?? (() => false);
+		this.beforeDispose = hooks.beforeDispose;
+	}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const glyphs = this.getGlyphs();
+		const paddingX = width >= FOOTER_PADDING_X * 2 + 1 ? FOOTER_PADDING_X : 0;
+		const contentWidth = Math.max(1, width - paddingX * 2);
+		const projectLine = renderProjectStatusLine(
+			{
+				// 快照未接线时仍保留占位，保证 Footer 结构从首帧起定型。
+				...(this.getProjectStatus?.() ?? { cwd: this.cwd, branch: null }),
+				runtime: this.getRuntimeStatus?.(),
+				duration: this.getTimer(),
+			},
+			contentWidth,
+			this.theme,
+			undefined,
+			glyphs,
+			this.settings.footerPrimary,
+		);
+		// 第二行：会话遥测（↑↓ R/CH ctx），行首 usage 图标作视觉锚点。
+		// 上下文未就绪时不展示零值 token 段，但保留 Context、auto、轮数与压缩次数。
+		const contextUsage = this.getContextUsage();
+		const usageSegments = buildEditorUsageSegments(
+			this.getSessionStatus(),
+			contextUsage,
+			this.getContextWindow(),
+			this.theme,
+			glyphs,
+			contextUsage === undefined
+				? this.settings.footerUsage.filter((segment) => segment === "context")
+				: this.settings.footerUsage,
+			this.getAutoCompactionEnabled(),
+		);
+		// 行首图标属于状态行的一部分，必须先从可用宽度中扣除；最后的截断
+		// 只是防御性兜底，避免宽字符或第三方状态文本再次把整行顶出终端。
+		const usageIconText = formatLeadingIcon(glyphs.usage);
+		const usageIconWidth = visibleWidth(usageIconText);
+		const usageSegmentsWidth = Math.max(0, contentWidth - usageIconWidth);
+		const renderedUsageSegments = usageSegmentsWidth > 0
+			? renderStatusLineSegments(usageSegments, usageSegmentsWidth, this.theme.fg("muted", " · "))
+			: "";
+		const usageLine = usageSegments.length > 0
+			? truncateToWidth(
+				`${this.theme.fg("muted", usageIconText)}${renderedUsageSegments}`,
+				contentWidth,
+			)
+			: "";
+		const showExtensions = this.settings.footerExtra.includes("extensions");
+		const statuses = showExtensions
+			? [...this.footerData.getExtensionStatuses().entries()]
+				.sort(([left], [right]) => left.localeCompare(right))
+				.map(([, status]) => sanitizeStyledSingleLine(status))
+				.filter(Boolean)
+			: [];
+		const lines = projectLine ? [projectLine] : [];
+		if (usageLine) lines.push(usageLine);
+		if (statuses.length > 0) {
+			lines.push(truncateToWidth(statuses.join(" · "), contentWidth, this.theme.fg("dim", "…")));
+		}
+		this.reportHeight?.(lines.length);
+		return paddingX > 0 ? lines.map((line) => `${" ".repeat(paddingX)}${line}`) : lines;
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.beforeDispose?.();
+		this.reportHeight?.(0);
+	}
+}

package/modules/tui/plugin/index.ts

@@ -0,0 +1,30 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerPiTuiLifecycle, type PiTuiPluginDependencies } from "./lifecycle.ts";
+import type { VisibleScreenOutput } from "./screen-transition.ts";
+
+// 视图与机制的稳定出口：测试和下游从这里 import，物理位置变化不影响调用方。
+export { PiUiEditor, formatModel } from "./editor.ts";
+export { ProjectStatusFooter } from "./footer.ts";
+export {
+	flashVisibleScreen,
+	restoreVisibleMainScreen,
+} from "./screen-transition.ts";
+export { AutoCompactionStatusController } from "../status/auto-compaction.ts";
+export type { PiTuiPluginDependencies } from "./lifecycle.ts";
+// 数据源分组接口是视图构造器的公开面，随视图一起从稳定出口导出。
+export type {
+	EditorLayoutSource,
+	FooterLayoutSource,
+	ProjectEnvironmentSource,
+	ProviderUsageSource,
+	SessionStatusSource,
+	StatusAppearance,
+} from "./status-sources.ts";
+
+export default function (
+	pi: ExtensionAPI,
+	output: VisibleScreenOutput = process.stdout,
+	dependencies: PiTuiPluginDependencies = {},
+): void {
+	registerPiTuiLifecycle(pi, output, dependencies);
+}