@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

package/node_modules/@narumitw/pi-btw/src/menu.ts

@@ -7,6 +7,7 @@ import type { Component, TUI } from "@earendil-works/pi-tui";
 import type { MenuContext, RunMenuResult } from "@narumitw/pi-tui-kit";
 import {
 	type BtwSettings,
+	type BtwSettingsPatch,
 	btwSettingsPath,
 	effectiveRememberThinkingLevelChanges,
 	readBtwSettings,
@@ -35,15 +36,20 @@ export interface ShowBtwCommandMenuOptions {
 	settingsPath?: string;
 	readSettings?: typeof readBtwSettings;
 	updateSettings?: (
-		patch: Partial<Pick<BtwSettings, "thinkingLevel" | "rememberThinkingLevelChanges">>,
+		patch: BtwSettingsPatch,
 		options: UpdateBtwSettingsOptions,
 	) => Promise<BtwSettings>;
 }
 
-export type BtwCommandMenuResult = "start" | "closed" | { kind: "resume"; threadId: string };
+export type BtwCommandMenuResult =
+	| "start"
+	| "tree"
+	| "closed"
+	| { kind: "resume"; threadId: string };
 
 type BtwMenuScreen = "main" | "resume" | "settings" | "invalid";
-type BtwMenuAction = "start" | "resume" | "set-thinking" | "set-remember";
+type BtwMenuAction = "start" | "start-tree" | "resume" | "set-thinking" | "set-remember";
+const SAME_AS_MAIN_THREAD = "Same as main thread";
 type BtwCustomOptions = Parameters<ExtensionCommandContext["ui"]["custom"]>[1];
 
 type BtwCustomFactory<T> = (
@@ -70,6 +76,7 @@ export async function showBtwCommandMenu(
 	const displaySettingsPath = sanitizeSingleLine(settingsPath);
 	const resumeThreads = options.resumeThreads ?? [];
 	let startSelected = false;
+	let treeSelected = false;
 	let resumedThreadId: string | undefined;
 
 	const loadState = async (): Promise<BtwMenuState> => {
@@ -79,8 +86,22 @@ export async function showBtwCommandMenu(
 		}
 		return { kind: "valid", settings: loaded.kind === "loaded" ? loaded.settings : {} };
 	};
-	const displayThinkingLevel = (settings: BtwSettings): BtwThinkingLevel =>
-		clampToAvailableThinkingLevel(settings.thinkingLevel ?? options.currentThinkingLevel, levels);
+	const currentMainThinkingLevel = clampToAvailableThinkingLevel(
+		options.currentThinkingLevel,
+		levels,
+	);
+	const displayThinkingLevel = (settings: BtwSettings): string =>
+		settings.thinkingLevel === undefined
+			? SAME_AS_MAIN_THREAD
+			: clampToAvailableThinkingLevel(settings.thinkingLevel, levels);
+	const displayThinkingSummary = (settings: BtwSettings): string =>
+		settings.thinkingLevel === undefined
+			? `${SAME_AS_MAIN_THREAD} (currently ${currentMainThinkingLevel})`
+			: displayThinkingLevel(settings);
+	const displayRememberSummary = (settings: BtwSettings): string => {
+		const value = effectiveRememberThinkingLevelChanges(settings) ? "On" : "Off";
+		return settings.thinkingLevel === undefined ? `${value} (fixed levels only)` : value;
+	};
 
 	const menu = defineMenu<BtwMenuState, BtwMenuScreen, BtwMenuAction, MenuContext>({
 		start: "main",
@@ -89,7 +110,7 @@ export async function showBtwCommandMenu(
 				kind: "actions",
 				title: "Pi BTW",
 				lines: [
-					`Thinking: ${displayThinkingLevel(state.settings)} · Remember changes: ${effectiveRememberThinkingLevelChanges(state.settings) ? "On" : "Off"}`,
+					`Thinking: ${displayThinkingSummary(state.settings)} · Remember changes: ${displayRememberSummary(state.settings)}`,
 				],
 				items: [
 					{
@@ -98,6 +119,12 @@ export async function showBtwCommandMenu(
 						description: "Open an empty side thread",
 						action: "start",
 					},
+					{
+						id: "start-tree",
+						label: "Start from main thread tree…",
+						description: "Choose context without switching the main branch",
+						action: "start-tree",
+					},
 					...(resumeThreads.length > 0
 						? [
 								{
@@ -111,7 +138,7 @@ export async function showBtwCommandMenu(
 					{
 						id: "settings",
 						label: "Settings",
-						description: "Choose pi-btw thinking and whether shortcut changes are remembered",
+						description: "Choose pi-btw thinking level and fixed-level shortcut memory",
 						to: state.kind === "invalid" ? "invalid" : "settings",
 					},
 				],
@@ -138,15 +165,15 @@ export async function showBtwCommandMenu(
 					{
 						id: "thinkingLevel",
 						label: "Thinking level",
-						description: "Set the starting level for future pi-btw side threads.",
+						description: `Set the starting level for future pi-btw side threads. Currently ${currentMainThinkingLevel}.`,
 						currentValue: displayThinkingLevel(state.settings),
-						values: levels,
+						values: [SAME_AS_MAIN_THREAD, ...levels],
 						action: "set-thinking",
 					},
 					{
 						id: "rememberThinkingLevelChanges",
 						label: "Remember thinking level changes",
-						description: "Save side-thread shortcut changes to pi-btw.json for next time.",
+						description: "Save shortcut changes for fixed thinking levels to pi-btw.json.",
 						currentValue: effectiveRememberThinkingLevelChanges(state.settings) ? "On" : "Off",
 						values: ["On", "Off"],
 						action: "set-remember",
@@ -168,6 +195,10 @@ export async function showBtwCommandMenu(
 				startSelected = true;
 				return { kind: "close" };
 			},
+			"start-tree": async () => {
+				treeSelected = true;
+				return { kind: "close" };
+			},
 			resume: async ({ itemId }: { itemId: string }) => {
 				if (!resumeThreads.some((thread) => thread.id === itemId)) {
 					return { kind: "rejected" } as const;
@@ -176,12 +207,16 @@ export async function showBtwCommandMenu(
 				return { kind: "close" } as const;
 			},
 			"set-thinking": async ({ value, signal }) => {
-				if (!value || !levels.includes(value as BtwThinkingLevel)) return { kind: "rejected" };
+				if (!value) return { kind: "rejected" };
+				const patch =
+					value === SAME_AS_MAIN_THREAD
+						? ({ thinkingLevel: undefined } satisfies BtwSettingsPatch)
+						: levels.includes(value as BtwThinkingLevel)
+							? ({ thinkingLevel: value as BtwThinkingLevel } satisfies BtwSettingsPatch)
+							: undefined;
+				if (!patch) return { kind: "rejected" };
 				try {
-					await updateSettings(
-						{ thinkingLevel: value as BtwThinkingLevel },
-						{ settingsPath, signal },
-					);
+					await updateSettings(patch, { settingsPath, signal });
 					if (signal.aborted) return { kind: "rejected" };
 					notifySafely(ctx, `Pi BTW thinking level: ${value}.`, "info");
 					return { kind: "stay" };
@@ -213,9 +248,37 @@ export async function showBtwCommandMenu(
 	);
 	if (result.kind !== "closed" || result.reason !== "close") return "closed";
 	if (resumedThreadId) return { kind: "resume", threadId: resumedThreadId };
+	if (treeSelected) return "tree";
 	return startSelected ? "start" : "closed";
 }
 
+export async function showBtwCustomPreservingEditor<T>(
+	ctx: ExtensionCommandContext,
+	factory: BtwCustomFactory<T>,
+): Promise<T | undefined> {
+	let liveEditorText = ctx.ui.getEditorText();
+	let completed = false;
+	const result = await ctx.ui.custom<T>((tui, theme, keybindings, done) =>
+		factory(tui, theme, keybindings, (value) => {
+			try {
+				liveEditorText = ctx.ui.getEditorText();
+			} catch {
+				// Keep completion finite if session replacement invalidates the editor context.
+			}
+			completed = true;
+			done(value);
+		}),
+	);
+	if (completed) {
+		try {
+			if (ctx.ui.getEditorText() !== liveEditorText) ctx.ui.setEditorText(liveEditorText);
+		} catch {
+			// A replaced context owns a different editor and must not receive stale restoration.
+		}
+	}
+	return result;
+}
+
 export async function runBtwMenuPreservingEditor(
 	ctx: ExtensionCommandContext,
 	run: (menuContext: MenuContext) => Promise<RunMenuResult>,

package/node_modules/@narumitw/pi-btw/src/settings.ts

@@ -20,6 +20,11 @@ export type BtwSettingsLoadResult =
 	| { kind: "invalid"; reason: string }
 	| { kind: "loaded"; settings: BtwSettings };
 
+export interface BtwSettingsPatch {
+	thinkingLevel?: BtwThinkingLevel;
+	rememberThinkingLevelChanges?: boolean;
+}
+
 export interface UpdateBtwSettingsOptions {
 	settingsPath?: string;
 	signal?: AbortSignal;
@@ -77,14 +82,14 @@ export async function readBtwSettings(
 }
 
 export function updateBtwSettings(
-	patch: Partial<Pick<BtwSettings, "thinkingLevel" | "rememberThinkingLevelChanges">>,
+	patch: BtwSettingsPatch,
 	options: UpdateBtwSettingsOptions = {},
 ): Promise<BtwSettings> {
 	const settingsPath = options.settingsPath ?? btwSettingsPath();
 	return enqueueMutation(settingsPath, async () => {
 		options.signal?.throwIfAborted();
 		const current = await readSettingsDocumentForUpdate(settingsPath);
-		const updated: SettingsDocument = { ...current, ...patch };
+		const updated = applyBtwSettingsPatch(current, patch);
 		const settings = normalizeBtwSettings(updated);
 		if (!settings) throw invalidSettingsError(settingsPath, "invalid settings shape");
 		await publishSettings(settingsPath, updated, options.signal, options.beforeRename);
@@ -216,6 +221,21 @@ async function publishSettings(
 	}
 }
 
+function applyBtwSettingsPatch(
+	current: SettingsDocument,
+	patch: BtwSettingsPatch,
+): SettingsDocument {
+	const updated: SettingsDocument = { ...current };
+	if (Object.hasOwn(patch, "thinkingLevel")) {
+		if (patch.thinkingLevel === undefined) delete updated.thinkingLevel;
+		else updated.thinkingLevel = patch.thinkingLevel;
+	}
+	if (Object.hasOwn(patch, "rememberThinkingLevelChanges")) {
+		updated.rememberThinkingLevelChanges = patch.rememberThinkingLevelChanges;
+	}
+	return updated;
+}
+
 function isSettingsDocument(value: unknown): value is SettingsDocument {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/node_modules/@narumitw/pi-btw/src/transcript-pager.ts

@@ -16,10 +16,13 @@ import {
 	Loader,
 	Markdown,
 	matchesKey,
+	ScrollView,
 	type TUI,
 	truncateToWidth,
+	VStack,
 	visibleWidth,
 } from "@earendil-works/pi-tui";
+import type { BtwFullscreenLayoutComponent } from "./fullscreen-ui.js";
 import type { BtwThinkingLevel, SideThreadTurn } from "./side-thread.js";
 import { sanitizeSingleLine } from "./text.js";
 
@@ -29,6 +32,21 @@ const OSC133_MARKERS = ["\u001b]133;A\u0007", "\u001b]133;B\u0007", "\u001b]133;
 // Pi renders a spacer above the custom component and a two-line built-in footer below it.
 const RESERVED_APP_LINES = 3;
 
+// A temporary fit after manual scrolling must not silently resume following new output.
+class PreservingScrollView extends ScrollView {
+	override updateLayout(
+		contentHeight: number,
+		viewportHeight: number,
+		requestRender: () => void,
+	): void {
+		const preserveManualPosition = !this.isFollowingEnd;
+		super.updateLayout(contentHeight, viewportHeight, requestRender);
+		if (preserveManualPosition && this.isFollowingEnd) {
+			this.scrollTo(this.scrollTop, { disableFollow: true });
+		}
+	}
+}
+
 export type TranscriptPagerAction =
 	| { kind: "submit"; question: string }
 	| { kind: "bringToMain"; questionDraft: string }
@@ -49,14 +67,13 @@ export interface BtwAnsweringViewOptions {
 	};
 }
 
-export class BtwTranscriptPager implements Component, Focusable {
+export class BtwTranscriptPager implements BtwFullscreenLayoutComponent, Focusable {
 	private readonly transcriptComponents: Component[];
 	private readonly editor: Editor;
 	private readonly canBringToMain: boolean;
-	private scrollOffset = 0;
+	private readonly scrollView: ScrollView;
+	private readonly layoutRoot: VStack;
 	private lastContentLineCount = 0;
-	private lastViewportHeight = 1;
-	private followBottom: boolean;
 	private warning: string | undefined;
 	private finished = false;
 	private isFocused = false;
@@ -75,7 +92,6 @@ export class BtwTranscriptPager implements Component, Focusable {
 	) {
 		this.transcriptComponents = buildTranscriptComponents(turns, this.theme);
 		this.canBringToMain = turns.some((turn) => turn.kind === "answered");
-		this.followBottom = options.startAtBottom ?? false;
 		this.thinkingLevel = options.thinking?.level;
 		const editorTheme: EditorTheme = {
 			borderColor: (text) => this.theme.fg("accent", text),
@@ -101,6 +117,17 @@ export class BtwTranscriptPager implements Component, Focusable {
 			this.finished = true;
 			this.onAction({ kind: "submit", question });
 		};
+		const transcript = this.createTranscriptComponent();
+		this.scrollView = new PreservingScrollView(transcript, {
+			follow: options.startAtBottom ? "end" : "none",
+			primary: true,
+		});
+		this.layoutRoot = new VStack([
+			{ component: this.createHeaderComponent(), basis: 1, shrink: 0, minSize: 1 },
+			{ component: this.scrollView, basis: 0, grow: 1, minSize: 0 },
+			{ component: this.createFooterComponent(), basis: 1, shrink: 0, minSize: 1 },
+			{ component: this.editor, basis: "auto", shrink: 1, minSize: 0 },
+		]);
 	}
 
 	get focused(): boolean {
@@ -112,6 +139,10 @@ export class BtwTranscriptPager implements Component, Focusable {
 		this.editor.focused = value;
 	}
 
+	getFullscreenLayout(): Component {
+		return this.layoutRoot;
+	}
+
 	render(width: number): string[] {
 		const safeWidth = Math.max(1, width);
 		const editorLines = this.editor.render(safeWidth);
@@ -122,13 +153,13 @@ export class BtwTranscriptPager implements Component, Focusable {
 		);
 		const contentLines = renderTranscriptLines(this.transcriptComponents, safeWidth);
 		this.lastContentLineCount = contentLines.length;
-		this.lastViewportHeight = viewportHeight;
-		if (this.followBottom) this.scrollOffset = this.getMaxScrollOffset();
-		this.clampScrollOffset();
+		this.scrollView.updateLayout(contentLines.length, viewportHeight, () =>
+			this.tui.requestRender(),
+		);
 
 		return fitComposerLayout(
 			renderSideThreadHeader(safeWidth, this.theme, this.thinkingLevel),
-			contentLines.slice(this.scrollOffset, this.scrollOffset + viewportHeight),
+			contentLines.slice(this.scrollView.scrollTop, this.scrollView.scrollTop + viewportHeight),
 			this.renderFooter(safeWidth),
 			editorLines,
 			availableRows,
@@ -164,15 +195,12 @@ export class BtwTranscriptPager implements Component, Focusable {
 			return;
 		}
 		if (matchesKey(data, Key.pageUp)) {
-			const previousOffset = this.scrollOffset;
-			this.scrollBy(-this.lastViewportHeight);
-			if (this.scrollOffset < previousOffset) this.followBottom = false;
+			this.scrollView.scrollBy(-Math.max(1, this.scrollView.viewportHeight));
 			this.tui.requestRender();
 			return;
 		}
 		if (matchesKey(data, Key.pageDown)) {
-			this.scrollBy(this.lastViewportHeight);
-			this.followBottom = this.scrollOffset >= this.getMaxScrollOffset();
+			this.scrollView.scrollBy(Math.max(1, this.scrollView.viewportHeight));
 			this.tui.requestRender();
 			return;
 		}
@@ -181,8 +209,7 @@ export class BtwTranscriptPager implements Component, Focusable {
 	}
 
 	invalidate(): void {
-		for (const component of this.transcriptComponents) component.invalidate();
-		this.editor.invalidate();
+		this.layoutRoot.invalidate();
 	}
 
 	dispose(): void {
@@ -218,7 +245,7 @@ export class BtwTranscriptPager implements Component, Focusable {
 						? compactBase
 						: fallbackBase;
 		if (scrollable) {
-			const history = ` • ${this.scrollOffset > 0 ? "↑ older" : "↓ newer"} • PgUp/PgDn history`;
+			const history = ` • ${this.scrollView.scrollTop > 0 ? "↑ older" : "↓ newer"} • PgUp/PgDn history`;
 			const compactHistory = " • PgUp/PgDn";
 			const compactScrollable = this.canBringToMain
 				? "Enter • Ctrl+R • Ctrl+C • PgUp/PgDn"
@@ -238,29 +265,46 @@ export class BtwTranscriptPager implements Component, Focusable {
 		return truncateToWidth(this.theme.fg("muted", hints), width);
 	}
 
-	private scrollBy(delta: number): void {
-		this.scrollOffset += delta;
-		this.clampScrollOffset();
+	private createHeaderComponent(): Component {
+		return {
+			render: (width) => [renderSideThreadHeader(width, this.theme, this.thinkingLevel)],
+			invalidate() {},
+		};
 	}
 
-	private clampScrollOffset(): void {
-		this.scrollOffset = Math.max(0, Math.min(this.scrollOffset, this.getMaxScrollOffset()));
+	private createTranscriptComponent(): Component {
+		return {
+			render: (width) => {
+				const lines = renderTranscriptLines(this.transcriptComponents, width);
+				this.lastContentLineCount = lines.length;
+				return lines;
+			},
+			invalidate: () => {
+				for (const component of this.transcriptComponents) component.invalidate();
+			},
+		};
+	}
+
+	private createFooterComponent(): Component {
+		return {
+			render: (width) => [this.renderFooter(width)],
+			invalidate() {},
+		};
 	}
 
 	private getMaxScrollOffset(): number {
-		return Math.max(0, this.lastContentLineCount - this.lastViewportHeight);
+		return Math.max(0, this.lastContentLineCount - this.scrollView.viewportHeight);
 	}
 }
 
-export class BtwAnsweringView implements Component, Focusable {
+export class BtwAnsweringView implements BtwFullscreenLayoutComponent, Focusable {
 	private readonly transcriptComponents: Component[];
 	private readonly loader: Loader;
 	private readonly editor: Editor | undefined;
 	private readonly controller = new AbortController();
-	private scrollOffset = 0;
+	private readonly scrollView: ScrollView;
+	private readonly layoutRoot: VStack;
 	private lastContentLineCount = 0;
-	private lastViewportHeight = 1;
-	private followBottom = true;
 	private warning: string | undefined;
 	private finished = false;
 	private isFocused = false;
@@ -308,6 +352,23 @@ export class BtwAnsweringView implements Component, Focusable {
 				this.warning = undefined;
 			};
 		}
+		const transcript = this.createTranscriptComponent();
+		this.scrollView = new PreservingScrollView(transcript, { follow: "end", primary: true });
+		this.layoutRoot = new VStack([
+			{ component: this.createHeaderComponent(), basis: 1, shrink: 0, minSize: 1 },
+			{ component: this.scrollView, basis: 0, grow: 1, minSize: 0 },
+			{
+				component: this.createSteeringComponent(),
+				basis: "auto",
+				shrink: 1,
+				minSize: 0,
+				maxSize: MAX_STEERING_DISPLAY_LINES,
+			},
+			{ component: this.createFooterComponent(), basis: 1, shrink: 0, minSize: 1 },
+			...(this.editor
+				? [{ component: this.editor, basis: "auto" as const, shrink: 1, minSize: 0 }]
+				: []),
+		]);
 	}
 
 	get focused(): boolean {
@@ -323,6 +384,10 @@ export class BtwAnsweringView implements Component, Focusable {
 		return this.controller.signal;
 	}
 
+	getFullscreenLayout(): Component {
+		return this.layoutRoot;
+	}
+
 	render(width: number): string[] {
 		const safeWidth = Math.max(1, width);
 		const availableRows = Math.max(1, this.tui.terminal.rows - RESERVED_APP_LINES);
@@ -343,13 +408,13 @@ export class BtwAnsweringView implements Component, Focusable {
 		);
 		const contentLines = renderTranscriptLines(this.transcriptComponents, safeWidth);
 		this.lastContentLineCount = contentLines.length;
-		this.lastViewportHeight = viewportHeight;
-		if (this.followBottom) this.scrollOffset = this.getMaxScrollOffset();
-		this.clampScrollOffset();
+		this.scrollView.updateLayout(contentLines.length, viewportHeight, () =>
+			this.tui.requestRender(),
+		);
 
 		return fitComposerLayout(
 			renderSideThreadHeader(safeWidth, this.theme, this.thinkingLevel),
-			contentLines.slice(this.scrollOffset, this.scrollOffset + viewportHeight),
+			contentLines.slice(this.scrollView.scrollTop, this.scrollView.scrollTop + viewportHeight),
 			this.renderFooter(safeWidth),
 			editorLines,
 			availableRows,
@@ -383,15 +448,12 @@ export class BtwAnsweringView implements Component, Focusable {
 			return;
 		}
 		if (matchesKey(data, Key.pageUp)) {
-			const previousOffset = this.scrollOffset;
-			this.scrollBy(-this.lastViewportHeight);
-			if (this.scrollOffset < previousOffset) this.followBottom = false;
+			this.scrollView.scrollBy(-Math.max(1, this.scrollView.viewportHeight));
 			this.tui.requestRender();
 			return;
 		}
 		if (matchesKey(data, Key.pageDown)) {
-			this.scrollBy(this.lastViewportHeight);
-			this.followBottom = this.scrollOffset >= this.getMaxScrollOffset();
+			this.scrollView.scrollBy(Math.max(1, this.scrollView.viewportHeight));
 			this.tui.requestRender();
 			return;
 		}
@@ -400,9 +462,7 @@ export class BtwAnsweringView implements Component, Focusable {
 	}
 
 	invalidate(): void {
-		for (const component of this.transcriptComponents) component.invalidate();
-		this.loader.invalidate();
-		this.editor?.invalidate();
+		this.layoutRoot.invalidate();
 	}
 
 	finish(): void {
@@ -442,17 +502,48 @@ export class BtwAnsweringView implements Component, Focusable {
 		return truncateToWidth(`${loaderLine} • ${this.theme.fg("muted", selectedHints)}`, width);
 	}
 
-	private scrollBy(delta: number): void {
-		this.scrollOffset += delta;
-		this.clampScrollOffset();
+	private createHeaderComponent(): Component {
+		return {
+			render: (width) => [renderSideThreadHeader(width, this.theme, this.thinkingLevel)],
+			invalidate() {},
+		};
+	}
+
+	private createTranscriptComponent(): Component {
+		return {
+			render: (width) => {
+				const lines = renderTranscriptLines(this.transcriptComponents, width);
+				this.lastContentLineCount = lines.length;
+				return lines;
+			},
+			invalidate: () => {
+				for (const component of this.transcriptComponents) component.invalidate();
+			},
+		};
+	}
+
+	private createSteeringComponent(): Component {
+		return {
+			render: (width) =>
+				renderSteeringLines(
+					this.options.steering?.questions ?? [],
+					width,
+					this.theme,
+					MAX_STEERING_DISPLAY_LINES,
+				),
+			invalidate() {},
+		};
 	}
 
-	private clampScrollOffset(): void {
-		this.scrollOffset = Math.max(0, Math.min(this.scrollOffset, this.getMaxScrollOffset()));
+	private createFooterComponent(): Component {
+		return {
+			render: (width) => [this.renderFooter(width)],
+			invalidate: () => this.loader.invalidate(),
+		};
 	}
 
 	private getMaxScrollOffset(): number {
-		return Math.max(0, this.lastContentLineCount - this.lastViewportHeight);
+		return Math.max(0, this.lastContentLineCount - this.scrollView.viewportHeight);
 	}
 }