pi-btw-cc 0.1.0 → 0.2.0

package/README.md

@@ -32,12 +32,15 @@ Needs Node >= 22.19 and pi 0.85.x.
 | --- | --- |
 | `↑` `↓` | Scroll the answer |
 | `⇧←` `⇧→` | Browse the side thread |
+| `e` | Expand or fold a long side question |
 | `c` | Copy the selected answer |
 | `f` | Promote the selected exchange into the main conversation |
 | `x` | Delete the selected side question |
 | `Esc` `Enter` | Close |
 
-The selected exchange is the one expanded in the body and the one `⇧←/⇧→`, `c`, `f` and `x` act on. The thread list under it marks the selection with `❯`, and the footer shows the position as `2/3`.
+The selected exchange is the one expanded in the body and the one `⇧←/⇧→`, `e`, `c`, `f` and `x` act on. The thread list under it marks the selection with `❯`, and the footer shows the position as `2/3`.
+
+A question that wraps to more than three rows is folded to its first line plus a `… N more lines (e to show)` marker, so it does not push the answer — or the spinner while the request runs — out of the body. `e` unfolds the selected question; opening the overlay again starts folded.
 
 <img src="docs/btw-browse.png" alt="Browsing to an older side question: the thread list marks the selection and the footer shows 1/3" width="880">
 
