@bachi/pi-coder 1.0.0

package/extensions/startup-logo/loaded-sections.test.ts

@@ -0,0 +1,257 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+	DETECT_WIDTH,
+	HIDDEN_SECTION_NAMES,
+	SECTION_PRUNER_KEY,
+	findLoadedResourcesContainer,
+	hideLoadedSections,
+	installHiddenSectionPruner,
+	isBlankLineComponent,
+	isHiddenSection,
+	pruneHiddenSections,
+	releaseHiddenSectionPruner,
+	sectionTitleOfLine,
+} from "./loaded-sections.ts";
+
+/** 最小可用的假组件 / 假容器：形状照着 pi-tui 的 Container / Text / Spacer 来。 */
+class FakeSection {
+	name: string;
+	constructor(name: string) {
+		this.name = name;
+	}
+	render(_width: number): string[] {
+		return [`\u001b[38;2;121;214;193m[${this.name}]\u001b[39m`, `  ${this.name} 的内容`, ""];
+	}
+}
+
+class FakeSpacer {
+	render(_width: number): string[] {
+		return [""];
+	}
+}
+
+class FakeText {
+	text: string;
+	constructor(text: string) {
+		this.text = text;
+	}
+	render(_width: number): string[] {
+		// pi-tui 的 Text 对空串返回空数组（不是 [""]），这里照抄这个细节
+		return this.text ? [this.text] : [];
+	}
+}
+
+class FakeContainer {
+	children: unknown[] = [];
+	addChild(child: unknown): void {
+		this.children.push(child);
+	}
+	render(width: number): string[] {
+		return this.children.flatMap((child) => (child as { render(w: number): string[] }).render(width));
+	}
+}
+
+/** 照 `showLoadedResources` 的顺序把一整份清单填进容器。 */
+function fillLoadedResources(container: FakeContainer, names: readonly string[] = ["Context", "Skills", "Prompts", "Extensions", "Themes"]): void {
+	container.addChild(new FakeSpacer()); // [Context] 前面那个额外空行
+	for (const name of names) {
+		container.addChild(new FakeSection(name));
+		container.addChild(new FakeSpacer());
+	}
+}
+
+const titlesIn = (container: FakeContainer): string[] =>
+	container.children
+		.map((child) => sectionTitleOfLine((child as FakeSection).render(80)[0]))
+		.filter((title): title is string => title !== undefined);
+
+test("sectionTitleOfLine：只认 `[Name]` 整行，ANSI 不参与", () => {
+	assert.equal(sectionTitleOfLine("\u001b[36m[Context]\u001b[39m"), "Context");
+	assert.equal(sectionTitleOfLine("  [Prompts]  "), "Prompts");
+	assert.equal(sectionTitleOfLine("[Skill conflicts]"), "Skill conflicts");
+	assert.equal(sectionTitleOfLine("[Context] 三个文件"), undefined);
+	assert.equal(sectionTitleOfLine("[[Context]]"), undefined);
+	assert.equal(sectionTitleOfLine(""), undefined);
+	assert.equal(sectionTitleOfLine(undefined), undefined);
+	assert.equal(sectionTitleOfLine(42), undefined);
+});
+
+test("isHiddenSection / isBlankLineComponent：只看第一行，渲染抛错只当「不是」", () => {
+	assert.equal(isHiddenSection(new FakeSection("Context")), true);
+	assert.equal(isHiddenSection(new FakeSection("Prompts")), true);
+	assert.equal(isHiddenSection(new FakeSection("Themes")), true);
+	assert.equal(isHiddenSection(new FakeSection("Skills")), false);
+	assert.equal(isHiddenSection(new FakeSection("Extensions")), false);
+	assert.equal(isHiddenSection(new FakeSpacer()), false);
+	assert.equal(isHiddenSection({ render: () => [{}, "x"] }), false);
+	assert.equal(
+		isHiddenSection({
+			render: () => {
+				throw new Error("boom");
+			},
+		}),
+		false,
+	);
+	assert.equal(isHiddenSection(undefined), false);
+	assert.equal(isBlankLineComponent(new FakeSpacer()), true);
+	assert.equal(isBlankLineComponent(new FakeText("")), false, "空 Text 渲染出 []，不是 spacer 形状");
+	assert.equal(isBlankLineComponent(new FakeSection("Skills")), false);
+	assert.equal(isBlankLineComponent({ render: () => [""] }), true);
+});
+
+test("addChild 接管：被隐藏的三段连同各自的分隔空行都进不去", () => {
+	const container = new FakeContainer();
+	assert.equal(installHiddenSectionPruner({ container }) !== undefined, true);
+	fillLoadedResources(container);
+
+	assert.deepEqual(titlesIn(container), ["Skills", "Extensions"]);
+	// 前面那个空行 + [Skills]、[Extensions] 各自的分隔空行
+	assert.equal(container.children.length, 5);
+	assert.deepEqual(container.children.map((child) => child instanceof FakeSpacer), [true, false, true, false, true]);
+});
+
+test("addChild 接管：非 `[x]` 形状、渲染抛错、非对象的 child 一律放行", () => {
+	const container = new FakeContainer();
+	installHiddenSectionPruner({ container });
+	const throwing = {
+		render: () => {
+			throw new Error("boom");
+		},
+	};
+	const plainText = new FakeText("[Context] 这三个文件");
+	container.addChild(throwing);
+	container.addChild(plainText);
+	container.addChild("裸字符串");
+	container.addChild(new FakeText(""));
+	assert.deepEqual(container.children, [throwing, plainText, "裸字符串", container.children[3]]);
+});
+
+test("addChild 接管：只有被剪掉的段才吃后面的空行，普通段后面照常", () => {
+	const container = new FakeContainer();
+	installHiddenSectionPruner({ container });
+	container.addChild(new FakeSection("Skills"));
+	container.addChild(new FakeSpacer());
+	container.addChild(new FakeSection("Prompts"));
+	container.addChild(new FakeSpacer());
+	container.addChild(new FakeSection("Extensions"));
+	assert.deepEqual(titlesIn(container), ["Skills", "Extensions"]);
+	assert.equal(container.children.length, 3);
+});
+
+test("pruneHiddenSections：装晚了（清单已填好）也能剪干净", () => {
+	const container = new FakeContainer();
+	fillLoadedResources(container);
+	assert.equal(container.children.length, 11); // 1 + 5×2
+	assert.equal(pruneHiddenSections(container), 3);
+	assert.deepEqual(titlesIn(container), ["Skills", "Extensions"]);
+	assert.equal(container.children.length, 5);
+});
+
+test("pruneHiddenSections：没有任何隐藏段时原样返回 0", () => {
+	const container = new FakeContainer();
+	fillLoadedResources(container, ["Skills", "Extensions"]);
+	const before = [...container.children];
+	assert.equal(pruneHiddenSections(container), 0);
+	assert.deepEqual(container.children, before);
+	assert.equal(pruneHiddenSections(undefined), 0);
+	assert.equal(pruneHiddenSections({}), 0);
+});
+
+test("installHiddenSectionPruner：装晚了先剪一遍已有内容，之后新加的也进不去", () => {
+	const container = new FakeContainer();
+	fillLoadedResources(container);
+	installHiddenSectionPruner({ container });
+	assert.deepEqual(titlesIn(container), ["Skills", "Extensions"]);
+	// /reload：clear() 之后重新填一份清单
+	container.children = [];
+	container.addChild(new FakeSpacer());
+	container.addChild(new FakeSection("Context"));
+	container.addChild(new FakeSpacer());
+	container.addChild(new FakeSection("Skills"));
+	assert.deepEqual(titlesIn(container), ["Skills"]);
+});
+
+test("接管幂等：重复安装不叠 wrapper，旧 release 不拆新 wrapper，release 后恢复原状", () => {
+	const container = new FakeContainer();
+	const release1 = installHiddenSectionPruner({ container });
+	assert.equal(typeof release1, "function");
+	const release2 = installHiddenSectionPruner({ container });
+	assert.equal(typeof release2, "function");
+
+	// 第二次安装已经顶掉了第一次：再调旧 release 也不能把新 wrapper 拆掉
+	release1!();
+	container.addChild(new FakeSection("Context"));
+	assert.deepEqual(titlesIn(container), [], "旧 release 不应动到新接管");
+
+	assert.equal(releaseHiddenSectionPruner(container), true);
+	release2!();
+	assert.equal(releaseHiddenSectionPruner(container), false);
+
+	// 解除之后新加的段不再被剪（等价于 pi-tui Container 的原始 addChild）
+	container.addChild(new FakeSection("Context"));
+	assert.deepEqual(titlesIn(container), ["Context"]);
+});
+
+test("接管记录挂在符号键上：别的实例能解除旧的接管", () => {
+	const container = new FakeContainer();
+	installHiddenSectionPruner({ container });
+	assert.equal(typeof (container as { [SECTION_PRUNER_KEY]?: unknown })[SECTION_PRUNER_KEY], "object");
+	// 模拟 /reload：新实例只拿到容器对象也要能清掉旧 wrapper
+	assert.equal(releaseHiddenSectionPruner(container), true);
+	assert.equal((container as { [SECTION_PRUNER_KEY]?: unknown })[SECTION_PRUNER_KEY], undefined);
+	const container2 = new FakeContainer();
+	assert.equal(releaseHiddenSectionPruner(container2), false);
+});
+
+test("findLoadedResourcesContainer：按 header 容器的下一个兄弟容器认，认不出返回 undefined", () => {
+	const headerContainer = new FakeContainer();
+	const loadedResources = new FakeContainer();
+	const chatContainer = new FakeContainer();
+	const document = new FakeContainer();
+	document.addChild(headerContainer);
+	document.addChild(loadedResources);
+	document.addChild(chatContainer);
+	const root = { children: [document] };
+
+	assert.equal(findLoadedResourcesContainer({ root, headerContainer }), loadedResources);
+	// header 容器自己不在树里 → 认不出
+	assert.equal(findLoadedResourcesContainer({ root, headerContainer: new FakeContainer() }), undefined);
+	assert.equal(findLoadedResourcesContainer({ root, headerContainer: undefined }), undefined);
+	// 兄弟不是容器形状 → 认不出
+	const oddHeader = new FakeContainer();
+	const oddDocument = new FakeContainer();
+	oddDocument.addChild(oddHeader);
+	oddDocument.addChild({ 不是容器: true });
+	assert.equal(findLoadedResourcesContainer({ root: { children: [oddDocument] }, headerContainer: oddHeader }), undefined);
+});
+
+test("hideLoadedSections：整条链路（找容器 → 接管 → 填清单）", () => {
+	const headerContainer = new FakeContainer();
+	const loadedResources = new FakeContainer();
+	const document = new FakeContainer();
+	document.addChild(headerContainer);
+	document.addChild(loadedResources);
+	const root = { children: [document] };
+
+	assert.equal(hideLoadedSections({ root, headerContainer }), true);
+	fillLoadedResources(loadedResources);
+	assert.deepEqual(titlesIn(loadedResources), ["Skills", "Extensions"]);
+
+	// 找不到容器时返回 false，什么都不改
+	assert.equal(hideLoadedSections({ root, headerContainer: new FakeContainer() }), false);
+	// 自定义隐藏名单
+	const other = new FakeContainer();
+	const otherHeader = new FakeContainer();
+	const otherDocument = new FakeContainer();
+	otherDocument.addChild(otherHeader);
+	otherDocument.addChild(other);
+	assert.equal(hideLoadedSections({ root: { children: [otherDocument] }, headerContainer: otherHeader, names: ["Skills"] }), true);
+	fillLoadedResources(other);
+	assert.deepEqual(titlesIn(other), ["Context", "Prompts", "Extensions", "Themes"]);
+});
+
+test("默认隐藏名单就是 Context / Prompts / Themes，判定宽度是个常规值", () => {
+	assert.deepEqual(HIDDEN_SECTION_NAMES, ["Context", "Prompts", "Themes"]);
+	assert.ok(DETECT_WIDTH >= 80, "标题行 `[Context]` 只有 9 列，判定宽度够宽就行");
+});

