@buyi1net/pi-toolkit 0.0.1

package/modules/tui/plugin/status-sources.ts

@@ -0,0 +1,49 @@
+import type { ContextUsage } from "@earendil-works/pi-coding-agent";
+import type { UsageRuntimeState } from "../kernel/usage-node.ts";
+import type { IconGlyphs } from "../renderer/icons.ts";
+import type { ProjectStatusSnapshot } from "../status/project-status.ts";
+import type { ResolvedStatusSettings } from "../status/status-config.ts";
+import type { RuntimeStatusSnapshot } from "../status/runtime-status.ts";
+import type { SessionStatusSnapshot } from "../status/session-status.ts";
+import type { TurnTimerSnapshot } from "../status/status-segments.ts";
+
+// 视图数据源分组契约：Footer 与 Editor 只按数据源接收分组接口，装配
+// （lifecycle.ts）负责把状态控制器与宿主上下文接成这些组。新增一个状态
+// 数据段只扩展或实现对应分组，不再改动视图构造器签名。
+
+/** 会话源：本轮计时器与会话遥测（token/cache、上下文用量、自动压缩）。 */
+export interface SessionStatusSource {
+	getTimer?: () => TurnTimerSnapshot;
+	getSessionStatus?: () => SessionStatusSnapshot;
+	getContextUsage?: () => ContextUsage | undefined;
+	getContextWindow?: () => number | undefined;
+	getAutoCompactionEnabled?: () => boolean;
+}
+
+/** 供应商源：用量快照查询；刷新请求由装配层接给控制器，不进视图。 */
+export interface ProviderUsageSource {
+	getState?: () => UsageRuntimeState | undefined;
+}
+
+/** 项目环境源：Git 状态、运行时状态与工作目录，供 Footer 项目行。 */
+export interface ProjectEnvironmentSource {
+	getProjectStatus?: () => Readonly<ProjectStatusSnapshot>;
+	getRuntimeStatus?: () => Readonly<RuntimeStatusSnapshot> | null;
+	cwd?: string;
+}
+
+/** 布局源（Footer 侧）：高度回报。 */
+export interface FooterLayoutSource {
+	reportHeight?: (height: number) => void;
+}
+
+/** 布局源（Editor 侧）：Footer 高度查询，供补全 Overlay 定位。 */
+export interface EditorLayoutSource {
+	getFooterHeight?: () => number;
+}
+
+/** 外观配置：图标解析与状态段设置，随数据源分组一起注入两端视图。 */
+export interface StatusAppearance {
+	getGlyphs?: () => IconGlyphs;
+	settings?: ResolvedStatusSettings;
+}

package/modules/tui/plugin/transition-gate.ts

