@narumitw/pi-btw 0.53.0 → 0.54.0

package/README.md

@@ -96,10 +96,12 @@ Type another question and press `Enter` to queue it as `Steering`; queued questi
 submission order and answered one at a time after the active response completes.
 A queued question uses the side thread's thinking level when its turn begins.
 A failed active response is shown in the transcript and does not discard later steering questions.
-The footer shows `PgUp`/`PgDn` only when history can scroll; press `Ctrl+C` to cancel the active
-response and discard the ephemeral side-thread draft and steering queue. Completed questions,
-answers, and visible errors remain available through Resume until the current extension instance
-ends. Steering remains entirely inside pi-btw and never appends to the main conversation or editor.
+Use the mouse wheel or trackpad to scroll transcript history like Pi's main thread.
+Keyboard `PgUp`/`PgDn` history navigation remains available.
+It appears in the footer only when the transcript can scroll.
+Press `Ctrl+C` to cancel the active response and discard the ephemeral side-thread draft and steering queue.
+Completed questions, answers, and visible errors remain available through Resume until the current extension instance ends.
+Steering remains entirely inside pi-btw and never appends to the main conversation or editor.
 
 After at least one successful answer, press `Ctrl+R` to bring selected context to the main
 editor. The scope menu shows the size of the latest question and answer and the entire side

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-btw",
-	"version": "0.53.0",
+	"version": "0.54.0",
 	"description": "Pi extension that adds a /btw side-question command.",
 	"type": "module",
 	"license": "MIT",

package/src/fullscreen-ui.ts

@@ -21,7 +21,14 @@ type BtwCustomFactory<T> = (
 	done: (result: T) => void,
 ) => (Component & { dispose?(): void }) | Promise<Component & { dispose?(): void }>;
 
-type BtwFullscreenTui = TUI & { flash?: (message: string, durationMs?: number) => void };
+type BtwFullscreenTui = TUI & {
+	flash?: (message: string, durationMs?: number) => void;
+	setLayoutRoot(component: Component | undefined): void;
+};
+
+export interface BtwFullscreenLayoutComponent extends Component {
+	getFullscreenLayout(): Component;
+}
 
 export type BtwFullscreenTuiFactory = (parent: TUI) => BtwFullscreenTui;
 
@@ -223,6 +230,7 @@ class BtwFullscreenHost<T> implements Component {
 			let component: (Component & { dispose?(): void }) | undefined;
 			let overlay: OverlayHandle | undefined;
 			let mounted = false;
+			let layoutMounted = false;
 			let factorySettled = false;
 			let closed = false;
 			let promiseSettled = false;
@@ -243,6 +251,7 @@ class BtwFullscreenHost<T> implements Component {
 				let cleanupError: unknown;
 				try {
 					if (overlay) overlay.hide();
+					else if (mounted && layoutMounted) fullscreen.setLayoutRoot(undefined);
 					else if (mounted && component) fullscreen.removeChild(component);
 				} catch (error) {
 					cleanupError = error;
@@ -327,8 +336,13 @@ class BtwFullscreenHost<T> implements Component {
 						options.onHandle?.(overlay);
 					} else {
 						fullscreen.clear();
-						fullscreen.addChild(component);
 						mounted = true;
+						if (isFullscreenLayoutComponent(component)) {
+							layoutMounted = true;
+							fullscreen.setLayoutRoot(component.getFullscreenLayout());
+						} else {
+							fullscreen.addChild(component);
+						}
 						fullscreen.setFocus(component);
 						fullscreen.requestRender();
 					}
@@ -337,3 +351,9 @@ class BtwFullscreenHost<T> implements Component {
 		});
 	}
 }
+
+function isFullscreenLayoutComponent(
+	component: Component,
+): component is BtwFullscreenLayoutComponent {
+	return "getFullscreenLayout" in component && typeof component.getFullscreenLayout === "function";
+}

package/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);
 	}
 }