package/extensions/startup-logo/loaded-sections.ts

@@ -0,0 +1,267 @@
+/**
+ * loaded-sections.ts — 启动时把 `[Context]` / `[Prompts]` / `[Themes]` 三段从「已加载资源」清单里剪掉
+ *
+ * pi 启动后会在 header 下面打一份「已加载资源」清单（`interactive-mode.js` 的 `showLoadedResources`，
+ * 每段 = 一个 `ExpandableText` 标题行 + 一行内容 + 一个 `Spacer(1)`）：
+ * `[Context]`（AGENTS.md 等上下文文件）、`[Skills]`、`[Prompts]`（斜杠模板）、`[Extensions]`、`[Themes]`。
+ * 其中 `[Context]` / `[Prompts]` / `[Themes]` 对使用者没有信息量（前两个每次启动都一样、主题文件也没人会去数），
+ * 留着只是白占屏幕，所以这里在**它们进容器之前**就丢掉；`[Skills]` / `[Extensions]` 以及
+ * `[Skill conflicts]` 之类的诊断段全部原样保留。
+ *
+ * 为什么不用 pi 自己的 `quietStartup`：那个开关把**整份清单**（含 Skills / Extensions / 诊断）一起关掉，
+ * 这里要的只是剪掉三段。清单是 pi 在 `bindCurrentSessionExtensions()` 里 `session_start` **之后**才填的
+ * （`showLoadedResources` 紧跟 `await session.bindExtensions(...)`），所以扩展在 `session_start` 里
+ * 接管容器的 `addChild` 就赶得上：被隐藏的段一次都不会进容器，也就不存在「先画出来再抹掉」的闪帧。
+ *
+ * 怎么认出「已加载资源」那个容器：pi 的 `documentContainer` 固定按
+ * `[headerContainer, loadedResourcesContainer, chatContainer]` 顺序挂子节点（`interactive-mode.js`
+ * 构造函数），所以从**已挂载的 header 组件**反查出 header 容器（`findRenderContainer`），再往上找它的
+ * 父容器、取紧随其后的那个兄弟容器即可。认不出就**什么都不做**（清单照旧显示），不猜下标、不抛错。
+ *
+ * 判定与剪枝都是内容驱动的，跟容器认的是谁无关：只有「渲染出来的第一行恰好是 `[Context]` / `[Prompts]` /
+ * `[Themes]`」的组件才会被丢，所以万一 pi 挪了容器位置、我们摸到了别的容器（例如 chatContainer），
+ * 最多是白接管一次，不会误删别的东西。任何一步抛错都当作「不是要剪的段」，一律放行。
+ *
+ * 全部是纯逻辑（容器只要求 `children` 数组 + `addChild`），不 import pi / pi-tui，`node --test` 直接跑。
+ */
+
+/** 要剪掉的段名（与 pi 的 `addLoadedSection("Context"…)` 逐字一致，大小写敏感）。 */
+export const HIDDEN_SECTION_NAMES: readonly string[] = ["Context", "Prompts", "Themes"];
+
+/** 接管记录挂在容器上的符号键（全局符号注册表：`/reload` 后的新实例能看到并解除旧实例的接管）。 */
+export const SECTION_PRUNER_KEY: symbol = Symbol.for("litellm-any.pi-startup-logo.sectionPruner");
+
+/**
+ * 判定用的渲染宽度。标题行只有 `[Context]` 这么长（9 列），远小于任何终端宽度，不会因折行而认不出；
+ * 取一个固定值是因为 `addChild` 那一刻还不知道真实宽度（`render` 才带宽度）。
+ */
+export const DETECT_WIDTH = 200;
+
+/** pi-tui `Container` 里本模块用到的那部分结构（`children` / `addChild` 都是公开的）。 */
+export interface PrunableContainer {
+	children: unknown[];
+	addChild?(child: unknown): void;
+	render?(width: number): string[];
+}
+
+interface PrunerRecord {
+	release: () => void;
+}
+
+const ANSI_PATTERN = /\u001b\[[0-9;]*m/g;
+
+/** 组件渲染出来的第一行（原样返回，可能是 undefined / 非字符串）。 */
+function firstRenderedLine(component: unknown, width: number): unknown {
+	try {
+		if (component === null || typeof component !== "object") return undefined;
+		const render = (component as { render?: unknown }).render;
+		if (typeof render !== "function") return undefined;
+		const lines = (render as (w: number) => unknown).call(component, width);
+		if (!Array.isArray(lines) || lines.length === 0) return undefined;
+		return lines[0];
+	} catch {
+		return undefined;
+	}
+}
+
+/** 剥掉 ANSI、去掉首尾空白后，这一行是不是 `[Name]` 形状；是就返回名字。 */
+export function sectionTitleOfLine(line: unknown): string | undefined {
+	if (typeof line !== "string") return undefined;
+	const plain = line.replace(ANSI_PATTERN, "").trim();
+	// 名字里可以带空格（`[Skill conflicts]` 这种诊断段），但不允许嵌套方括号。
+	const match = /^\[([^[\]]+)\]$/.exec(plain);
+	const title = match?.[1].trim();
+	return title ? title : undefined;
+}
+
+/** 这个组件的第一行是不是某个被隐藏的段标题。 */
+export function isHiddenSection(
+	component: unknown,
+	names: readonly string[] = HIDDEN_SECTION_NAMES,
+	width: number = DETECT_WIDTH,
+): boolean {
+	const title = sectionTitleOfLine(firstRenderedLine(component, width));
+	return title !== undefined && names.includes(title);
+}
+
+/** 这个组件是不是「一行空行」——`addLoadedSection` 每段后面那个 `Spacer(1)` 就是这个形状。 */
+export function isBlankLineComponent(component: unknown, width: number = DETECT_WIDTH): boolean {
+	try {
+		if (component === null || typeof component !== "object") return false;
+		const render = (component as { render?: unknown }).render;
+		if (typeof render !== "function") return false;
+		const lines = (render as (w: number) => unknown).call(component, width);
+		return Array.isArray(lines) && lines.length === 1 && lines[0] === "";
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * 把 `container` 里现有的隐藏段（连同它后面那个分隔空行）直接删掉，返回删掉的段数。
+ *
+ * 正常路径用不到它（`addChild` 接管在前面就拦住了），留着是为了「接管装晚了」的情况 ——
+ * 例如 `/reload` 之后清单已经填好才轮到新实例。
+ */
+export function pruneHiddenSections(
+	container: unknown,
+	names: readonly string[] = HIDDEN_SECTION_NAMES,
+	width: number = DETECT_WIDTH,
+): number {
+	const target = container as PrunableContainer | undefined;
+	if (!target || !Array.isArray(target.children)) return 0;
+	const children = target.children;
+	let removed = 0;
+	// 倒着走：删掉下标 i 之后，原 i+1（紧跟的空行）正好落到 i 上。
+	for (let i = children.length - 1; i >= 0; i--) {
+		if (!isHiddenSection(children[i], names, width)) continue;
+		try {
+			children.splice(i, 1);
+			removed++;
+			if (i < children.length && isBlankLineComponent(children[i], width)) children.splice(i, 1);
+		} catch {
+			// 数组只读之类：能删多少算多少，不再往下试。
+			break;
+		}
+	}
+	return removed;
+}
+
+/** 解除 `container` 上现有的接管（可能是别的扩展实例遗留的）。返回是否解掉了什么。 */
+export function releaseHiddenSectionPruner(container: unknown): boolean {
+	try {
+		const record = (container as { [SECTION_PRUNER_KEY]?: PrunerRecord } | undefined)?.[SECTION_PRUNER_KEY];
+		if (!record || typeof record.release !== "function") return false;
+		record.release();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function isPrunableContainer(value: unknown): value is PrunableContainer {
+	return (
+		value !== null &&
+		typeof value === "object" &&
+		Array.isArray((value as PrunableContainer).children) &&
+		typeof (value as PrunableContainer).addChild === "function"
+	);
+}
+
+/**
+ * 接管 `container.addChild`：隐藏段（以及它后面那个分隔空行）直接不放进去，其余一律透传。
+ * 返回解除函数（幂等）；容器不可用时返回 undefined。
+ *
+ * 幂等：重复调用先解除上一次接管再装新的，不会叠 wrapper；`/reload` 后新实例能解除旧实例的接管。
+ */
+export function installHiddenSectionPruner(options: {
+	container: unknown;
+	names?: readonly string[];
+	width?: number;
+}): (() => void) | undefined {
+	if (!isPrunableContainer(options.container)) return undefined;
+	const container = options.container;
+	releaseHiddenSectionPruner(container);
+
+	const names = options.names ?? HIDDEN_SECTION_NAMES;
+	const width = options.width ?? DETECT_WIDTH;
+	// 装晚了（清单已经填好）时先把现有的剪掉。
+	pruneHiddenSections(container, names, width);
+
+	const originalAddChild = container.addChild!;
+	const state: { released: boolean; record?: PrunerRecord } = { released: false };
+	let dropNextBlank = false;
+
+	const release = (): void => {
+		if (state.released) return;
+		state.released = true;
+		try {
+			const holder = container as { [SECTION_PRUNER_KEY]?: PrunerRecord };
+			// 已经被别的实例的新接管顶掉：只管让自己的 wrapper 失效，别去拆新的那个。
+			if (state.record && holder[SECTION_PRUNER_KEY] !== state.record) return;
+			delete holder[SECTION_PRUNER_KEY];
+			container.addChild = originalAddChild;
+		} catch {
+			// 容器只读 / 已被替换：wrapper 自己会因 released 标志透传。
+		}
+	};
+
+	const wrapper = (child: unknown): void => {
+		if (state.released) {
+			originalAddChild.call(container, child);
+			return;
+		}
+		try {
+			if (isHiddenSection(child, names, width)) {
+				// 段后面紧跟的就是它自己的 Spacer(1)，一起收掉，免得留下多余空行。
+				dropNextBlank = true;
+				return;
+			}
+			if (dropNextBlank) {
+				dropNextBlank = false;
+				if (isBlankLineComponent(child, width)) return;
+			}
+		} catch {
+			// 判定失败：按普通 child 放行。
+		}
+		originalAddChild.call(container, child);
+	};
+
+	try {
+		container.addChild = wrapper;
+		state.record = { release };
+		(container as { [SECTION_PRUNER_KEY]?: PrunerRecord })[SECTION_PRUNER_KEY] = state.record;
+	} catch {
+		return undefined;
+	}
+	return release;
+}
+
+/**
+ * 在 `root` 的子树里找「直接装着 `headerContainer` 的那个容器」，再取它**后面**那个兄弟容器 ——
+ * 就是 pi 的 `loadedResourcesContainer`。认不出返回 undefined。
+ */
+export function findLoadedResourcesContainer(options: {
+	root: unknown;
+	headerContainer: unknown;
+	maxDepth?: number;
+}): PrunableContainer | undefined {
+	const { root, headerContainer } = options;
+	if (!headerContainer) return undefined;
+	const maxDepth = options.maxDepth ?? 6;
+	const seen = new Set<unknown>();
+
+	const walk = (node: unknown, depth: number): unknown => {
+		if (depth > maxDepth || node === null || typeof node !== "object" || seen.has(node)) return undefined;
+		seen.add(node);
+		const children = (node as { children?: unknown }).children;
+		if (!Array.isArray(children)) return undefined;
+		const index = children.indexOf(headerContainer);
+		if (index >= 0) return children[index + 1];
+		for (const child of children) {
+			const found = walk(child, depth + 1);
+			if (found !== undefined) return found;
+		}
+		return undefined;
+	};
+
+	try {
+		const sibling = walk(root, 0);
+		return isPrunableContainer(sibling) ? sibling : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * 找到「已加载资源」容器并装上剪枝接管。返回是否装上了（找不到容器 / 容器形状不对 → false，界面照旧）。
+ */
+export function hideLoadedSections(options: {
+	root: unknown;
+	headerContainer: unknown;
+	names?: readonly string[];
+}): boolean {
+	const container = findLoadedResourcesContainer({ root: options.root, headerContainer: options.headerContainer });
+	if (!container) return false;
+	return installHiddenSectionPruner({ container, names: options.names }) !== undefined;
+}

package/extensions/startup-logo/logo.test.ts

@@ -0,0 +1,124 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+	MARK_BLANK,
+	MARK_CELL,
+	MARK_COLS,
+	MARK_GLYPH_WIDTH,
+	MARK_INDENT,
+	MARK_ROWS,
+	MARK_WIDTH,
+	attachSideText,
+	composeHeaderLines,
+	markCellFilled,
+	markLines,
+	shortenPath,
+} from "./logo.ts";
+
+/** 去掉 ANSI，只看几何。 */
+const plain = (line: string): string => line.replace(/\u001b\[[0-9;]*m/g, "");
+
+test("印记是 4×4 格子，本体宽 12、左侧留白一格所以整行 13", () => {
+	assert.equal(MARK_CELL, "███");
+	assert.equal(MARK_BLANK, "   ");
+	assert.equal(MARK_INDENT, " ");
+	assert.equal(MARK_ROWS, 4);
+	assert.equal(MARK_COLS, 4);
+	assert.equal(MARK_GLYPH_WIDTH, 12);
+	assert.equal(MARK_WIDTH, MARK_INDENT.length + MARK_GLYPH_WIDTH);
+	assert.equal(MARK_WIDTH, 13);
+});
+
+test("markLines 的四行形状（含补回来的那一格）与左侧留白", () => {
+	assert.deepEqual(markLines(), [
+		" █████████   ", // 上横：三格实心
+		" ███   ███   ", // 左竖 + 右腿上身
+		" ██████   ███", // 左竖 + 内衬 + 右腿（上游落定帧漏掉的 (5,5)）
+		" ███      ███", // 左竖 + 右腿脚
+	]);
+	for (const line of markLines()) {
+		assert.ok(line.startsWith(MARK_INDENT), "每行都要顶一个空格，不能贴左边缘");
+		assert.equal(line.length, MARK_WIDTH, "每行可见宽度必须一致，否则侧栏歪");
+	}
+});
+
+test("markCellFilled 与格子表一致，越界当空格", () => {
+	markLines().forEach((line, row) => {
+		for (let col = 0; col < MARK_COLS; col++) {
+			assert.equal(
+				markCellFilled(row, col),
+				line.slice(MARK_INDENT.length + col * 3, MARK_INDENT.length + col * 3 + 3) === MARK_CELL,
+				`(${row},${col}) 取色与整行渲染不一致`,
+			);
+		}
+	});
+	assert.equal(markCellFilled(9, 9), false);
+	assert.equal(markCellFilled(-1, 0), false);
+});
+
+test("右腿不是悬空的一只脚（回归：上游 phase 6 少了 (2,3) 那格）", () => {
+	// 最后一行最右格实心 → 它上一行最右格也必须实心，否则腿断了
+	assert.equal(markCellFilled(MARK_ROWS - 1, MARK_COLS - 1), true);
+	assert.equal(markCellFilled(MARK_ROWS - 2, MARK_COLS - 1), true);
+});
+
+test("attachSideText：两条侧栏落在第 1、2 行，其余行原样等宽", () => {
+	const out = attachSideText(markLines().map((l) => `[${l}]`), ["V", "C"]);
+	assert.equal(out.length, MARK_ROWS);
+	assert.equal(out[1], `[${markLines()[1]}]  V`);
+	assert.equal(out[2], `[${markLines()[2]}]  C`);
+	assert.equal(out[0], `[${markLines()[0]}]`);
+	assert.equal(out[3], `[${markLines()[3]}]`);
+});
+
+test("attachSideText：ANSI 不参与列计算", () => {
+	const colored = markLines().map((l) => `\x1b[38;2;121;214;193m${l}\x1b[39m`);
+	const out = attachSideText(colored, ["A", "B"]);
+	// 挂侧栏的行：剥掉 ANSI 后，侧栏前正好是整行宽度 + 2 空格
+	for (const [i, text] of [
+		[1, "A"],
+		[2, "B"],
+	] as const) {
+		const stripped = plain(out[i]!);
+		assert.equal(stripped, `${markLines()[i]}  ${text}`);
+		assert.equal(stripped.indexOf(text), MARK_WIDTH + 2);
+	}
+	// 没挂侧栏的行仍是完整等宽
+	assert.equal(plain(out[0]!), " █████████   ");
+	assert.equal(plain(out[0]!).length, MARK_WIDTH);
+});
+
+test("attachSideText：侧栏为空 / 比行数多 / 行数为 0 都不炸", () => {
+	const lines = markLines();
+	assert.deepEqual(attachSideText(lines, []), [...lines]);
+	assert.equal(attachSideText(lines, ["a", "b", "c", "d", "e"]).length, MARK_ROWS);
+	assert.deepEqual(attachSideText([], ["a"]), []);
+	// 空字符串那条不占位：只有一行被贴字，其余保持等宽
+	const blanked = attachSideText(lines, ["", "only"]);
+	assert.equal(blanked.filter((l) => l.endsWith("only")).length, 1);
+	assert.equal(blanked.filter((l) => l.endsWith("only") && l !== blanked[blanked.findIndex((x) => x.endsWith("only"))]).length, 0);
+});
+
+test("每行可见宽度恒等于 MARK_WIDTH（挂不挂侧栏的行都等宽，侧栏列才不会歪）", () => {
+	for (const line of markLines()) assert.equal(plain(line).length, MARK_WIDTH);
+	for (const line of markLines((f) => (f ? `\x1b[31m${MARK_CELL}\x1b[39m` : MARK_BLANK))) {
+		assert.equal(plain(line).length, MARK_WIDTH);
+	}
+});
+
+test("composeHeaderLines：段之间恰好一个空行，缺段不留空行", () => {
+	assert.deepEqual(composeHeaderLines({ logo: ["a", "b"], hints: "h", onboarding: "o" }), ["a", "b", "", "h", "", "o"]);
+	assert.deepEqual(composeHeaderLines({ logo: ["a"], hints: "h" }), ["a", "", "h"]);
+	assert.deepEqual(composeHeaderLines({ logo: [], hints: "h", onboarding: "o" }), ["h", "", "o"]);
+	assert.deepEqual(composeHeaderLines({ logo: [] }), []);
+	assert.deepEqual(composeHeaderLines({ logo: [], onboarding: "o" }), ["o"]);
+});
+
+test("shortenPath：家目录内缩写，外面原样", () => {
+	assert.equal(shortenPath("/Users/bachi", "/Users/bachi"), "~");
+	assert.equal(shortenPath("/Users/bachi/jaylli/litellm-any", "/Users/bachi"), "~/jaylli/litellm-any");
+	assert.equal(shortenPath("/tmp/x", "/Users/bachi"), "/tmp/x");
+	// 同前缀但不同目录（/Users/bachix）不能被当成子路径缩写
+	assert.equal(shortenPath("/Users/bachix", "/Users/bachi"), "/Users/bachix");
+	assert.equal(shortenPath("/srv/app", undefined), "/srv/app");
+});