@@ -0,0 +1,261 @@
+import type {
+	TUI,
+	TuiMainScreenRenderState,
+} from "@earendil-works/pi-tui";
+
+const CLEAR_VISIBLE_SCREEN = "\x1b[2J\x1b[H";
+const BEGIN_SYNCHRONIZED_OUTPUT = "\x1b[?2026h";
+const END_SYNCHRONIZED_OUTPUT = "\x1b[?2026l";
+const MAX_HELD_OUTPUT_BYTES = 2 * 1024 * 1024;
+const FAIL_OPEN_AFTER_MS = 10_000;
+const GUARD_CLEAR_INTERVAL_MS = 16;
+const GLOBAL_GATE_KEY = "__piTuiTerminalTransitionGateV1";
+
+type TerminalWriteTarget = {
+	write(data: string): void;
+};
+
+type TransitionOutput = {
+	isTTY?: boolean;
+	write(data: string): unknown;
+};
+
+type MainScreenTui = TUI & {
+	captureRenderState(): TuiMainScreenRenderState;
+	restoreRenderState(state: TuiMainScreenRenderState): void;
+};
+
+type HeldWrite = {
+	terminal: TerminalWriteTarget;
+	data: string;
+};
+
+export interface TransitionHoldOptions {
+	clearVisibleScreen?: boolean;
+}
+
+function isMainScreenTui(tui: TUI): tui is MainScreenTui {
+	return (
+		tui.mode === "regular" &&
+		typeof (tui as Partial<MainScreenTui>).captureRenderState === "function" &&
+		typeof (tui as Partial<MainScreenTui>).restoreRenderState === "function"
+	);
+}
+
+function canRedrawVisibleViewport(tui: TUI, state: TuiMainScreenRenderState): boolean {
+	const width = tui.terminal.columns;
+	const height = tui.terminal.rows;
+	if (!Number.isSafeInteger(width) || width <= 0 || !Number.isSafeInteger(height) || height <= 0) {
+		return false;
+	}
+	if (!Array.isArray(state.previousLines) || state.previousLines.length === 0) return false;
+	if (state.previousLines.some((line) => line.includes("\x1b_G") || line.includes("\x1b]1337;File="))) {
+		return false;
+	}
+	return Number.isSafeInteger(state.previousViewportTop) && state.previousViewportTop >= 0;
+}
+
+export class TerminalTransitionGate {
+	private readonly output: TransitionOutput;
+	private holding = false;
+	private heldWrites: HeldWrite[] = [];
+	private heldOutputBytes = 0;
+	private failOpenTimer: ReturnType<typeof setTimeout> | undefined;
+	private hasVisibleFrame = false;
+
+	// 实例级拦截：宿主真实 terminal（jiti 双副本下 prototype patch 拦不到宿主）。
+	private hookedTerminal: TerminalWriteTarget | undefined;
+	private instanceOriginalWrite: ((data: string) => void) | undefined;
+	// 拦截挂接前的看门狗：holding 且 hook 未挂期间宿主仍在渲染原生帧（真实配置
+	// 下扩展初始化可达数秒），以约一帧的间隔清屏，落屏帧最多存活 16ms——
+	// 低于单行文字的感知阈值；空屏上的清屏是视觉 no-op，不会闪烁。
+	private guardTimer: ReturnType<typeof setInterval> | undefined;
+
+	constructor(output: TransitionOutput = process.stdout) {
+		this.output = output;
+	}
+
+	/** 同一实例重复挂接不叠加拦截；换绑时先恢复旧实例，避免旧终端继续持闸。 */
+	hookTerminal(terminal: TerminalWriteTarget): void {
+		if (this.hookedTerminal === terminal) return;
+		this.stopGuardTimer();
+		if (this.hookedTerminal && this.instanceOriginalWrite) {
+			this.hookedTerminal.write = this.instanceOriginalWrite;
+		}
+		const originalWrite = terminal.write;
+		this.hookedTerminal = terminal;
+		this.instanceOriginalWrite = originalWrite;
+		const gate = this;
+		terminal.write = (data: string): void => {
+			if (!gate.holding) {
+				originalWrite.call(terminal, data);
+				return;
+			}
+			gate.captureWrite(terminal, data);
+		};
+	}
+
+	/** 清屏和揭示必须绕过拦截，否则控制序列也会被持闸。 */
+	private writeThrough(data: string): void {
+		if (this.hookedTerminal && this.instanceOriginalWrite) {
+			this.instanceOriginalWrite.call(this.hookedTerminal, data);
+			return;
+		}
+		this.output.write(data);
+	}
+
+	isHolding(): boolean {
+		return this.holding;
+	}
+
+	hold(tui?: TUI, options: TransitionHoldOptions = {}): boolean {
+		if (!this.output.isTTY) return false;
+		if (this.holding) {
+			if (options.clearVisibleScreen) this.clearVisibleScreen(tui);
+			return true;
+		}
+
+		// 首次启动时隐藏宿主的未装饰帧；reload 时保留当前画面，最终帧会原位覆盖，
+		// 避免 Windows Terminal 把整屏清除前的内容留进回滚历史形成重复残影。
+		if (!this.hasVisibleFrame || options.clearVisibleScreen) {
+			this.writeThrough(CLEAR_VISIBLE_SCREEN);
+		}
+
+		this.holding = true;
+		this.heldWrites = [];
+		this.heldOutputBytes = 0;
+		this.armFailOpen();
+		this.startGuardTimer();
+		return true;
+	}
+
+	private startGuardTimer(): void {
+		if (this.guardTimer || this.hookedTerminal) return;
+		this.guardTimer = setInterval(() => {
+			if (!this.holding || this.hookedTerminal) {
+				this.stopGuardTimer();
+				return;
+			}
+			// 经 output 直写清屏：此时 hook 未挂，宿主 write 不经闸门。
+			this.output.write(CLEAR_VISIBLE_SCREEN);
+		}, GUARD_CLEAR_INTERVAL_MS);
+		this.guardTimer.unref?.();
+	}
+
+	private stopGuardTimer(): void {
+		if (!this.guardTimer) return;
+		clearInterval(this.guardTimer);
+		this.guardTimer = undefined;
+	}
+
+	private clearVisibleScreen(_tui?: TUI): void {
+		this.writeThrough(CLEAR_VISIBLE_SCREEN);
+	}
+
+	reveal(tui: TUI): boolean {
+		if (!this.holding) return false;
+
+		try {
+			// 闸门关闭期间仍让 Pi 完成一次内部渲染，随后直接揭示准备好的可见区。
+			tui.renderNow(false);
+			if (isMainScreenTui(tui)) {
+				const state = tui.captureRenderState();
+				if (canRedrawVisibleViewport(tui, state)) {
+					const height = tui.terminal.rows;
+					const maxViewportTop = Math.max(0, state.previousLines.length - height);
+					const top = Math.min(state.previousViewportTop, maxViewportTop);
+					const bottom = Math.min(state.previousLines.length, top + height);
+					tui.restoreRenderState({
+						...state,
+						hardwareCursorRow: Math.max(top, bottom - 1),
+					});
+					this.release(false);
+					const visibleLines = state.previousLines.slice(top, bottom);
+					this.writeThrough(
+						`${BEGIN_SYNCHRONIZED_OUTPUT}\x1b[H${visibleLines.join("\r\n")}\x1b[J${END_SYNCHRONIZED_OUTPUT}`,
+					);
+					this.hasVisibleFrame = true;
+					// 状态已经与最终帧一致；这一轮只让 Pi 恢复 IME 硬件光标。
+					tui.renderNow(false);
+					return true;
+				}
+			}
+
+			this.release(false);
+			tui.renderNow(true);
+			this.hasVisibleFrame = true;
+			return true;
+		} catch {
+			this.release(true);
+			try {
+				tui.renderNow(true);
+			} catch {
+				// 已回放被拦截的输出，不能再安全恢复时保持宿主当前终端状态。
+			}
+			return false;
+		}
+	}
+
+	release(replayHeldOutput = false): void {
+		if (!this.holding) return;
+		this.stopGuardTimer();
+		this.holding = false;
+		this.clearFailOpenTimer();
+		const heldWrites = this.heldWrites;
+		this.heldWrites = [];
+		this.heldOutputBytes = 0;
+		if (!replayHeldOutput) return;
+		// 已解除持闸，按捕获来源回放；换绑后的当前直写通道不再属于旧终端。
+		for (const held of heldWrites) {
+			held.terminal.write(held.data);
+		}
+	}
+
+	private captureWrite(terminal: TerminalWriteTarget, data: string): void {
+		this.heldWrites.push({ terminal, data });
+		this.heldOutputBytes += Buffer.byteLength(data);
+		if (this.heldOutputBytes > MAX_HELD_OUTPUT_BYTES) this.release(true);
+	}
+
+	private armFailOpen(): void {
+		this.clearFailOpenTimer();
+		this.failOpenTimer = setTimeout(() => this.release(true), FAIL_OPEN_AFTER_MS);
+		this.failOpenTimer.unref?.();
+	}
+
+	private clearFailOpenTimer(): void {
+		if (!this.failOpenTimer) return;
+		clearTimeout(this.failOpenTimer);
+		this.failOpenTimer = undefined;
+	}
+}
+
+export function getTerminalTransitionGate(
+	output: TransitionOutput = process.stdout,
+): TerminalTransitionGate {
+	const globalState = globalThis as typeof globalThis & Record<string, unknown>;
+	const existing = globalState[GLOBAL_GATE_KEY];
+	if (
+		existing !== null &&
+		typeof existing === "object" &&
+		"hold" in existing &&
+		typeof existing.hold === "function" &&
+		"reveal" in existing &&
+		typeof existing.reveal === "function" &&
+		"release" in existing &&
+		typeof existing.release === "function"
+	) {
+		const gate = existing as TerminalTransitionGate;
+		// jiti 会在 /reload 时载入新的模块实例，但全局闸门必须沿用同一份拦截状态。
+		// 把旧实例升级到当前原型，避免同一 Pi 进程一直执行上一个版本的方法。
+		Object.setPrototypeOf(gate, TerminalTransitionGate.prototype);
+		// 能复用全局实例说明当前进程已经展示过上一版插件界面；旧实例没有该字段。
+		if (typeof (gate as unknown as { hasVisibleFrame?: unknown }).hasVisibleFrame !== "boolean") {
+			(gate as unknown as { hasVisibleFrame: boolean }).hasVisibleFrame = true;
+		}
+		return gate;
+	}
+	const gate = new TerminalTransitionGate(output);
+	globalState[GLOBAL_GATE_KEY] = gate;
+	return gate;
+}