@@ -52,6 +55,7 @@ The selected exchange is the one expanded in the body and the one `⇧←/⇧→
 - Promotion only appends, so the main conversation's cached prompt prefix stays valid. While a side request is still running, `f` waits instead of aborting it.
 - Side requests don't share the main conversation's prompt cache, so their input tokens are billed in full.
 - On narrow terminals the key hints wrap onto more rows and the answer area shrinks to keep them visible.
+- Depending on the fold, a state change reveals what changed: a folded question keeps the top of the exchange in view, an unfolded one scrolls to the answer (or to the error) below the question. On a terminal too short to show both, the answer or status row wins over the question top.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-btw-cc",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Claude Code-style /btw side questions for pi: a no-tools side thread in a floating overlay, persisted per session and promotable into the main conversation with one key.",
 	"type": "module",
 	"license": "MIT",

package/src/index.ts

@@ -9,9 +9,10 @@
  *   replayed into the next request. The thread is persisted in the session file
  *   as `btw-thread` custom entries, so it survives reloads, restarts and
  *   `/resume` of the same session, and follows the active `/tree` branch.
- * - Overlay keys: ↑/↓ scroll, ⇧←/→ browse the side thread, `c` copy the selected
- *   answer, `f` promote the selected exchange into the main conversation, `x`
- *   delete the selected exchange, Esc/Enter close.
+ * - Overlay keys: ↑/↓ scroll, ⇧←/→ browse the side thread, `e` expand or fold a
+ *   long question, `c` copy the selected answer, `f` promote the selected
+ *   exchange into the main conversation, `x` delete the selected exchange,
+ *   Esc/Enter close.
  * - `/btw` without a question reopens the overlay on the existing thread.
  *
  * Nothing reaches the main conversation unless `f` is pressed.

package/src/overlay.ts

@@ -15,15 +15,20 @@
  *
  * Only the body scrolls; the title bar and footer stay in place. `⇧←/→` moves
  * the selection: the selected exchange is the one expanded in the body and the
- * one `c`, `f` and `x` act on, and the dimmed window below the separator lists
- * the exchanges around it while marking the selected one, mirroring Claude
+ * one `e`, `c`, `f` and `x` act on, and the dimmed window below the separator
+ * lists the exchanges around it while marking the selected one, mirroring Claude
  * Code's overlay.
+ *
+ * A question that wraps to more than `QUESTION_COLLAPSE_LINES` rows is folded to
+ * its first line plus a `… N more lines (e to show)` marker, and `e` unfolds it.
+ * Without the fold a long question fills the whole body and pushes the answer or
+ * the pending spinner out of view; with it a state change only ever reveals the
+ * answer, the spinner or the error it belongs to.
  */
 
 import { randomUUID } from "node:crypto";
 import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
 import {
-	Container,
 	Key,
 	Markdown,
 	matchesKey,
@@ -31,6 +36,7 @@ import {
 	Text,
 	truncateToWidth,
 	visibleWidth,
+	wrapTextWithAnsi,
 	type Component,
 	type TUI,
 	type TuiMouseEvent,
@@ -115,6 +121,13 @@ export const OVERLAY_MIN_WIDTH = 60;
 /** Minimum and maximum body height in rows. */
 const MIN_BODY_ROWS = 4;
 const MAX_BODY_ROWS = 30;
+/**
+ * Wrapped question rows a question may take before it is folded.
+ *
+ * Three rows fit next to the answer on every supported terminal; a longer
+ * question would leave the body with no room for what the reader came for.
+ */
+const QUESTION_COLLAPSE_LINES = 3;
 
 export class BtwOverlay implements Component {
 	private readonly tui: TUI;
@@ -126,6 +139,22 @@ export class BtwOverlay implements Component {
 	private readonly done: (result: BtwOverlayResult) => void;
 
 	private thread: BtwExchange[];
+	/** Ids of exchanges whose long question is unfolded; every exchange starts folded. */
+	private readonly expandedIds = new Set<string>();
+	/** Unfold state of the in-flight question, carried over to the exchange it becomes. */
+	private pendingExpanded = false;
+	/**
+	 * Anchor the next paint scrolls to after a state change.
+	 *
+	 * `questionTop` is the explicit unfold request, `status` and `answer` are the
+	 * two blocks a finished request produces; null means the reader owns the scroll
+	 * position and no reveal may move it.
+	 */
+	private reveal: "questionTop" | "status" | "answer" | null = null;
+	/** First text row of the selected answer inside `contentLines`; -1 when absent. */
+	private answerStart = -1;
+	/** First text row of the pending spinner or error inside `contentLines`; -1 when absent. */
+	private statusStart = -1;
 	/** Index into `thread` of the exchange expanded in the body; always clamped. */
 	private selectedIndex = 0;
 	/** Footer rows the last render needed; the body shrinks when the footer wraps. */
@@ -201,6 +230,10 @@ export class BtwOverlay implements Component {
 			this.close();
 			return;
 		}
+		if (data === "e") {
+			this.toggleExpanded();
+			return;
+		}
 		if (data === "c") {
 			void this.copySelectedAnswer();
 			return;
@@ -224,7 +257,10 @@ export class BtwOverlay implements Component {
 	render(width: number): string[] {
 		const innerWidth = Math.max(24, width - 4);
 		if (this.dirty || this.cachedWidth !== innerWidth) {
-			this.contentLines = this.buildContent(innerWidth);
+			const content = this.buildContent(innerWidth);
+			this.contentLines = content.lines;
+			this.answerStart = content.answerStart;
+			this.statusStart = content.statusStart;
 			this.cachedWidth = innerWidth;
 			this.dirty = false;
 		}
@@ -233,6 +269,12 @@ export class BtwOverlay implements Component {
 		this.footerRows = footer.length;
 		const bodyHeight = this.bodyHeight();
 		const maxScroll = Math.max(0, this.contentLines.length - bodyHeight);
+		// The reveal runs after the content is measured, because both the target row
+		// and the body height come from the freshly built lines.
+		if (this.reveal !== null) {
+			this.scrollTop = Math.min(Math.max(0, this.revealTarget(bodyHeight)), maxScroll);
+			this.reveal = null;
+		}
 		if (this.scrollTop > maxScroll) this.scrollTop = maxScroll;
 		const visible = this.contentLines.slice(this.scrollTop, this.scrollTop + bodyHeight);
 
@@ -264,6 +306,9 @@ export class BtwOverlay implements Component {
 
 	private startAsk(question: string, ask: (signal: AbortSignal) => Promise<BtwQueryOutcome>): void {
 		this.pending = { question };
+		// A fresh question always starts folded, so the spinner under it is visible.
+		this.pendingExpanded = false;
+		this.reveal = "status";
 		this.abort = new AbortController();
 		this.spinnerTimer = setInterval(() => {
 			this.spinnerFrame = (this.spinnerFrame + 1) % SPINNER_FRAMES.length;
@@ -289,21 +334,28 @@ export class BtwOverlay implements Component {
 					replayed: this.replayedCount,
 				};
 				this.thread = appendExchange(this.thread, exchange);
+				// The fold state the reader chose while waiting carries over to the
+				// exchange the question becomes.
+				if (this.pendingExpanded) this.expandedIds.add(exchange.id);
+				this.pendingExpanded = false;
 				this.pending = null;
 				// A finished answer is what the reader wants to see next, so browsing
-				// ends here and the body scrolls back to the expanded newest exchange.
-				// The exchange appearing in the body is the whole signal; no footer
-				// flash is needed for it.
+				// ends here and the body reveals the newest exchange: a folded question
+				// keeps its exchange top, an unfolded one scrolls to the answer. The
+				// exchange appearing in the body is the whole signal; no footer flash is
+				// needed for it.
 				this.selectNewest();
 				this.sink.add(exchange);
-				this.setScroll(0);
+				this.reveal = "answer";
 				break;
 			}
 			case "error":
 				this.pending = { question, error: outcome.message };
+				this.reveal = "status";
 				break;
 			case "cancelled":
 				this.pending = { question, error: "The side request was cancelled." };
+				this.reveal = "status";
 				break;
 		}
 		this.dirty = true;
@@ -361,11 +413,12 @@ export class BtwOverlay implements Component {
 		}
 		this.thread = removeExchange(this.thread, selected.id);
 		this.sink.remove(selected.id);
+		this.expandedIds.delete(selected.id);
 		// Deleting moves the reader back to the newest remaining exchange, so a
 		// deletion never leaves the body pointing at an evicted index.
 		this.selectNewest();
 		this.dirty = true;
-		this.setScroll(0);
+		this.reveal = "answer";
 		this.flash("Deleted this side question");
 	}
 
@@ -385,12 +438,68 @@ export class BtwOverlay implements Component {
 		if (next === this.selectedIndex) return;
 		this.selectedIndex = next;
 		this.dirty = true;
-		// The expanded exchange is the first block of the body, so browsing
-		// always restarts at its top.
-		this.setScroll(0);
+		// The selected exchange builds the body from its first row, so browsing
+		// lands on the answer of a long unfolded question and on the whole folded
+		// block otherwise.
+		this.reveal = "answer";
 		this.tui.requestRender();
 	}
 
+	/** `e` folds or unfolds the question the reader is looking at. */
+	private toggleExpanded(): void {
+		const question = this.pending?.question ?? this.selectedExchange()?.question;
+		if (question === undefined || !this.isCollapsible(question)) return;
+		if (this.pending !== null) {
+			this.pendingExpanded = !this.pendingExpanded;
+		} else {
+			const id = this.selectedExchange()?.id;
+			if (id === undefined) return;
+			if (this.expandedIds.has(id)) this.expandedIds.delete(id);
+			else this.expandedIds.add(id);
+		}
+		this.dirty = true;
+		// Unfolding is a request to read the question from its first line; folding
+		// gives the body back to the answer or the spinner below it.
+		const expanded = this.pending !== null ? this.pendingExpanded : this.isSelectedExpanded();
+		this.reveal = expanded ? "questionTop" : this.pending !== null ? "status" : "answer";
+		this.tui.requestRender();
+	}
+
+	/** Whether the selected exchange has a long question unfolded right now. */
+	private isSelectedExpanded(): boolean {
+		const selected = this.selectedExchange();
+		if (selected === undefined) return false;
+		return this.expandedIds.has(selected.id) && this.isCollapsible(selected.question);
+	}
+
+	/**
+	 * Whether the question needs more rows than `QUESTION_COLLAPSE_LINES` at the last rendered width.
+	 *
+	 * `cachedWidth` is only set by a paint. Before the first one no width is known, and measuring at
+	 * -1 would report every question as folded, so a fold key arriving then has to be ignored
+	 * instead of recording a decision the question does not deserve.
+	 */
+	private isCollapsible(question: string): boolean {
+		if (this.cachedWidth <= 0) return false;
+		return wrapTextWithAnsi(this.questionLine(question), this.cachedWidth).length > QUESTION_COLLAPSE_LINES;
+	}
+
+	/**
+	 * Body row the next state change scrolls to.
+	 *
+	 * An unfolded question is taller than the body, so the answer (or the pending
+	 * status line) is pinned to the top and the question scrolls away above it. A
+	 * folded block is short enough to keep its exchange top, and the viewport only
+	 * moves as far as a very short body needs to keep the target row visible.
+	 */
+	private revealTarget(bodyHeight: number): number {
+		if (this.reveal === "questionTop") return 0;
+		const expanded = this.pending !== null ? this.pendingExpanded : this.isSelectedExpanded();
+		const target = this.reveal === "status" ? this.statusStart : this.answerStart;
+		if (expanded) return target;
+		return target < bodyHeight ? 0 : target - bodyHeight + 1;
+	}
+
 	private flash(text: string, tone: "success" | "warning" | "error" = "success"): void {
 		this.flashState = { text, tone };
 		if (this.flashTimer !== null) clearTimeout(this.flashTimer);
@@ -448,16 +557,31 @@ export class BtwOverlay implements Component {
 		return Math.max(1, Math.min(Math.floor((this.tui.terminal.rows * OVERLAY_MAX_HEIGHT_PERCENT) / 100), available));
 	}
 
-	private buildContent(innerWidth: number): string[] {
-		const container = new Container();
+	private buildContent(innerWidth: number): { lines: string[]; answerStart: number; statusStart: number } {
+		const lines: string[] = [];
+		let answerStart = -1;
+		let statusStart = -1;
+		/**
+		 * Append one child and return the row its first text line lands on.
+		 *
+		 * `paddingTop` is the child's vertical padding: a blank row above the text
+		 * means the reader would see that empty row first if a reveal pinned the
+		 * child itself, so the mark has to skip it.
+		 */
+		const push = (component: Component, paddingTop = 0): number => {
+			const start = lines.length + paddingTop;
+			for (const line of component.render(innerWidth)) lines.push(line);
+			return start;
+		};
 		const pending = this.pending;
 		const selected = this.selectedExchange();
 
 		if (pending !== null) {
 			// The in-flight question takes the expanded slot: every finished
-			// exchange moves into the dimmed window below it.
-			container.addChild(new Text(this.questionLine(pending.question), 0, 0));
-			container.addChild(
+			// exchange moves into the dimmed window below it. Unlike the finished
+			// exchange it has no blank row above it, so the spinner stays close.
+			push(new Text(this.questionBlockText(pending.question, this.pendingExpanded, innerWidth), 0, 0));
+			statusStart = push(
 				new Text(
 					pending.error !== undefined
 						? this.theme.fg("error", pending.error)
@@ -465,26 +589,25 @@ export class BtwOverlay implements Component {
 					0,
 					1,
 				),
+				1,
 			);
 		} else if (selected === undefined) {
-			container.addChild(
-				new Text(this.theme.fg("dim", "No side questions in this session yet. Run /btw <question> to ask one."), 0, 0),
-			);
+			push(new Text(this.theme.fg("dim", "No side questions in this session yet. Run /btw <question> to ask one."), 0, 0));
 		} else {
 			const count = this.thread.length;
-			container.addChild(new Text(this.theme.fg("dim", `${count} side question${count === 1 ? "" : "s"}`), 0, 0));
-			container.addChild(new Text(this.questionLine(selected.question), 0, 1));
-			container.addChild(new Markdown(selected.answer, 0, 1, getMarkdownTheme()));
+			push(new Text(this.theme.fg("dim", `${count} side question${count === 1 ? "" : "s"}`), 0, 0));
+			push(new Text(this.questionBlockText(selected.question, this.isSelectedExpanded(), innerWidth), 0, 1));
+			answerStart = push(new Markdown(selected.answer, 0, 1, getMarkdownTheme()), 1);
 		}
 
 		const listed = this.windowEntries();
 		if (listed.length > 0) {
-			container.addChild(new Spacer(1));
-			container.addChild(new Text(this.theme.fg("borderMuted", "─".repeat(innerWidth)), 0, 0));
-			container.addChild(new Spacer(1));
+			push(new Spacer(1));
+			push(new Text(this.theme.fg("borderMuted", "─".repeat(innerWidth)), 0, 0));
+			push(new Spacer(1));
 			const { start, end } = this.windowRange();
 			if (start > 0) {
-				container.addChild(new Text(this.theme.fg("dim", `… ${start} earlier`), 0, 0));
+				push(new Text(this.theme.fg("dim", `… ${start} earlier`), 0, 0));
 			}
 			for (const entry of listed) {
 				// The selected exchange is expanded above and listed here as well: the
@@ -492,14 +615,14 @@ export class BtwOverlay implements Component {
 				// reader currently is even while the expanded block is scrolled away.
 				const marker = entry.selected ? this.theme.fg("accent", "❯") : this.theme.fg("muted", "·");
 				const line = truncateToWidth(`${marker} ${this.theme.fg("muted", entry.exchange.question)}`, innerWidth, "…");
-				container.addChild(new Text(line, 0, 0));
+				push(new Text(line, 0, 0));
 			}
 			if (end < this.thread.length) {
-				container.addChild(new Text(this.theme.fg("dim", `… ${this.thread.length - end} newer`), 0, 0));
+				push(new Text(this.theme.fg("dim", `… ${this.thread.length - end} newer`), 0, 0));
 			}
 		}
 
-		return container.render(innerWidth);
+		return { lines, answerStart, statusStart };
 	}
 
 	/**
@@ -531,6 +654,25 @@ export class BtwOverlay implements Component {
 		return this.theme.fg("accent", "❯ ") + this.theme.fg("text", question);
 	}
 
+	/**
+	 * Rendered question block: the full question, or its first line plus a marker.
+	 *
+	 * A question that wraps to more than `QUESTION_COLLAPSE_LINES` rows is folded,
+	 * because it would otherwise push the answer or the spinner out of the body.
+	 * The marker states how many rows are hidden so nothing disappears silently,
+	 * and carries the `e` hint: a footer hint for it would push the key hints onto
+	 * an extra row, which costs the body its own row on every render.
+	 */
+	private questionBlockText(question: string, expanded: boolean, innerWidth: number): string {
+		const rendered = wrapTextWithAnsi(this.questionLine(question), innerWidth);
+		if (rendered.length <= QUESTION_COLLAPSE_LINES) return rendered.join("\n");
+		if (expanded) return [...rendered, this.theme.fg("dim", "  (e to hide)")].join("\n");
+		const hidden = rendered.length - 1;
+		// Cut the first line one column short so the ellipsis fits inside the frame.
+		const first = truncateToWidth(rendered[0] ?? "", innerWidth - 1, "") + "…";
+		return `${first}\n${this.theme.fg("dim", `  … ${hidden} more line${hidden === 1 ? "" : "s"} (e to show)`)}`;
+	}
+
 	private titleBar(width: number): string {
 		const left = "╭─" + this.theme.fg("accent", " btw ") + this.theme.fg("border", "─");
 		const labelWidth = Math.min(visibleWidth(this.modelLabel), Math.max(0, width - 14));