@bismawy/pi-arnative 0.3.5 → 0.3.7

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.3.7] - 2026-10-05
+
+### Fixed
+- The `powershell` and `ls` tools now render in the arnative box like every other call. pi draws a tool that ships its own `renderCall`/`renderResult` but sets no `renderShell` through its own `contentBox` — a background block with no border. Both tools match that shape (their definitions spread the renderer functions onto the tool object), so they now go through `minimal()` like `bash`/`grep`/`read`. `powershell` is Windows-only: `getPowerShellConfig()` throws elsewhere, and re-registering it would activate a tool the builtin deliberately leaves off (`extensions/tools.ts`).
+- pi-fff's default-mode tools `ffgrep` and `fffind` are boxed too. The box path only recognized the override names `find`/`grep`, which pi-fff uses when it replaces pi's builtins, so a session running it in default mode showed those calls as bare blocks (`extensions/tools.ts`).
+- pi's `[Extension issues]` diagnostic now draws in the arnative box, stripped to two content rows: the title (warning glyph + section name, brackets dropped, `[ctrl+o to expand]` hint) over the extension's source path. pi's extra diagnostic lines are dropped — the expand hint stands in for them (`extensions/section-headers.ts`).
+- The package-update box title lost the double space after its glyph (`extensions/ui-render-tweaks.ts`).
+
+### Changed
+- The `section-headers.ts` self-check moved out of the extension into `test/section-headers.test.ts` and runs under `node --test`, so `npm test` lists it as a test instead of a script that prints `OK`. This is a pilot for the other modules; the remaining in-file self-checks follow the same layout once proven (`extensions/section-headers.ts`, `test/section-headers.test.ts`, `package.json`).
+
+## [0.3.6] - 2026-10-05
+
+### Fixed
+- Fixed a startup crash: `Cannot read properties of null (reading 'fg')`. pi's `[Extension issues]` diagnostic box passed a null theme into the box renderer, which dereferenced it and killed the process with `uncaughtException`. It only surfaced on machines where an extension reported a problem (a conflicting shortcut, a failed `session_start`, …), because that is when the diagnostic is drawn. The renderer now draws an uncolored box for the first frame instead of throwing (`lib/box.ts`).
+- The active theme now lives in a single `globalThis` slot. `/reload` re-imports extension modules, so two copies can coexist, and only one of them receives `session_start`. The copy that owns the `loadedResourcesContainer` patch used to keep a permanently-null theme; it now paints with the live theme (`lib/ansi.ts`, `extensions/section-headers.ts`, `extensions/ui-render-tweaks.ts`).
+- Removed the `activeThemeProxy ?? Theme` fallback in the package-update box: `Theme` is a class, not an instance, so the fallback would itself have thrown `th.fg is not a function`. The box component now tolerates a null theme (`extensions/ui-render-tweaks.ts`).
+
 ## [0.3.5] - 2026-10-04
 
 ### Fixed

package/extensions/section-headers.ts

@@ -11,9 +11,9 @@
  * - Box divider '├────┤'. Active tab content is left-aligned, wrapped, soft.
  * - Hides pi's built-in stacked list in loadedResourcesContainer.
  */
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { readFileSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { tmpdir, userInfo } from "node:os";
+import { userInfo } from "node:os";
 import { join } from "node:path";
 import {
 	UserMessageComponent,
@@ -30,12 +30,12 @@ import {
 	type TuiMouseEvent,
 	type TuiMouseEventResult,
 } from "@earendil-works/pi-tui";
+import type { BoxTheme } from "../lib/box.ts";
 import { renderBoxLines } from "../lib/box.ts";
-import { stripAnsi, themeOf } from "../lib/ansi.ts";
-import { assert, isMain } from "../lib/check.ts";
-import { capitalize, markedLabels, modelDisplayParts } from "../lib/format.ts";
+import { getActiveTheme, setActiveTheme, stripAnsi, themeOf } from "../lib/ansi.ts";
+import { capitalize, expandKeyName, modelDisplayParts } from "../lib/format.ts";
 import { SHORTCUT_NEW_SESSION, SHORTCUT_NEXT_TAB, SHORTCUT_RELOAD } from "../lib/shortcuts.ts";
-import { HEADER_PRESET_KEY as HEADER_PRESET_CONFIG_KEY, loadChoice, resetPresetCache, saveChoice } from "../lib/preset-store.ts";
+import { HEADER_PRESET_KEY as HEADER_PRESET_CONFIG_KEY, loadChoice, saveChoice } from "../lib/preset-store.ts";
 import { formatTokens, getModelAllTimeUsage } from "../lib/usage-store.ts";
 
 export type TabKey = "Model" | "Directory" | "Context" | "Skills" | "Extensions" | "Shortcut";
@@ -52,9 +52,10 @@ export const SECTION_ICONS: Record<TabKey, string> = {
 	Shortcut: "\uf11c", // nf-fa-keyboard_o
 };
 
-export type Themeish = { fg?(color: string, text: string): string; bg?(color: string, text: string): string } | null;
+// nf-cod-warning, width 1 — prefixes a pi diagnostic block's compact header.
+const DIAGNOSTIC_ICON = "\uea6c";
 
-let activeThemeProxy: Themeish = null;
+export type Themeish = { fg?(color: string, text: string): string; bg?(color: string, text: string): string } | null;
 
 const MODEL_SNAPSHOT_KEY = Symbol.for("pi-arnative.currentModel");
 const THINKING_SNAPSHOT_KEY = Symbol.for("pi-arnative.currentThinking");
@@ -474,7 +475,7 @@ export class ArnativeHeader implements Component {
 		if (width < 36) {
 			return [centerLine(`pi v${VERSION}`, width)];
 		}
-		const th = this.themeProxy || (activeThemeProxy as Themeish);
+		const th = this.themeProxy || getActiveTheme<Themeish>();
 		const side = fgFirst(th, ["dim"], "│");
 
 		const infoLines: string[] = [];
@@ -646,6 +647,30 @@ export class ArnativeHeader implements Component {
 	}
 }
 
+// Arnative box for pi's `[Extension issues]` diagnostic: exactly two rows, the title
+// (warning icon + section name, brackets dropped, + expand hint) over the extension's
+// source path. pi's extra diagnostic lines are dropped — the expand hint stands in for
+// them. Uses only `warning` + `dim`, both defined by every pi theme, so it draws the
+// same under any theme; `rows` is pi's own render output, row 0 being the title.
+export function extensionIssuesLines(th: BoxTheme | null, width: number, rows: string[], hint: string): string[] {
+	const paint = (color: string, text: string) => {
+		try {
+			return th?.fg ? th.fg(color, text) : text;
+		} catch {
+			return text;
+		}
+	};
+	// Rows are plain text: ANSI inside would break the width math of renderBoxLines.
+	const title = stripAnsi(rows[0] ?? "").trim().replace(/^\[(.+)\]$/, "$1");
+	const hintPlain = stripAnsi(hint).trim();
+	const detail = stripAnsi(rows[1] ?? "").trim();
+	const header = `${paint("warning", `${DIAGNOSTIC_ICON} ${title}`)}${hintPlain ? `  ${paint("dim", hintPlain)}` : ""}`;
+	return renderBoxLines(th, width, [header, detail], undefined, "warning");
+}
+
+// Hooks the shared `app.tools.expand` key: `ctrl+o to expand` -> `[ctrl+o to expand]`.
+const wrapHint = (key: string): string => `[${key} to expand]`;
+
 // Intercept loadedResourcesContainer: capture data for the tabs and hide pi's own display
 const SECTION_HEADER_KEY = Symbol.for("pi-arnative.sectionHeadersRewritten");
 if (UserMessageComponent?.prototype && !(globalThis as Record<symbol, boolean>)[SECTION_HEADER_KEY]) {
@@ -689,7 +714,11 @@ if (UserMessageComponent?.prototype && !(globalThis as Record<symbol, boolean>)[
 					const text = themedTextOf(child);
 					if (text.includes("[Extension issues]") && typeof child.render === "function") {
 						const origRender = child.render.bind(child);
-						child.render = (w: number) => renderBoxLines(activeThemeProxy, w, origRender(w), undefined, "warning");
+						// Shortcut hint only when the shortcut registry is reachable; otherwise just the
+						// two-line compact block.
+						const rawHint = wrapHint(expandKeyName());
+						child.render = (w: number) =>
+							extensionIssuesLines(getActiveTheme<BoxTheme>(), w, origRender(w), rawHint);
 						return origAddChild.call(this, child);
 					}
 					// Any other element inside loadedResourcesContainer (e.g. Spacer) is hidden too
@@ -729,7 +758,9 @@ export default function (pi: ExtensionAPI) {
 		}
 		resourcesListingShown(quiet === false);
 		for (const key of ["Context", "Skills", "Extensions"] as const) tabStore.set(key, []);
-		activeThemeProxy = themeOf<Themeish>(ctx) ?? activeThemeProxy;
+		// A context without a theme (project-trust prompt) must not drop the one we have.
+		const th = themeOf<Themeish>(ctx);
+		if (th) setActiveTheme(th);
 		// Register the header for the active preset
 		applyHeaderPreset(ctx);
 	});
@@ -748,324 +779,3 @@ export default function (pi: ExtensionAPI) {
 		}
 	});
 }