package/modules/tui/renderer/custom-header.ts

@@ -0,0 +1,157 @@
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { formatProjectPath } from "../status/project-status.ts";
+import type { IconGlyphs } from "./icons.ts";
+import {
+	PI_INSTALLER_LOGO_DURATIONS_MS,
+	PI_INSTALLER_LOGO_FRAMES,
+	PI_INSTALLER_LOGO_WIDTH,
+	type PiInstallerLogoFrame,
+	type PiLogoColor,
+} from "./pi-installer-logo.ts";
+
+/**
+ * 基于 amosblomqvist/pi-config 的 custom-header.ts 思路改造：
+ * 用 Pi 公开的 Header 组件绘制启动横幅，并保留本项目的宽度与主题适配。
+ * 参考：https://github.com/amosblomqvist/pi-config/blob/main/extensions/custom-header.ts
+ */
+
+const BANNER_MIN_WIDTH = 32;
+const BANNER_GAP = 1;
+const BANNER_PADDING_X = 1;
+export const CUSTOM_HEADER_LOGO_FRAMES = PI_INSTALLER_LOGO_FRAMES;
+export const CUSTOM_HEADER_ANIMATION_DURATIONS_MS = PI_INSTALLER_LOGO_DURATIONS_MS;
+
+const LOGO_THEME_COLORS: Record<PiLogoColor, ThemeColor | undefined> = {
+	panel: undefined,
+	cyan: "accent",
+	red: "error",
+	green: "success",
+	orange: "warning",
+	white: "text",
+	flash: "warning",
+};
+
+export interface CustomHeaderSnapshot {
+	version: string;
+	model: string;
+	thinking: string;
+	cwd: string;
+}
+
+function joinSides(left: string, right: string, width: number): string {
+	if (!right) return truncateToWidth(left, width);
+	const gap = width - visibleWidth(left) - visibleWidth(right);
+	if (gap >= 1) return `${left}${" ".repeat(gap)}${right}`;
+	return truncateToWidth(`${left} · ${right}`, width);
+}
+
+function joinColumns(
+	left: string,
+	right: string,
+	width: number,
+	leftColumnWidth = visibleWidth(left),
+): string {
+	const leftWidth = visibleWidth(left);
+	const availableRightWidth = width - leftColumnWidth - BANNER_GAP;
+	if (availableRightWidth < 1) return truncateToWidth(left, width);
+	const paddedLeft = `${left}${" ".repeat(Math.max(0, leftColumnWidth - leftWidth))}`;
+	return `${paddedLeft}${" ".repeat(BANNER_GAP)}${truncateToWidth(right, availableRightWidth)}`;
+}
+
+function renderLogoFrame(frame: PiInstallerLogoFrame, theme: Theme): string[] {
+	return frame.map((row) => {
+		let line = "";
+		let run = "";
+		let runColor: ThemeColor | undefined;
+
+		const flush = (): void => {
+			if (!run) return;
+			line += runColor ? theme.fg(runColor, run) : run;
+			run = "";
+		};
+
+		for (const cell of row) {
+			const color = LOGO_THEME_COLORS[cell];
+			if (color !== runColor && run) flush();
+			runColor = color;
+			// 对应官方安装器的 panel_cell="  " 与各色 cell="██"。
+			run += cell === "panel" ? "  " : "██";
+		}
+		flush();
+		return line.trimEnd();
+	});
+}
+
+function formatHeaderModel(model: string): string {
+	const separator = model.lastIndexOf("/");
+	return separator >= 0 ? model.slice(separator + 1) : model;
+}
+
+function alignRowsToBottom(rows: readonly string[], height: number): string[] {
+	const visibleRows = rows.slice(-height);
+	const leadingEmptyRows = height - visibleRows.length;
+	return Array.from({ length: height }, (_, index) => visibleRows[index - leadingEmptyRows] ?? "");
+}
+
+function renderCompactHeader(
+	snapshot: CustomHeaderSnapshot,
+	width: number,
+	theme: Theme,
+	glyphs: IconGlyphs,
+): string[] {
+	const brand = theme.bold(theme.fg("border", `${glyphs.brand} Pi Tui`));
+	const version = theme.fg("muted", `Pi v${snapshot.version}`);
+	const first = joinSides(brand, version, width);
+	if (width < 32) return [first];
+
+	const model = theme.fg("accent", `${glyphs.model} ${snapshot.model}`);
+	const thinking = snapshot.thinking
+		? theme.fg("muted", `${glyphs.thinking} ${snapshot.thinking}`)
+		: "";
+	const left = thinking ? `${model} · ${thinking}` : model;
+	const path = `${theme.fg("accent", glyphs.project)}${theme.fg(
+		"dim",
+		` ${formatProjectPath(snapshot.cwd)}`,
+	)}`;
+	return [first, joinSides(left, path, width)];
+}
+
+export function renderCustomHeader(
+	snapshot: CustomHeaderSnapshot,
+	width: number,
+	theme: Theme,
+	glyphs: IconGlyphs,
+	logoFrame: PiInstallerLogoFrame = CUSTOM_HEADER_LOGO_FRAMES.at(-1)!,
+): string[] {
+	if (width <= 0) return [];
+	const paddingX = width >= BANNER_PADDING_X * 2 + 1 ? BANNER_PADDING_X : 0;
+	const contentWidth = Math.max(1, width - paddingX * 2);
+	if (width < BANNER_MIN_WIDTH) {
+		const compact = renderCompactHeader(snapshot, contentWidth, theme, glyphs);
+		return compact.map((line) => `${" ".repeat(paddingX)}${line}`);
+	}
+
+	const logo = renderLogoFrame(logoFrame, theme).map((line) => theme.bold(line));
+	const logoWidth = PI_INSTALLER_LOGO_WIDTH;
+	const title = `${theme.bold(theme.fg("border", "Pi"))}${theme.fg("dim", ` v${snapshot.version}`)}`;
+	const modelName = formatHeaderModel(snapshot.model);
+	const modelDetails = snapshot.thinking ? `${modelName} · ${snapshot.thinking}` : modelName;
+	const model = theme.fg("dim", modelDetails);
+	const path = theme.fg("dim", formatProjectPath(snapshot.cwd));
+	const shortcuts = theme.fg(
+		"dim",
+		"Escape interrupt · Ctrl+C/Ctrl+D clear/exit · / commands · ! bash · Ctrl+O more",
+	);
+	const details = [
+		title,
+		model,
+		path,
+		shortcuts,
+	];
+	const alignedDetails = alignRowsToBottom(details, logo.length);
+
+	return logo.map(
+		(line, index) => `${" ".repeat(paddingX)}${joinColumns(line, alignedDetails[index] ?? "", contentWidth, logoWidth)}`,
+	);
+}

package/modules/tui/renderer/editor.ts

@@ -0,0 +1,70 @@
+import { stripTerminalSequences, visibleWidth } from "@earendil-works/pi-tui";
+
+function plainLine(line: string): string {
+	return stripTerminalSequences(line);
+}
+
+function isEditorBorder(line: string): boolean {
+	const plain = plainLine(line);
+	return /^─+$/.test(plain) || /^─── [↑↓] \d+ more (?:─+|\.{1,3})$/.test(plain);
+}
+
+function scrollLabel(line: string): string | undefined {
+	return plainLine(line).match(/[↑↓] \d+ more/)?.[0];
+}
+
+export function hasTruncatedScrollBorder(lines: readonly string[]): boolean {
+	return lines.some((line, index) => {
+		if (index !== 0 && index < 2) return false;
+		const plain = plainLine(line);
+		return plain.endsWith("...") && (/^─/.test(plain) || /[↑↓]/.test(plain));
+	});
+}
+
+function findBottomBorder(lines: readonly string[]): number {
+	for (let index = lines.length - 1; index >= 2; index -= 1) {
+		if (isEditorBorder(lines[index] ?? "")) return index;
+	}
+	return -1;
+}
+
+export function splitNativeEditorRender(lines: readonly string[]): {
+	editor: string[];
+	autocomplete: string[];
+} {
+	const bottomBorderIndex = findBottomBorder(lines);
+	if (bottomBorderIndex < 2) return { editor: [...lines], autocomplete: [] };
+	return {
+		editor: lines.slice(0, bottomBorderIndex + 1),
+		autocomplete: lines.slice(bottomBorderIndex + 1),
+	};
+}
+
+export interface TopBorderStatusOptions {
+	left: string;
+	borderColor: (text: string) => string;
+}
+
+/**
+ * 轻插入：Pi 原生上下横线边框保持原样，只在顶边左端嵌入状态文本。
+ * 顶边不是纯横线（滚动标签等原生动态形态）时原样返回，不与原生行为竞争。
+ */
+export function insertTopBorderStatus(
+	baseLines: readonly string[],
+	options: TopBorderStatusOptions,
+): string[] {
+	if (baseLines.length === 0) return [...baseLines];
+	const top = baseLines[0] ?? "";
+	const plain = plainLine(top);
+	if (!/^─+$/.test(plain)) return [...baseLines];
+
+	const segment = options.left ? ` ${options.left} ` : "";
+	const segmentWidth = visibleWidth(segment);
+	const lineWidth = visibleWidth(plain);
+	// 两侧至少各留两列横线；放不下时保持原生顶边
+	if (segmentWidth === 0 || segmentWidth > lineWidth - 4) return [...baseLines];
+
+	const fill = "─".repeat(lineWidth - segmentWidth - 2);
+	const decorated = `${options.borderColor("──")}${segment}${options.borderColor(fill)}`;
+	return [decorated, ...baseLines.slice(1)];
+}