-
-// Self-check: `node extensions/section-headers.ts`
-if (isMain(import.meta.url)) {
-
-	assert(sectionNameOf("\x1b[33m[Skills]\x1b[39m\n  a, b") === "Skills", "header [Skills] detected");
-	assert(sectionNameOf("pi v0.87.1") === null, "non-section text is not detected");
-
-	// Header presets: Arnative (Full) is the default; Pi (system) hands the header slot back to pi.
-	assert(DEFAULT_HEADER_PRESET === "Arnative (Full)" && HEADER_PRESETS.length === 2, "Arnative (Full) is the default header preset");
-	assert(HEADER_PRESETS.join(" | ") === "Pi (system) | Arnative (Full)", "built-in preset is listed first");
-	assert(markedLabels(HEADER_PRESETS, "Arnative (Full)").join(" | ") === "  Pi (system) | ● Arnative (Full)", "preset labels mark the active one");
-	// Persisting a preset writes a config file: point it at a fixture so the real agent dir stays clean.
-	const presetFixture = mkdtempSync(join(tmpdir(), "arnative-hdr-"));
-	const prevAgentDir = process.env.PI_CODING_AGENT_DIR;
-	process.env.PI_CODING_AGENT_DIR = presetFixture;
-	resetPresetCache();
-	let installed: unknown = "untouched";
-	const presetCtx: any = { ui: { setHeader: (factory: unknown) => { installed = factory; } } };
-	setHeaderPreset("Pi (system)", presetCtx);
-	assert(installed === undefined && activeHeaderPreset() === "Pi (system)", "Pi (system) clears the custom header");
-	setHeaderPreset("Arnative (Full)", presetCtx);
-	assert(typeof installed === "function" && activeHeaderPreset() === "Arnative (Full)", "Arnative (Full) installs the header factory");
-	// Persist a NON-default value: asserting the default survives proves nothing.
-	setHeaderPreset("Pi (system)", presetCtx);
-	assert(loadChoice(HEADER_PRESET_CONFIG_KEY, HEADER_PRESETS) === "Pi (system)", "the header preset is persisted to disk");
-	delete (globalThis as Record<symbol, unknown>)[HEADER_PRESET_KEY];
-	resetPresetCache();
-	assert(activeHeaderPreset() === "Pi (system)", "a restart reads the non-default preset back from disk");
-	rmSync(presetFixture, { recursive: true, force: true });
-	if (prevAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
-	else process.env.PI_CODING_AGENT_DIR = prevAgentDir;
-	resetPresetCache();
-
-	// Parsing & wrapping
-	assert(extractItemsFromBody("  a, b, c").length === 3, "extractItemsFromBody splits 3 comma items");
-	assert(extractItemsFromBody("  x\n  y\n  z").length === 3, "extractItemsFromBody returns 3 lines");
-
-	// Directory path wrapping: never truncated, always the full path
-	const wp = wrapPath("/run/media/bisma/DATA/Pi/pi-arnative", 20);
-	assert(wp.join("") === "/run/media/bisma/DATA/Pi/pi-arnative", "wrapPath drops no segment");
-	assert(wp.every((l) => visibleWidth(l) <= 20), "wrapPath respects the width");
-	assert(wrapPath("D:\\Pi\\pi-arnative", 80).join("") === "D:/Pi/pi-arnative", "wrapPath normalizes backslashes");
-	assert(wrapPath("/a/very-long-segment-name", 6).every((l) => visibleWidth(l) <= 6), "long segment is sliced");
-
-	const wrapTest = wrapCommaItems(["item1", "item2", "item3", "item4"], 15);
-	assert(wrapTest.length >= 2, "wrapCommaItems wraps into lines");
-	assert(visibleWidth(wrapTest[0]!) <= 15, "wrapped line width within the limit");
-
-	const cLine = centerLine("test", 20);
-	assert(visibleWidth(cLine) === 20, "centerLine is exactly 20 columns");
-	assert(cLine.startsWith("│") && cLine.endsWith("│"), "centerLine starts and ends with │");
-
-	// Model name formatting
-	assert(
-		formatModelDisplayName({ name: "Gemini 3.8 Flash", provider: "antigravity" }) ===
-			"Gemini 3.8 Flash (Antigravity)",
-		"formatModelDisplayName with name and provider",
-	);
-	assert(
-		formatModelDisplayName({ id: "deepseek-v4.1-flash", provider: "yarz" }) ===
-			"Deepseek V4.1 Flash (Yarz)",
-		"formatModelDisplayName converts id to titlecase",
-	);
-
-	// Package & version resolver
-	assert(packageNameOf("@bismawy/pi-agentrouter") === "@bismawy/pi-agentrouter", "plain npm label");
-	assert(packageNameOf("footer.ts") === "footer.ts", "local label");
-
-	const gitTmp = mkdtempSync(join(tmpdir(), "pi-ver-"));
-	mkdirSync(join(gitTmp, "git", "github.com", "test/arnative"), { recursive: true });
-	writeFileSync(join(gitTmp, "git", "github.com", "test/arnative", "package.json"), JSON.stringify({ version: "9.9.9" }));
-	assert(installedVersion("test/arnative", join(gitTmp, "npm"), join(gitTmp, "git")) === "9.9.9", "version from the git clone");
-	rmSync(gitTmp, { recursive: true, force: true });
-
-	// ArnativeHeader component & mouse tab click
-	tabStore.set("Context", ["AGENTS.md"]);
-	tabStore.set("Skills", ["agents-sdk", "cloudflare"]);
-	tabStore.set("Extensions", ["@bismawy/pi-agentrouter@1.6.1", "footer.ts"]);
-
-	let renderRequested = false;
-	const fakeTui: any = {
-		requestRender: () => {
-			renderRequested = true;
-		},
-	};
-	const fakeCtx: any = {
-		model: { name: "Gemini 3.8 Flash", provider: "antigravity" },
-		thinkingLevel: "low",
-		cwd: "/run/media/bisma/DATA/Pi/pi-arnative",
-	};
-
-	// Only "dim" is colored, so the box line colors can be asserted.
-	const ansiTheme = { fg: (c: string, t: string) => (c === "dim" ? `\x1b[2m${t}\x1b[22m` : t) };
-
-	// Counts come from pi's loaded-resource listing. With `quietStartup: true | "header"`
-	// pi skips that listing, so the counts are unknown — shown as "—", never a misleading 0.
-	resourcesListingShown(false);
-	tabStore.set("Context", []);
-	tabStore.set("Skills", []);
-	tabStore.set("Extensions", []);
-	const hdrQuiet = new ArnativeHeader(fakeTui, ansiTheme, fakeCtx);
-	assert(hdrQuiet.getTabsData(120).map((t) => t.label).join("|").includes("Skills [—]"), "hidden listing: counts render as —, not 0");
-	hdrQuiet.activeTab = "Skills";
-	assert(
-		hdrQuiet.render(120).some((l) => stripAnsi(l).includes("(not tracked")),
-		"hidden listing: empty tab explains itself instead of a bare (empty)",
-	);
-	resourcesListingShown(true);
-	assert(new ArnativeHeader(fakeTui, ansiTheme, fakeCtx).getTabsData(120).some((t) => t.label === "Skills [0]"), "shown listing: 0 is a real count again");
-	tabStore.set("Context", ["AGENTS.md"]);
-	tabStore.set("Skills", ["agents-sdk", "cloudflare"]);
-	tabStore.set("Extensions", ["@bismawy/pi-agentrouter@1.6.1", "footer.ts"]);
-	const hdr = new ArnativeHeader(fakeTui, ansiTheme, fakeCtx);
-	assert(hdr.activeTab === "Directory", "default tab is Directory");
-
-	// Default view: the working directory path, shown on open
-	const linesDefault = hdr.render(100);
-	assert(stripAnsi(linesDefault[5]!).includes("/run/media/bisma/DATA/Pi/pi-arnative"), "directory path shown as soon as the first tab opens");
-
-	hdr.activeTab = "Model";
-	const lines100 = hdr.render(100);
-	assert(lines100.length === 7, "render 100 = border + 5 rows + border (left: mark + gap + pi version; info: brand line + tab box + data)");
-	assert(lines100.every((l) => visibleWidth(l) === 100), "every line at width 100 is exactly 100 columns");
-	assert(lines100[0]!.includes("╭") && lines100[0]!.includes("╮"), "round top border");
-	assert(lines100[6]!.includes("╰") && lines100[6]!.includes("╯"), "round bottom border");
-	// The column divider joins the frame: full-height split, no gap at the borders.
-	const jx = stripAnsi(lines100[0]!).indexOf("┬");
-	assert(jx > 0 && stripAnsi(lines100[6]!).indexOf("┴") === jx, "┬/┴ junctions sit on the border at the divider column");
-	assert(
-		lines100.slice(1, 6).every((l) => stripAnsi(l)[jx] === "│"),
-		"the divider sits in the same column on every row",
-	);
-	const logoPlain = buildLogoLines(null);
-	assert(logoPlain.length === 4 && visibleWidth(logoPlain[0]!) === 8, "pi block mark intact (4 lines x 8 columns)");
-	// P (columns 0-2) accent, i (the right bar) soft — the old wordmark's two-tone.
-	const logoTagged = buildLogoLines({
-		fg: (c: string, t: string) => (c === "accent" ? `<A>${t}</A>` : c === "accentSoft" ? `<T>${t}</T>` : t),
-	} as any);
-	assert(logoTagged[0] === "<A>██████</A>  ", "mark top row: P in the theme accent");
-	assert(logoTagged[2] === "<A>████</A>  <T>██</T>", "mark lower rows: P accent + i (right bar) soft");
-	assert(
-		lines100.slice(1, 5).every((l, i) => stripAnsi(l).slice(2, 10) === logoPlain[i]),
-		"pi block mark in the left column, 4 lines",
-	);
-	assert(
-		/Welcome back, \S/.test(stripAnsi(lines100[1]!)) && !stripAnsi(lines100[1]!).includes("pi v"),
-		"line 1: greeting uses the device username",
-	);
-	// Left column: the pi version sits directly under the mark (no gap).
-	assert(stripAnsi(lines100[5]!).slice(2, 12).includes("pi v"), "pi version sits under the mark in the left column");
-	// Info column: brand + greeting, then the tab box straight away (no blank line).
-	assert(/Arnative v\d+\.\d+\.\d+ · Welcome back, \S/.test(stripAnsi(lines100[1]!)), "info line 1: Arnative version · Welcome back, user");
-	assert(!stripAnsi(lines100[2]!).includes("Menu"), "tab box border carries no label");
-	// Tab box separators join its borders: ┬ above and ┴ below each "│". Compare by display
-	// column, not string index: the tab icons are astral (2 code units, 1 column).
-	const atColumn = (line: string, col: number): string | undefined => {
-		let c = 0;
-		for (const ch of stripAnsi(line)) {
-			const w = visibleWidth(ch);
-			if (col >= c && col < c + w) return ch;
-			c += w;
-		}
-		return undefined;
-	};
-	const tabSepCols = [...stripAnsi(lines100[2]!).matchAll(/┬/g)].map((m) => visibleWidth(stripAnsi(lines100[2]!).slice(0, m.index)));
-	assert(tabSepCols.length >= 2, "tab box top border has ┬ at each column divider");
-	assert(
-		tabSepCols.every((c) => atColumn(lines100[3]!, c) === "│" && atColumn(lines100[4]!, c) === "┴"),
-		"each tab divider is full height (┬ / │ / ┴ in the same column)",
-	);
-	assert(!stripAnsi(lines100[1]!).includes("Interrupt"), "shortcut legend no longer on the top line");
-	// Both brand names use the theme accent, not only "pi".
-	const accentTheme = {
-		fg: (c: string, t: string) => (c === "accent" ? `<A>${t}</A>` : c === "dim" ? `<D>${t}</D>` : t),
-	};
-	const accentHeader = new ArnativeHeader(fakeTui, accentTheme as any, fakeCtx);
-	// The marker theme returns literal "<A>" text (not ANSI), so the measured width is
-	// inflated — render wide enough that the brand/greeting line is not truncated.
-	const accentLines = accentHeader.render(140);
-	assert(accentLines[5]!.includes("<A>\x1b[1mpi"), "the pi name uses the theme accent");
-	assert(accentLines[1]!.includes("<A>\x1b[1mArnative"), "the Arnative name uses the same theme accent");
-	const greetLine = accentHeader.render(140)[1]!;
-	assert(greetLine.includes("<D>Welcome back,"), "greeting text uses the dim color");
-	assert(greetLine.includes(`<A>\x1b[1m${capitalize(deviceUser())}`), "device username uses the theme accent, first letter capitalized");
-	assert(stripAnsi(lines100[3]!).includes("Model [Gemini 3.8 Flash]"), "Model tab in the menu (Model [name])");
-	// Directory tab: name only in the menu, whole path in the content line below
-	hdr.activeTab = "Directory";
-	hdr.render(100);
-	assert(stripAnsi(lines100[3]!).includes("Directory"), "Directory tab shown in the menu");
-	assert(!stripAnsi(lines100[3]!).includes("Directory: /"), "Directory menu entry has no path (detail only on click)");
-	assert(stripAnsi(lines100[3]!).indexOf("Directory") < stripAnsi(lines100[3]!).indexOf("Model ["), "Directory tab is leftmost");
-	hdr.activeTab = "Model";
-	hdr.render(100);
-	assert(stripAnsi(lines100[5]!).includes("Gemini 3.8 Flash (Antigravity)"), "active Model tab data on the last info line");
-	// Directory tab content: full path, wrapped, nothing lost
-	hdr.activeTab = "Directory";
-	const linesDir = hdr.render(100);
-	const dirContent = stripAnsi(linesDir[5]!);
-	assert(dirContent.includes("/run/media/bisma"), "full Directory tab path (start) shown");
-	assert(dirContent.includes("pi-arnative"), "full Directory tab path (end) shown — no truncation");
-	hdr.activeTab = "Model";
-	hdr.render(100);
-	// Tab box borders are a single fully dimmed block (the "─"/"┬"/"┴" runs are colored too).
-	assert((lines100[4]!.match(/\x1b\[/g) ?? []).length === 8, "bottom box line (row 4) = one fully dimmed block");
-	assert(
-		lines100[2]!.includes("\x1b[2m╭─") && lines100[2]!.includes("┬") && lines100[2]!.includes("╮\x1b[22m"),
-		"tab box top border = one dim block carrying the ┬ junctions",
-	);
-
-	// Tab regions: Model, Context, Skills, Extensions
-	const tabY = (hdr as any).renderedTabLineY;
-	assert(tabY > 0, "tab line Y position recorded");
-	const tabRegions = (hdr as any).renderedTabRegions as Array<{ key: TabKey; startX: number; endX: number }>;
-	assert(tabRegions.length >= 3, "tab regions filled (right tabs may be cut at 100 columns)");
-	assert(tabRegions.some((r) => r.key === "Directory"), "Directory tab present in the menu (width 100)");
-
-	// Click the Extensions tab (when truncated at 100 columns, use the rightmost tab)
-	const extRegion = tabRegions.find((r) => r.key === "Extensions") ?? tabRegions[tabRegions.length - 1]!;
-	const clickExt = hdr.handleMouse({
-		type: "click",
-		button: "left",
-		x: Math.floor((extRegion.startX + extRegion.endX) / 2),
-		y: tabY,
-	} as any);
-	assert(clickExt?.handled === true, "mouse click on the tab is handled");
-	assert(hdr.activeTab === extRegion.key, "activeTab switches to the clicked tab");
-	assert(renderRequested === true, "requestRender called when the tab switches");
-
-	const linesExt = hdr.render(100);
-	assert(stripAnsi(linesExt[5]!).includes(extRegion.key === "Extensions" ? "@bismawy/pi-agentrouter@1.6.1" : ""), "active tab data on the last info line");
-
-	// Click the Skills tab (measured at a width where every tab fits)
-	const wide = hdr.render(140);
-	const wideRegions = (hdr as any).renderedTabRegions as Array<{ key: TabKey; startX: number; endX: number }>;
-	const skillsRegion = wideRegions.find((r) => r.key === "Skills") ?? wideRegions[wideRegions.length - 1]!;
-	hdr.activeTab = "Model";
-	hdr.render(140);
-	const skillsY = (hdr as any).renderedTabLineY;
-	hdr.handleMouse({
-		type: "click",
-		button: "left",
-		x: Math.floor((skillsRegion.startX + skillsRegion.endX) / 2),
-		y: skillsY,
-	} as any);
-	assert(hdr.activeTab === skillsRegion.key, `activeTab switches to ${skillsRegion.key} after the click`);
-
-	const linesSkills = hdr.render(140);
-	assert(wide.every((l) => visibleWidth(l) === 140), "lines at 140 columns stay 140");
-	assert(wideRegions.length === 6, "width 140: all 6 tabs shown (Shortcut included)");
-	if (skillsRegion.key === "Skills") {
-		assert(linesSkills[5]!.includes("agents-sdk, cloudflare"), "Skills tab data on the last info line");
-		assert(!linesSkills[5]!.includes("Gemini 3.8 Flash (Antigravity)"), "Model data not shown in the Skills tab content");
-		assert(linesSkills[3]!.includes("Model [Gemini 3.8 Flash]"), "tab menu still shown while another tab is active");
-	}
-
-	// The Y of a tab must point at the tab menu line, not the line above
-	const rowsPlain = lines100.map((l) => stripAnsi(l));
-	assert(rowsPlain[tabY]!.includes("Model ["), "renderedTabLineY points at the tab menu line");
-	assert(tabRegions.every((r) => rowsPlain[tabY]!.slice(r.startX, r.endX + 1).includes(r.key === "Model" ? "Model [" : r.key)), "tab regions align with the text on that line");
-
-	// Shortcut tab: the key cheatsheet lives in the tab content, not in a header line
-	hdr.activeTab = "Shortcut";
-	const linesShortcut = hdr.render(170);
-	assert(
-		((hdr as any).renderedTabRegions as Array<{ key: TabKey }>).some((r) => r.key === "Shortcut"),
-		"width 170: Shortcut tab shown (not dropped)",
-	);
-	const scContent = stripAnsi(linesShortcut.slice(5).join(" "));
-	assert(scContent.includes("[Esc] Interrupt"), "Shortcut tab: legend moved into the content");
-	assert(
-		scContent.includes(`[${SHORTCUT_RELOAD.label}] Reload`),
-		`Shortcut tab: reload shortcut present in the content (${SHORTCUT_RELOAD.label})`,
-	);
-	assert(stripAnsi(linesShortcut[1]!).includes("Arnative v"), "the Arnative brand stays on line 1 while the Shortcut tab is active");
-	hdr.activeTab = "Model";
-	hdr.render(140);
-
-	// Narrow screen: brand lines + tabs + data stay intact, rightmost tabs are dropped
-	const narrow = hdr.render(60);
-	assert(narrow.every((l) => visibleWidth(l) === 60), "lines at 60 columns stay 60");
-	assert(stripAnsi(narrow[1]!).includes("Welcome back,"), "greeting stays intact at 60 columns");
-	assert(stripAnsi(narrow[1]!).includes("Arnative v"), "Arnative brand intact at 60 columns");
-	assert(stripAnsi(narrow[1]!).includes("Interrupt") === false, "legend does not come back to the top line");
-	assert(
-		!((hdr as any).renderedTabRegions as Array<{ key: TabKey }>).some((r) => r.key === "Shortcut"),
-		"rightmost tab dropped at 60 columns",
-	);
-	assert(stripAnsi(narrow[3]!).includes("Model ["), "Model tab still shown at 60 columns");
-
-	// Intercept addChild: capture the data and suppress the child
-	const proto = Object.getPrototypeOf(UserMessageComponent.prototype) as { addChild?: unknown };
-	const container: any = { children: [] as any[], addChild: proto.addChild as (c: any) => unknown };
-	const fakeSection = {
-		getCollapsedText: () => "[Skills]\n  new-skill-1, new-skill-2",
-		getExpandedText: () => "[Skills]\n  new-skill-1, new-skill-2",
-		setText: () => {},
-		render: (_w: number) => ["should be hidden"],
-	};
-	container.addChild(fakeSection);
-	assert(fakeSection.render(80).length === 0, "child of loadedResourcesContainer suppressed (render = [])");
-	assert(tabStore.get("Skills")?.includes("new-skill-1") === true, "new data lands in tabStore");
-
-	// pi 0.99 ExpandableText shape: `build` callback + `state` object, no getters.
-	const modernSection = {
-		state: { expanded: false },
-		build: () => "[Context]\n  AGENTS.md, MEMORY.md",
-		setText: () => {},
-		render: (_w: number) => ["should be hidden"],
-	};
-	container.addChild(modernSection);
-	assert(modernSection.render(80).length === 0, "pi 0.99 section suppressed (build + state shape)");
-	assert(tabStore.get("Context")?.includes("MEMORY.md") === true, "pi 0.99 section data lands in tabStore");
-
-	// Startup help block is not a resource section and must survive untouched.
-	const helpBlock = { build: () => "\u2580\u2580\u2588  v0.99.1\n\u2588\u2580 \u2588 escape interrupt", state: { expanded: false }, render: () => ["help"] };
-	container.addChild(helpBlock);
-	assert(sectionBodyOf(helpBlock) === "\u2580\u2580\u2588  v0.99.1\n\u2588\u2580 \u2588 escape interrupt", "sectionBodyOf reads the build shape");
-	assert(sectionNameOf(sectionBodyOf(helpBlock)!) === null, "startup help block is not a resource section");
-
-	console.log("section-headers.ts self-check OK");
-}

package/extensions/tools.ts

@@ -24,6 +24,10 @@ import {
 	createEditTool,
 	createFindTool,
 	createGrepTool,
+	createLsTool,
+	createLsToolDefinition,
+	createPowerShellTool,
+	createPowerShellToolDefinition,
 	createReadTool,
 	createWriteTool,
 	getMarkdownTheme,
@@ -290,11 +294,23 @@ for (const n of BOXED_TOOLS.keys()) OWN_BOX.add(n);
 
 const MCP_TOOL = (name: string): boolean => name === "mcp" || name === "mcpScript" || name.startsWith("mcp__");
 
-const FFF_OVERRIDE = ["find", "grep"];
-const usesTheirCallRenderer = (self: any): boolean =>
-	BOXED_TOOLS.has(self.toolName) ||
-	MCP_TOOL(self.toolName) ||
-	(FFF_OVERRIDE.includes(self.toolName) && self.toolDefinition?.renderShell !== "self");
+// pi-fff / pi core/plugin tools whose renderers we rebuild in our own box when their
+// renderer carries no explicit `renderShell` marker (our `minimal()` sets "self").
+//   pi-fff: `ffgrep`/`fffind` in the default mode, `find`/`grep` once it "overrides"
+//           pi's builtins; matching either name covers both of its modes.
+//   pi core: `powershell` and `ls` — pi's runtime keeps `createAllToolDefinitions`, which
+//           spreads `renderCall`/`renderResult` onto the tool OBJECT; `wrapToolDefinition`
+//           (used by `createPowerShellTool`/`createLsTool`) drops them instead.
+const boxTheirRenderers = (self: any): boolean =>
+	self.toolDefinition?.renderShell !== "self" &&
+	(self.toolName === "ls" ||
+		self.toolName === "powershell" ||
+		self.toolName === "ffgrep" ||
+		self.toolName === "fffind" ||
+		self.toolName === "find" ||
+		self.toolName === "grep" ||
+		BOXED_TOOLS.has(self.toolName) ||
+		MCP_TOOL(self.toolName));
 
 // The MCP box title names the invoked tool (full args when expanded).
 const mcpInfo = (name: string, args: any, th: Theme): string => {
@@ -352,7 +368,11 @@ if (ToolExecutionComponent?.prototype?.render && !(globalThis as Record<symbol,
 	const origCall = proto.getCallRenderer;
 	const origResult = proto.getResultRenderer;
 	const origShell = proto.getRenderShell;
-	const hasOwnRenderer = (self: any): boolean => Boolean(origCall.call(self) || origResult.call(self));
+	const hasOwnRenderer = (self: any): boolean =>
+		!boxTheirRenderers(self) && Boolean(origCall.call(self) || origResult.call(self));
+	// pi-fff splits title (renderCall) and result (renderResult) — both merge into one box.
+	// Its two naming modes are covered: `find`/`grep` (override) and `ffgrep`/`fffind` (default).
+	const FFF_TOOLS = ["find", "grep", "ffgrep", "fffind"];
 
 	// A tool call with no registered definition (e.g. an unknown tool name that
 	// errored with "Tool X not found") makes hasRendererDefinition() false, so the
@@ -366,13 +386,13 @@ if (ToolExecutionComponent?.prototype?.render && !(globalThis as Record<symbol,
 	};
 
 	proto.getRenderShell = function (): string {
-		if (usesTheirCallRenderer(this)) return "self";
+		if (boxTheirRenderers(this)) return "self";
 		return hasOwnRenderer(this) ? origShell.call(this) : "self";
 	};
 
 	proto.getCallRenderer = function () {
 		const name: string = this.toolName;
-		const mine = usesTheirCallRenderer(this);
+		const mine = boxTheirRenderers(this);
 		const own = origCall.call(this);
 		// Chrome DevTools' own renderCall is a bare line; ours replaces it (icon + name).
 		if (own && !mine && !CDP_NAME.has(name)) return own;
@@ -394,9 +414,9 @@ if (ToolExecutionComponent?.prototype?.render && !(globalThis as Record<symbol,
 		const name: string = this.toolName;
 		const own = origResult.call(this);
 		// pi-fff splits title (renderCall) and result (renderResult); both go in one box.
-		const fff = FFF_OVERRIDE.includes(name) && this.toolDefinition?.renderShell !== "self";
+		const fff = FFF_TOOLS.includes(name) && this.toolDefinition?.renderShell !== "self";
 		// MCP: their result renderer is deliberately skipped (unbounded error dump).
-		if (own && !usesTheirCallRenderer(this)) return own;
+		if (own && !boxTheirRenderers(this)) return own;
 		const boxed = BOXED_TOOLS.has(name);
 		// Chrome DevTools are in BOXED_TOOLS for the title/icon only: their renderResult
 		// (raw text, empty when collapsed) would drop our title row, so it is ignored.
@@ -660,6 +680,31 @@ function arnativeTools(pi: ExtensionAPI) {
 
 	// Gap is only stripped for our own boxes (see OWN_BOX above).
 
+	// powershell: pi core registers it as a separate builtin (only on Windows); without
+	// our own registration it keeps pi's "default" shell and renders as a bg block, not a
+	// box (the same reason `bash` is re-registered below). Windows only: on any other
+	// platform `getPowerShellConfig()` throws, and an unregistered tool would stay off
+	// while our registration is active on load.
+	if (process.platform === "win32")
+		minimal(
+			pi,
+			createPowerShellTool(cwd),
+			(th) => th.fg("accent", "PS>"),
+			(a, _th, soft, expanded) => {
+				const cmd = (a.command ?? "").replace(/\r?\n/g, " ").trim();
+				return paintLinks(expanded ? cmd : smartTitle(cmd), soft);
+			},
+		);
+
+	// ls: no renderShell of its own, so pi's default shell turns it into a bg block.
+	minimal(
+		pi,
+		createLsTool(cwd),
+		(th) => th.fg("accent", "ls"),
+		(a, _th, soft) => soft(shortPath(a.path ?? ".")),
+		numRes((n) => `${n} entries`),
+	);
+
 	// bash: `󰔟 $ <6 words>…` / `✓ $ <full title when expanded>  0.1s`
 	minimal(
 		pi,
@@ -997,6 +1042,38 @@ if (isMain(import.meta.url)) {
 	assert(fffOut.some((l: string) => l.includes("*.ts in D:/Pi/x")), "pi-fff find: renderCall title goes in the box");
 	assert(fffOut.some((l: string) => l.includes("6 more lines")), "pi-fff find: renderResult summary goes in the box");
 
+	// pi-fff default mode (`ffgrep`/`fffind`): same renderer shape, different names.
+	for (const n of ["ffgrep", "fffind"]) {
+		const t = { toolName: n, toolDefinition: { renderCall: () => fffCall, renderResult: () => fffRes } };
+		assert(
+			ToolExecutionComponent.prototype.getRenderShell.call(t) === "self",
+			`pi-fff ${n}: shell forced to self (default mode is boxed too)`,
+		);
+		const out = (ToolExecutionComponent.prototype.getResultRenderer.call(t) as any)(
+			{ content: [{ type: "text", text: "src/a.ts\nsrc/b.ts" }] },
+			{ expanded: false, isPartial: false },
+			th,
+			{ args: { pattern: "*.ts" }, state: {} },
+		).render(60);
+		assert(
+			out[0].startsWith("╭") && out.some((l: string) => l.includes("6 more lines")),
+			`pi-fff ${n}: result + summary merged into one box`,
+		);
+	}
+
+	// pi core `powershell` / `ls` spread their renderers into the tool object and set no
+	// renderShell, so pi's "default" shell used to render them as a bare bg block (see the
+	// OWN_BOX block below for the registration half of this fix).
+	for (const [n, t] of [
+		["powershell", createPowerShellToolDefinition(cwd)],
+		["ls", createLsToolDefinition(cwd)],
+	] as const) {
+		assert(
+			ToolExecutionComponent.prototype.getRenderShell.call({ toolName: n, toolDefinition: t }) === "self",
+			`pi core ${n}: shell forced to self (joins our box, not a bg block)`,
+		);
+	}
+
 	const oursFind = { toolName: "find", toolDefinition: { renderShell: "self", renderCall: () => fffCall, renderResult: () => fffRes } };
 	assert(
 		(ToolExecutionComponent.prototype.getCallRenderer.call(oursFind) as any)() === fffCall &&
@@ -1067,7 +1144,35 @@ if (isMain(import.meta.url)) {
 		"OWN_BOX: our own tools + boxed tools registered",
 	);
 	assert(!OWN_BOX.has("mcp") && !OWN_BOX.has("source_check"), "OWN_BOX: third-party renderers not tightened");
-	assert(hasOwnRendererDef(mcpTool) && !hasOwnRendererDef(noRenderer), "tightened benchmark: tool renderer definition");
+	// pi core `powershell`/`ls` spread their renderer functions onto the tool object and
+	// set no renderShell; that is exactly the shape that used to fall into pi's "default"
+	// shell and render as a bare bg block. Registering them through minimal() boxes them.
+	const coreReg: Record<string, any> = {};
+	arnativeTools({ registerTool: (t: any) => { coreReg[t.name] = t; }, registerToolRenderer: () => {}, on: () => {} } as never);
+	for (const [n, t] of [
+		["powershell", createPowerShellToolDefinition(cwd)],
+		["ls", createLsToolDefinition(cwd)],
+	] as const) {
+		const def = t as any;
+		assert(
+			Boolean(def.renderCall) && Boolean(def.renderResult),
+			`pi core ${n}: the definition pi runs spreads its renderers onto the object`,
+		);
+		assert(
+			ToolExecutionComponent.prototype.getRenderShell.call({ toolName: n, toolDefinition: def }) === "self",
+			`pi core ${n}: shell forced to self (joins our box, not a bg block)`,
+		);
+	}
+	// The guard is load-bearing: `getPowerShellConfig()` throws off Windows, and our
+	// registration activates a tool the builtin deliberately leaves off.
+	assert(
+		coreReg.ls?.renderShell === "self",
+		"pi core ls: registered through minimal() (boxing is live)",
+	);
+	assert(
+		process.platform === "win32" ? coreReg.powershell?.renderShell === "self" : coreReg.powershell === undefined,
+		"pi core powershell: registered on Windows only (getPowerShellConfig throws elsewhere)",
+	);	assert(hasOwnRendererDef(mcpTool) && !hasOwnRendererDef(noRenderer), "tightened benchmark: tool renderer definition");
 	assert(
 		capped(th, ["a", "b", "c"], false).length === CALL_ROWS + 1 &&
 			capped(th, ["a", "b", "c"], true).length === 3 &&

package/extensions/ui-render-tweaks.ts

@@ -21,7 +21,6 @@ import {
 	getMarkdownTheme,
 	initTheme,
 	InteractiveMode,
-	keyText,
 	Theme,
 	UserMessageComponent,
 	type ExtensionAPI,
@@ -40,12 +39,13 @@ import {
 } from "@earendil-works/pi-tui";
 import { readdirSync, readFileSync } from "node:fs";
 import { renderBoxLines } from "../lib/box.ts";
-import { ansiBgOpen, stripAnsi, themeOf, accentSoftOf } from "../lib/ansi.ts";
+import { ansiBgOpen, getActiveTheme, setActiveTheme, stripAnsi, themeOf, accentSoftOf } from "../lib/ansi.ts";
 import { assert, isMain } from "../lib/check.ts";
 import { contrast, parseOklch, toHex } from "../lib/color.ts";
 import { expandKeyName } from "../lib/format.ts";
 
-let activeThemeProxy: { fg(color: string, text: string): string; bg?(color: string, text: string): string } | null = null;
+type ActiveTheme = { fg(color: string, text: string): string; bg?(color: string, text: string): string } | null;
+const activeTheme = () => getActiveTheme<Exclude<ActiveTheme, null>>();
 
 // Hide pi's built-in "Reloading keybindings, extensions, skills..." box
 // (hardcoded in handleReloadCommand, no auto-hide). Patches Container.render
@@ -141,8 +141,8 @@ if (TuiAltScreen?.prototype && !(globalThis as Record<symbol, boolean>)[SELECTIO
 	if (typeof origHighlight === "function") {
 		TuiAltScreen.prototype.applySelectionHighlight = function (text: string): string {
 			const highlighted = origHighlight.call(this, text);
-			const fgOpen = ansiFgOpen(activeThemeProxy);
-			const bgOpen = ansiBgOpen(activeThemeProxy, "selectedBg");
+			const fgOpen = ansiFgOpen(activeTheme());
+			const bgOpen = ansiBgOpen(activeTheme(), "selectedBg");
 			return fgOpen && bgOpen ? recolorSelection(highlighted, fgOpen, bgOpen) : highlighted;
 		};
 	}
@@ -161,7 +161,7 @@ if (TuiAltScreen?.prototype && !(globalThis as Record<symbol, boolean>)[PILL_KEY
 			layout: unknown,
 			width: number,
 		) {
-			return withAccentPill(this, () => origComposite.call(this, screen, layout, width), activeThemeProxy);
+			return withAccentPill(this, () => origComposite.call(this, screen, layout, width), activeTheme());
 		};
 	}
 }
@@ -190,7 +190,7 @@ if (ExtensionSelectorComponent?.prototype && !(globalThis as Record<symbol, bool
 	};
 	const origUpdateList = proto.updateList;
 	proto.updateList = function (this: typeof proto) {
-		const th = activeThemeProxy;
+		const th = activeTheme();
 		if (!th) return origUpdateList.call(this); // no theme yet -> pi's default
 		this.listContainer.clear();
 		for (let i = 0; i < this.options.length; i++) {
@@ -206,7 +206,8 @@ if (ExtensionSelectorComponent?.prototype && !(globalThis as Record<symbol, bool
 export default function uiRenderTweaks(pi: ExtensionAPI) {
 	// The active theme is re-read per session (ctx.ui.theme); render reads it lazily.
 	pi.on("session_start", async (_event, ctx) => {
-		activeThemeProxy = themeOf<typeof activeThemeProxy>(ctx) ?? activeThemeProxy;
+		const th = themeOf<Exclude<ActiveTheme, null>>(ctx);
+		if (th) setActiveTheme(th);
 	});
 
 	// 4. `pi-jev-eye-review` contract message: use our own border box.
@@ -224,9 +225,9 @@ export default function uiRenderTweaks(pi: ExtensionAPI) {
 // body text is unchanged.
 export class PackageUpdateBoxComponent implements Component {
 	private packages: string[];
-	private th: { fg(c: string, t: string): string };
+	private th: { fg(c: string, t: string): string } | null;
 
-	constructor(packages: string[], th: { fg(c: string, t: string): string }) {
+	constructor(packages: string[], th: { fg(c: string, t: string): string } | null) {
 		this.packages = packages;
 		this.th = th;
 	}
@@ -235,10 +236,11 @@ export class PackageUpdateBoxComponent implements Component {
 
 	render(width: number): string[] {
 		const th = this.th;
+		const fg = (color: string, text: string) => (th ? th.fg(color, text) : text);
 		const rows = [
-			th.fg("warning", "\x1b[1m\uf449  Package Updates Available\x1b[22m"),
-			`${th.fg("muted", "Package updates are available. Run ")}${th.fg("accent", "pi update --extensions")}`,
-			th.fg("muted", "Packages:"),
+			fg("warning", "\x1b[1m\uf449 Package Updates Available\x1b[22m"),
+			`${fg("muted", "Package updates are available. Run ")}${fg("accent", "pi update --extensions")}`,
+			fg("muted", "Packages:"),
 			...this.packages.map((pkg) => `- ${pkg}`),
 		];
 		return renderBoxLines(th, width, rows, undefined, "warning");
@@ -257,7 +259,7 @@ if (InteractiveMode?.prototype && !(globalThis as Record<symbol, boolean>)[PACKA
 			ui: { requestRender(): void };
 		};
 		self.chatContainer.addChild(new Spacer(1));
-		self.chatContainer.addChild(new PackageUpdateBoxComponent(packages, activeThemeProxy ?? Theme));
+		self.chatContainer.addChild(new PackageUpdateBoxComponent(packages, activeTheme()));
 		self.ui.requestRender();
 	};
 }
@@ -333,7 +335,7 @@ if (CompactionSummaryMessageComponent?.prototype && !(globalThis as Record<symbo
 	const proto = CompactionSummaryMessageComponent.prototype as any;
 	const origUpdateDisplay = proto.updateDisplay;
 	proto.updateDisplay = function (): void {
-		const th = activeThemeProxy;
+		const th = activeTheme();
 		if (!th) return origUpdateDisplay.call(this);
 		const message = this.message as { tokensBefore?: number; summary?: string } | undefined;
 		const tokenStr = Number(message?.tokensBefore ?? 0).toLocaleString();

package/lib/ansi.ts

@@ -25,6 +25,19 @@ export function themeOf<T>(ctx: unknown): T | null {
 	return (ctx as { ui?: { theme?: T } } | null | undefined)?.ui?.theme ?? null;
 }
 
+// Shared active-theme slot. `/reload` re-imports an extension's modules, so two copies
+// can coexist: one carries the session_start handler, the other owns a stacked UI patch.
+// globalThis gives both the same theme, so the patched copy paints instead of drawing
+// uncolored (or, before the null-guard fix, crashing). Set from `session_start`.
+const THEME_PROXY_KEY = Symbol.for("pi-arnative.activeThemeProxy");
+export function getActiveTheme<T>(): T | null {
+	return (globalThis as Record<symbol, T>)[THEME_PROXY_KEY] ?? null;
+}
+export function setActiveTheme<T>(th: T | null): void {
+	if (th) (globalThis as Record<symbol, T>)[THEME_PROXY_KEY] = th;
+	else delete (globalThis as Record<symbol, T>)[THEME_PROXY_KEY];
+}
+
 /** Painter for the `accentSoft` token, which only arnative themes define; other themes fall back to accent (probed once). */
 export function accentSoftOf(th: { fg?(c: string, t: string): string } | null): (s: string) => string {
 	const fg = th?.fg?.bind(th);
@@ -46,6 +59,11 @@ if (isMain(import.meta.url)) {
 	assert(themeOf({ ui: { theme: "T" } }) === "T", "themeOf reads ctx.ui.theme");
 	assert(themeOf(null) === null, "themeOf tolerates a missing ctx");
 
+	setActiveTheme({ fg: (c, t) => `<${c}>${t}</${c}>` });
+	assert(getActiveTheme<object>() !== null, "active theme round-trips through globalThis");
+	setActiveTheme(null);
+	assert(getActiveTheme<object>() === null, "clearing the active theme leaves no stale slot");
+
 	const tag = { fg: (c: string, t: string) => `<${c}>${t}</${c}>` };
 	assert(accentSoftOf(tag)("x") === "<accentSoft>x</accentSoft>", "accentSoftOf uses accentSoft when the theme defines it");
 	const noSoft = {

package/lib/box.ts

@@ -23,18 +23,21 @@ const applyBg = (line: string, width: number, bgFn: (text: string) => string): s
 	return bgFn(line + " ".repeat(pad));
 };
 
-/** Wrap `rows` (plain or ANSI-colored) into a box. `bgType` = theme bg name (no-op when the theme has no `bg`); `borderColor` = border color. */
-export function renderBoxLines(theme: BoxTheme, width: number, rows: string[], bgType?: string, borderColor = "dim"): string[] {
-	const dim = (s: string) => theme.fg(borderColor, s);
+/** Wrap `rows` (plain or ANSI-colored) into a box. `bgType` = theme bg name (no-op when the theme has no `bg`); `borderColor` = border color.
+ *  `theme` may be null: a box is patched in at module load, before `session_start`
+ *  delivers the active theme. An uncolored box for that first frame beats a null
+ *  deref that kills the process. */
+export function renderBoxLines(theme: BoxTheme | null, width: number, rows: string[], bgType?: string, borderColor = "dim"): string[] {
+	const dim = (s: string) => (theme ? theme.fg(borderColor, s) : s);
 	const inner = Math.max(8, width - 4);
 	const lines = [boxEdge("╭", "╮", width, dim)];
 	for (const row of rows) {
 		for (const line of wrapTextWithAnsi(row, inner)) lines.push(boxRow(line, width, dim));
 	}
 	lines.push(boxEdge("╰", "╯", width, dim));
-	if (bgType && theme.bg) {
+	if (bgType && theme?.bg) {
 		try {
-			return lines.map((l) => applyBg(l, width, (s) => theme.bg!(bgType, s)));
+			return lines.map((l) => applyBg(l, width, (s) => theme!.bg!(bgType, s)));
 		} catch {
 			return lines;
 		}
@@ -50,5 +53,8 @@ if (isMain(import.meta.url)) {
 	assert(plain[1] === "│ hello                │", "content line padded flush");
 	assert(renderBoxLines(th, 24, ["x".repeat(40)]).length === 4, "long line wrapped");
 	assert(renderBoxLines(th, 20, ["hi"], "customMessageBg").length === 3, "bg ignored when the theme has no bg");
+	const nullTheme = renderBoxLines(null, 24, ["hello"], "customMessageBg");
+	assert(nullTheme.every((l) => visibleWidth(l) === 24), "null theme renders an uncolored box instead of throwing");
+	assert(nullTheme[0]!.startsWith("╭") && nullTheme[1] === "│ hello                │", "null-theme frame and padding intact");
 	console.log("lib/box.ts OK");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bismawy/pi-arnative",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Refined aesthetics. Cohesive tools. Built for Pi. Warm themes, rounded tool boxes, tabbed header, compact footer and a /usage dashboard.",
   "keywords": [
     "pi-package",
@@ -41,7 +41,7 @@
   },
   "scripts": {
     "dev": "pi --extension ./extensions/tools.ts --extension ./extensions/section-headers.ts --extension ./extensions/footer.ts --extension ./extensions/timestamps.ts --extension ./extensions/ui-render-tweaks.ts --extension ./extensions/usage.ts --extension ./extensions/arnative.ts",
-    "test": "node lib/box.ts && node lib/ansi.ts && node lib/color.ts && node lib/shortcuts.ts && node lib/preset-store.ts && node themes/gen-themes.mjs --check && node extensions/tools.ts && node extensions/footer.ts && node extensions/timestamps.ts && node extensions/section-headers.ts && node extensions/ui-render-tweaks.ts && node extensions/usage.ts && node extensions/arnative.ts",
+    "test": "node lib/box.ts && node lib/ansi.ts && node lib/color.ts && node lib/shortcuts.ts && node lib/preset-store.ts && node themes/gen-themes.mjs --check && node extensions/tools.ts && node extensions/footer.ts && node extensions/timestamps.ts && node extensions/ui-render-tweaks.ts && node extensions/usage.ts && node extensions/arnative.ts && node --test",
     "themes": "node themes/gen-themes.mjs",
     "release:check": "node scripts/release-check.mjs pre-tag",
     "prepublishOnly": "npm test && node scripts/release-check.mjs pre-publish"