package/modules/tui/renderer/header.ts

@@ -0,0 +1,72 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import {
+	CUSTOM_HEADER_ANIMATION_DURATIONS_MS,
+	CUSTOM_HEADER_LOGO_FRAMES,
+	renderCustomHeader,
+	type CustomHeaderSnapshot,
+} from "./custom-header.ts";
+import type { IconGlyphs } from "./icons.ts";
+
+export class PiTuiHeader implements Component {
+	private readonly getSnapshot: () => CustomHeaderSnapshot;
+	private readonly getTheme: () => Theme;
+	private readonly getGlyphs: () => IconGlyphs;
+	private readonly requestRender: () => void;
+	private animationFrame = 0;
+	private animationStopped = false;
+	private cancelAnimation: (() => void) | undefined;
+	private readonly scheduleTimeout: (callback: () => void, delayMs: number) => () => void;
+
+	constructor(
+		getSnapshot: () => CustomHeaderSnapshot,
+		getTheme: () => Theme,
+		getGlyphs: () => IconGlyphs,
+		requestRender: () => void = () => {},
+		// 为保持与 setTimeout 一致，注入调度器也须延后调用，并返回取消函数。
+		scheduleTimeout = (callback: () => void, delayMs: number): (() => void) => {
+			const timer = setTimeout(callback, delayMs);
+			return () => clearTimeout(timer);
+		},
+	) {
+		this.getSnapshot = getSnapshot;
+		this.getTheme = getTheme;
+		this.getGlyphs = getGlyphs;
+		this.requestRender = requestRender;
+		this.scheduleTimeout = scheduleTimeout;
+		this.scheduleNextAnimationFrame();
+	}
+
+	private scheduleNextAnimationFrame(): void {
+		if (this.animationStopped || this.animationFrame >= CUSTOM_HEADER_LOGO_FRAMES.length - 1) return;
+		this.cancelAnimation = this.scheduleTimeout(() => {
+			this.cancelAnimation = undefined;
+			this.animationFrame += 1;
+			this.requestRender();
+			this.scheduleNextAnimationFrame();
+		}, CUSTOM_HEADER_ANIMATION_DURATIONS_MS[this.animationFrame] ?? 80);
+	}
+
+	private stopAnimation(): void {
+		// 重绘回调可能同步 dispose，此时尚未安排下一帧，单靠取消定时器无法阻止续播。
+		this.animationStopped = true;
+		this.cancelAnimation?.();
+		this.cancelAnimation = undefined;
+	}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		return renderCustomHeader(
+			this.getSnapshot(),
+			width,
+			this.getTheme(),
+			this.getGlyphs(),
+			CUSTOM_HEADER_LOGO_FRAMES[this.animationFrame],
+		);
+	}
+
+	dispose(): void {
+		this.stopAnimation();
+	}
+}