Skip to content

A self-improving RLM agent for coding workflows and long-running autonomous tasks.

Rust

add a sticky chat-name top bar to fullscreen chats (#2328)

kta5cc2371ec59
diff --git a/packages/coding-agent/.changes/chat-top-bar.md b/packages/coding-agent/.changes/chat-top-bar.md
new file mode 100644
index 0000000000..300c716b44
--- /dev/null
+++ b/packages/coding-agent/.changes/chat-top-bar.md
@@ -0,0 +1 @@
+- Fullscreen chats show a pinned top bar with the chat name centered in plain text and the session's total spend beside it; the bar stays visible in every scroll position and refreshes the spend after each turn.
diff --git a/packages/coding-agent/src/modes/interactive/components/top-bar.ts b/packages/coding-agent/src/modes/interactive/components/top-bar.ts
new file mode 100644
index 0000000000..6ece8000c8
--- /dev/null
+++ b/packages/coding-agent/src/modes/interactive/components/top-bar.ts
@@ -0,0 +1,50 @@
+import { type Component, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { theme } from "../theme/theme.js";
+
+export interface TopBarOptions {
+ getChatName: () => string | undefined;
+ /** Total session spend in USD (branch total, subagents included). */
+ getCostUsd?: () => number | undefined;
+}
+
+/**
+ * Pinned top bar for fullscreen chats: the chat name centered in plain text on
+ * the terminal background, with the session's spend beside it. Rendered as the
+ * fullscreen viewport's pinned header, so it stays on screen in every scroll
+ * position.
+ */
+export class TopBar implements Component {
+ private readonly options: TopBarOptions;
+
+ constructor(options: TopBarOptions) {
+ this.options = options;
+ }
+
+ invalidate(): void {
+ // Render output is derived from live session state via getters.
+ }
+
+ render(width: number): string[] {
+ const safeWidth = Math.max(1, width);
+ // Strip terminal control characters (C0, DEL, C1): a persisted session
+ // name could carry escape sequences that would execute on every bar
+ // repaint. Then collapse all whitespace: an embedded newline in the
+ // name would emit multiple rows and break the fixed fullscreen frame.
+ const name = (this.options.getChatName() ?? "")
+ .replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
+ .replace(/\s+/g, " ")
+ .trim();
+ if (!name) {
+ return [""];
+ }
+ // Center the name; the cost trails it with a small gap. No background,
+ // no rules: the bar should read as plain text on the terminal.
+ const nameWidth = visibleWidth(name);
+ const cost = this.options.getCostUsd?.();
+ const costText =
+ typeof cost === "number" && Number.isFinite(cost) && cost >= 0 ? theme.fg("dim", `$${cost.toFixed(2)}`) : "";
+ const start = Math.max(0, Math.floor((safeWidth - nameWidth) / 2));
+ const line = `${" ".repeat(start)}${theme.fg("text", name)}${costText ? ` ${costText}` : ""}`;
+ return [truncateToWidth(line, safeWidth, "")];
+ }
+}
diff --git a/packages/coding-agent/src/modes/interactive/interactive-mode.ts b/packages/coding-agent/src/modes/interactive/interactive-mode.ts
index 8baeba9d2f..6c14b2a4fe 100644
--- a/packages/coding-agent/src/modes/interactive/interactive-mode.ts
+++ b/packages/coding-agent/src/modes/interactive/interactive-mode.ts
@@ -249,6 +249,7 @@ import {
ToolExecutionComponent,
type ToolExecutionDefinition,
} from "./components/tool-execution.js";
+import { TopBar } from "./components/top-bar.js";
import { TreeSelectorComponent } from "./components/tree-selector.js";
import { UserMessageComponent } from "./components/user-message.js";
import { UserMessageSelectorComponent } from "./components/user-message-selector.js";
@@ -1104,6 +1105,12 @@ export class InteractiveMode {
private customFooter: (Component & { dispose?(): void }) | undefined = undefined;
private headerContainer: Container;
+ /** Pinned fullscreen top bar identifying the chat by name while scrolling. */
+ private topBar: TopBar;
+ /** Cached session spend (USD) for the top bar, keyed to the session it was fetched for. */
+ private topBarCost: { sessionId?: string; total?: number } = {};
+ /** Stale-discard state for top bar cost refreshes (mirrors contextUsageRefresh). */
+ private topBarCostRefresh = { generation: 0, lastSuccessGeneration: 0 };
private builtInHeader: Component | undefined = undefined;
@@ -1152,6 +1159,14 @@ export class InteractiveMode {
void this.copyFullscreenSelection(text);
};
this.headerContainer = new Container();
+ this.topBar = new TopBar({
+ getChatName: () => this.getCurrentSessionName() ?? path.basename(this.getCurrentCwd()),
+ // Hide the cached spend unless it was fetched for the session now bound:
+ // a pending or failed refresh must not attribute the previous
+ // session's spend to the new chat.
+ getCostUsd: () =>
+ this.topBarCost.sessionId === this.connectionState?.sessionId ? this.topBarCost.total : undefined,
+ });
this.chatContainer = new Container();
this.shortcutGuideContainer = new Container();
this.pendingMessagesContainer = new Container();
@@ -1519,6 +1534,43 @@ export class InteractiveMode {
await this.updateAvailableProviderCount();
}
+ /**
+ * Refresh the top bar's cached session spend from the context tree.
+ * Results for a replaced session, or superseded by a newer successful
+ * refresh, are discarded — mirroring refreshConnectionContextUsage.
+ */
+ private refreshTopBarCost(): void {
+ // Partial-mode test harnesses skip the constructor, so the field
+ // initializer may be absent there; the refresh is cosmetic and must
+ // never crash a real flow on any `this`.
+ this.topBarCostRefresh ??= { generation: 0, lastSuccessGeneration: 0 };
+ const refresh = this.topBarCostRefresh;
+ const generation = ++refresh.generation;
+ const connection = this.agentConnection;
+ const sessionId = this.connectionState?.sessionId;
+ void (async () => {
+ try {
+ const tree = await connection.getContextTree();
+ const total = tree?.totalUsage?.cost?.total;
+ if (
+ typeof total !== "number" ||
+ !Number.isFinite(total) ||
+ generation < refresh.lastSuccessGeneration ||
+ this.agentConnection !== connection ||
+ this.connectionState?.sessionId !== sessionId
+ ) {
+ return;
+ }
+ refresh.lastSuccessGeneration = generation;
+ this.topBarCost = { sessionId, total };
+ this.ui.requestRender();
+ } catch {
+ // Cost is cosmetic; a failed fetch keeps the previous value
+ // (the session-keyed getter still hides cross-session leaks).
+ }
+ })();
+ }
+
private updateTerminalTitle(): void {
const cwdBasename = path.basename(this.getCurrentCwd());
const sessionName = this.getCurrentSessionName();
@@ -2892,6 +2944,7 @@ export class InteractiveMode {
await this.updateAvailableProviderCount();
this.updateEditorBorderColor();
this.updateTerminalTitle();
+ this.refreshTopBarCost();
this.setGoalAnnouncementBaseline(this.getGoalState());
this.syncGoalTray(this.getGoalState());
this.syncWorkingLoader();
@@ -3016,6 +3069,7 @@ export class InteractiveMode {
this.sideQuestionBashDiscarded = undefined;
}
this.updateTerminalTitle();
+ this.refreshTopBarCost();
this.setGoalAnnouncementBaseline(this.getGoalState());
this.syncGoalTray(this.getGoalState());
this.syncWorkingLoader();
@@ -3546,6 +3600,7 @@ export class InteractiveMode {
this.setupAutocompleteProvider();
this.defaultEditor.onExtensionShortcut = undefined;
this.updateTerminalTitle();
+ this.refreshTopBarCost();
this.workingMessage = undefined;
this.workingVisible = true;
this.setWorkingIndicator();
@@ -5198,6 +5253,7 @@ export class InteractiveMode {
this.sessionRecap = event.recap;
this.patchConnectionState({ recap: event.recap });
this.renderRecap();
+ this.refreshTopBarCost();
} else if (event.type === "side_question_event") {
this.handleSideQuestionEvent(event.event);
} else if (event.type === "extension_ui_request") {
@@ -5444,6 +5500,7 @@ export class InteractiveMode {
case "session_info_changed":
this.updateTerminalTitle();
+ this.refreshTopBarCost();
this.footer.invalidate();
this.ui.requestRender();
break;
@@ -5688,6 +5745,7 @@ export class InteractiveMode {
this.ui.terminal.setProgress(false);
}
this.turnStartedAt = undefined;
+ this.refreshTopBarCost();
// Drops the loader; background subagents are shown by the tree, not the loader.
this.syncWorkingLoader();
if (this.streamingComponent) {
@@ -7383,6 +7441,7 @@ export class InteractiveMode {
this.widgetContainerBelow,
],
dock: this.promptDock,
+ pin: this.topBar,
mouse: this.settingsManager.getFullscreenMouse(),
});
} else {
diff --git a/packages/coding-agent/test/interactive-mode-status.test.ts b/packages/coding-agent/test/interactive-mode-status.test.ts
index 9a9231b1e7..c681233648 100644
--- a/packages/coding-agent/test/interactive-mode-status.test.ts
+++ b/packages/coding-agent/test/interactive-mode-status.test.ts
@@ -1595,6 +1595,7 @@ describe("InteractiveMode connection events", () => {
updateAvailableProviderCount: vi.fn(async () => {}),
updateEditorBorderColor: vi.fn(),
updateTerminalTitle: vi.fn(),
+ refreshTopBarCost: vi.fn(),
setGoalAnnouncementBaseline: vi.fn(),
syncGoalTray: vi.fn(),
syncWorkingLoader: vi.fn(),
@@ -1840,6 +1841,7 @@ describe("InteractiveMode connection events", () => {
restoreStreamingMessageFromSnapshot: vi.fn(),
updatePendingMessagesDisplay: vi.fn(),
updateTerminalTitle: vi.fn(),
+ refreshTopBarCost: vi.fn(),
setGoalAnnouncementBaseline: vi.fn(),
syncGoalTray: vi.fn(),
syncWorkingLoader: vi.fn(),
@@ -1906,6 +1908,7 @@ describe("InteractiveMode connection events", () => {
updatePendingMessagesDisplay: vi.fn(),
flushPendingBashComponents: vi.fn(),
updateTerminalTitle: vi.fn(),
+ refreshTopBarCost: vi.fn(),
setGoalAnnouncementBaseline: vi.fn(),
syncGoalTray: vi.fn(),
syncWorkingLoader: vi.fn(),
@@ -1967,6 +1970,7 @@ describe("InteractiveMode connection events", () => {
updatePendingMessagesDisplay: vi.fn(),
flushPendingBashComponents,
updateTerminalTitle: vi.fn(),
+ refreshTopBarCost: vi.fn(),
setGoalAnnouncementBaseline: vi.fn(),
syncGoalTray: vi.fn(),
syncWorkingLoader: vi.fn(),
@@ -3359,6 +3363,7 @@ describe("InteractiveMode session switch command catalog", () => {
updateAvailableProviderCount: vi.fn(async () => {}),
updateEditorBorderColor: vi.fn(),
updateTerminalTitle: vi.fn(),
+ refreshTopBarCost: vi.fn(),
setGoalAnnouncementBaseline: vi.fn(),
syncGoalTray: vi.fn(),
getGoalState: () => emptyGoalState(),
diff --git a/packages/coding-agent/test/interactive-mode-streaming.test.ts b/packages/coding-agent/test/interactive-mode-streaming.test.ts
index 1a8f4d0628..1677a42d27 100644
--- a/packages/coding-agent/test/interactive-mode-streaming.test.ts
+++ b/packages/coding-agent/test/interactive-mode-streaming.test.ts
@@ -53,6 +53,7 @@ type HandleEventThis = {
checkShutdownRequested(): Promise<void>;
applyOptimisticContextUsage(): void;
refreshConnectionContextUsage(): Promise<void>;
+ refreshTopBarCost(): void;
clearShortcutGuide(): void;
addMessageToChat(): void;
};
@@ -102,6 +103,7 @@ function createFakeInteractiveModeThis(): HandleEventThis {
checkShutdownRequested: vi.fn(async () => {}),
applyOptimisticContextUsage: vi.fn(),
refreshConnectionContextUsage: vi.fn(async () => {}),
+ refreshTopBarCost: vi.fn(),
clearShortcutGuide: vi.fn(),
addMessageToChat: vi.fn(),
};
diff --git a/packages/coding-agent/test/suite/regressions/2295-startup-navigation.test.ts b/packages/coding-agent/test/suite/regressions/2295-startup-navigation.test.ts
index 5aa77d8d99..0b45123479 100644
--- a/packages/coding-agent/test/suite/regressions/2295-startup-navigation.test.ts
+++ b/packages/coding-agent/test/suite/regressions/2295-startup-navigation.test.ts
@@ -36,6 +36,7 @@ describe("back navigation during chat startup", () => {
updateAvailableProviderCount: vi.fn(async () => {}),
updateEditorBorderColor: vi.fn(),
updateTerminalTitle: vi.fn(),
+ refreshTopBarCost: vi.fn(),
setGoalAnnouncementBaseline: vi.fn(),
getGoalState: vi.fn(),
syncGoalTray: vi.fn(),
diff --git a/packages/coding-agent/test/suite/regressions/4509-side-questions.test.ts b/packages/coding-agent/test/suite/regressions/4509-side-questions.test.ts
index c0f4d47625..ca3153f0b9 100644
--- a/packages/coding-agent/test/suite/regressions/4509-side-questions.test.ts
+++ b/packages/coding-agent/test/suite/regressions/4509-side-questions.test.ts
@@ -1060,6 +1060,7 @@ describe("ENG-4509 side questions", () => {
flushCompactionQueue: vi.fn(async () => {}),
flushPendingBashComponents: vi.fn(),
updateTerminalTitle: vi.fn(),
+ refreshTopBarCost: vi.fn(),
setGoalAnnouncementBaseline: vi.fn(),
syncGoalTray: vi.fn(),
syncWorkingLoader: vi.fn(),
diff --git a/packages/coding-agent/test/top-bar.test.ts b/packages/coding-agent/test/top-bar.test.ts
new file mode 100644
index 0000000000..f4df191fc2
--- /dev/null
+++ b/packages/coding-agent/test/top-bar.test.ts
@@ -0,0 +1,51 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { TopBar } from "../src/modes/interactive/components/top-bar.js";
+import { initTheme } from "../src/modes/interactive/theme/theme.js";
+
+beforeEach(() => {
+ initTheme("dark");
+});
+
+const stripAnsi = (value: string): string => value.replace(/\x1b\[[0-9;]*m/g, "");
+
+describe("TopBar", () => {
+ it("centers the chat name and trails the spend beside it", () => {
+ const bar = new TopBar({ getChatName: () => "demo", getCostUsd: () => 1.42 });
+ const [line] = bar.render(21);
+ const plain = stripAnsi(line);
+ expect(plain).toBe(" demo $1.42");
+ });
+
+ it("renders only the name when no spend is known", () => {
+ const bar = new TopBar({ getChatName: () => "demo", getCostUsd: () => undefined });
+ const [line] = bar.render(21);
+ expect(stripAnsi(line)).toBe(" demo");
+ });
+
+ it("collapses embedded newlines so the bar stays a single row", () => {
+ const bar = new TopBar({ getChatName: () => "line1\nline2" });
+ const lines = bar.render(21);
+ expect(lines).toHaveLength(1);
+ expect(stripAnsi(lines[0])).toContain("line1 line2");
+ });
+
+ it("strips terminal escape sequences from the chat name", () => {
+ const bar = new TopBar({ getChatName: () => "a\u001b[2Jb\u001b]0;title\u0007c" });
+ const [line] = bar.render(30);
+ const plain = stripAnsi(line);
+ expect(plain).not.toContain("\u001b");
+ expect(plain).not.toContain("\u0007");
+ expect(plain).toContain("a [2Jb ]0;title c");
+ });
+
+ it("returns a blank line when the chat name is empty", () => {
+ const bar = new TopBar({ getChatName: () => undefined });
+ expect(bar.render(21)).toEqual([""]);
+ });
+
+ it("truncates to the terminal width", () => {
+ const bar = new TopBar({ getChatName: () => "a-very-long-chat-name-that-overflows", getCostUsd: () => 9.99 });
+ const [line] = bar.render(12);
+ expect(stripAnsi(line).length).toBeLessThanOrEqual(12);
+ });
+});
diff --git a/packages/tui/.changes/chat-top-bar.md b/packages/tui/.changes/chat-top-bar.md
new file mode 100644
index 0000000000..b15fcc1132
--- /dev/null
+++ b/packages/tui/.changes/chat-top-bar.md
@@ -0,0 +1 @@
+- Fullscreen frames can pin a component above the scrolling transcript: the viewport composes header, window, and dock rows and maps mouse selection, dock click targets, and the follow hint through the header offset.
diff --git a/packages/tui/src/fullscreen.ts b/packages/tui/src/fullscreen.ts
index 45a7c3617f..d184d56e96 100644
--- a/packages/tui/src/fullscreen.ts
+++ b/packages/tui/src/fullscreen.ts
@@ -79,6 +79,7 @@ export class FullscreenViewport {
private prevHeight = 0;
private lastMaxScroll = 0;
private lastWindowHeight = 0;
+ private lastHeaderHeight = 0;
private lastTranscript: string[] = [];
private lastFrame: string[] = [];
private lastFrameVisibleStart = 0;
@@ -92,22 +93,33 @@ export class FullscreenViewport {
private selectionMode: SelectionMode | null = null;
/**
- * Compose a frame of exactly `height` lines: scrolled transcript window on
- * top, dock pinned to the bottom. Following pins the window to the
- * transcript end; otherwise it stays frozen while content appends.
+ * Compose a frame of exactly `height` lines: an optional pinned header on
+ * top, the scrolled transcript window in the middle, and the dock pinned
+ * to the bottom. Following pins the window to the transcript end;
+ * otherwise it stays frozen while content appends.
*/
composeFrame(
transcript: string[],
dock: string[],
height: number,
tableCellSelectionRegions: ReadonlyArray<TableCellSelectionRegion> = [],
+ header?: string[],
): string[] {
let dockLines = dock;
const dockHeight = clippedFullscreenDockHeight(dockLines.length, height);
if (dockLines.length > dockHeight) {
dockLines = dockLines.slice(dockLines.length - dockHeight);
}
- const windowHeight = height - dockLines.length;
+ let headerLines = header ?? [];
+ // Header rows are taken away from the transcript window, never from the
+ // dock; a too-tall header is clipped from the top like the dock clips
+ // from its bottom, so the bar keeps its bottom rows.
+ const maxHeader = Math.max(0, height - dockLines.length - FULLSCREEN_MIN_TRANSCRIPT_ROWS);
+ const headerHeight = Math.min(headerLines.length, maxHeader);
+ if (headerLines.length > headerHeight) {
+ headerLines = headerLines.slice(headerLines.length - headerHeight);
+ }
+ const windowHeight = height - dockLines.length - headerLines.length;
const maxScroll = Math.max(0, transcript.length - windowHeight);
if (this.following) {
@@ -117,6 +129,7 @@ export class FullscreenViewport {
}
this.lastMaxScroll = maxScroll;
this.lastWindowHeight = windowHeight;
+ this.lastHeaderHeight = headerLines.length;
this.lastTranscript = transcript;
this.tableCellSelectionRegions = tableCellSelectionRegions;
@@ -128,7 +141,7 @@ export class FullscreenViewport {
while (window.length < windowHeight) {
window.push("");
}
- return [...window, ...dockLines];
+ return [...headerLines, ...window, ...dockLines];
}
private orderedSelection(): { start: SelectionPoint; end: SelectionPoint } | null {
@@ -361,8 +374,12 @@ export class FullscreenViewport {
if (visibleHeight <= 0) return null;
const visibleStart = this.lastFrameVisibleHeight > 0 ? this.lastFrameVisibleStart : 0;
const visibleEnd = visibleStart + visibleHeight - 1;
- const transcriptStart = Math.max(0, visibleStart);
- const transcriptEnd = Math.min(this.lastWindowHeight - 1, visibleEnd);
+ // The transcript window occupies frame rows [headerHeight, headerHeight +
+ // windowHeight); the pinned header sits above it and the dock below.
+ const windowStart = this.lastHeaderHeight;
+ const windowEnd = this.lastHeaderHeight + this.lastWindowHeight - 1;
+ const transcriptStart = Math.max(windowStart, visibleStart);
+ const transcriptEnd = Math.min(windowEnd, visibleEnd);
if (transcriptStart > transcriptEnd) return null;
return {
firstRow: transcriptStart - visibleStart,
@@ -381,7 +398,8 @@ export class FullscreenViewport {
const row = clamp ? Math.max(0, Math.min(screenRow, bounds.visibleHeight - 1)) : screenRow;
const frameLine = bounds.visibleStart + row;
if (!clamp && (frameLine < bounds.transcriptStart || frameLine > bounds.transcriptEnd)) return null;
- return this.scrollTop + Math.max(bounds.transcriptStart, Math.min(frameLine, bounds.transcriptEnd));
+ const clampedFrameLine = Math.max(bounds.transcriptStart, Math.min(frameLine, bounds.transcriptEnd));
+ return this.scrollTop + clampedFrameLine - this.lastHeaderHeight;
}
private isFrameSelectable(point: SelectionPoint): boolean {
@@ -701,6 +719,11 @@ export class FullscreenViewport {
return this.lastWindowHeight;
}
+ /** Rows the pinned header currently occupies at the top of the frame. */
+ headerHeight(): number {
+ return this.lastHeaderHeight;
+ }
+
isFollowing(): boolean {
return this.following;
}
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index 6c45635690..ce0f412c6b 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -86,6 +86,8 @@ export interface TuiStopOptions {
export interface FullscreenOptions {
scroll: Component[];
dock: Component;
+ /** Pinned above the scrolling transcript — stays on top while scrolling. */
+ pin?: Component;
mouse?: boolean;
viewportControls?: boolean;
}
@@ -339,6 +341,7 @@ export class TUI extends Container {
viewport: FullscreenViewport;
scroll: Component[];
dock: Component;
+ pin: Component | undefined;
mouse: boolean;
viewportControls: boolean;
inlineState: {
@@ -686,6 +689,7 @@ export class TUI extends Container {
viewport: new FullscreenViewport(),
scroll: options.scroll,
dock: options.dock,
+ pin: options.pin,
mouse: options.mouse !== false,
viewportControls: options.viewportControls !== false,
inlineState: {
@@ -1301,13 +1305,9 @@ export class TUI extends Container {
return visibleContentSpan(line, maxWidth);
}
- private createDockSelectionRegions(
- frame: string[],
- transcriptWindowHeight: number,
- width: number,
- ): FrameSelectionRegion[] {
+ private createDockSelectionRegions(frame: string[], firstDockRow: number, width: number): FrameSelectionRegion[] {
const regions: FrameSelectionRegion[] = [];
- for (let row = Math.max(0, transcriptWindowHeight); row < frame.length; row++) {
+ for (let row = Math.max(0, firstDockRow); row < frame.length; row++) {
const span = this.selectableSpan(frame[row] ?? "", width);
if (span) {
regions.push({ line: row, col: span.from, width: span.to - span.from });
@@ -1508,10 +1508,15 @@ export class TUI extends Container {
}
return fullscreen.dock.render(width);
});
+ const header = withFullscreenImageFallback(() => fullscreen.pin?.render(width) ?? []);
- let frame = fullscreen.viewport.composeFrame(transcript, dock, height, selectionRegions);
+ let frame = fullscreen.viewport.composeFrame(transcript, dock, height, selectionRegions, header);
this.overlaySelectionRegions.push(
- ...this.createDockSelectionRegions(frame, fullscreen.viewport.windowHeight(), width),
+ ...this.createDockSelectionRegions(
+ frame,
+ fullscreen.viewport.headerHeight() + fullscreen.viewport.windowHeight(),
+ width,
+ ),
);
const scrollInfo = fullscreen.viewport.scrollInfo();
if (fullscreen.viewportControls && !scrollInfo.following) {
@@ -1520,7 +1525,7 @@ export class TUI extends Container {
const followKey = getKeybindings().getKeys("tui.viewport.follow")[0] ?? "ctrl+shift+down";
const label = ` ${followKey} to follow `;
const labelWidth = visibleWidth(label);
- const row = fullscreen.viewport.windowHeight() - 1;
+ const row = fullscreen.viewport.headerHeight() + fullscreen.viewport.windowHeight() - 1;
if (row >= 0 && row < frame.length && labelWidth <= width) {
const col = Math.floor((width - labelWidth) / 2);
frame[row] = this.compositeLineAt(frame[row], `\x1b[7m${label}\x1b[27m`, col, labelWidth, width);
diff --git a/packages/tui/test/fullscreen.test.ts b/packages/tui/test/fullscreen.test.ts
index 99b5e89440..61e0f9117d 100644
--- a/packages/tui/test/fullscreen.test.ts
+++ b/packages/tui/test/fullscreen.test.ts
@@ -121,6 +121,71 @@ describe("TUI fullscreen mode", () => {
tui.stop();
});
+ it("pins a header above the transcript that stays on top while scrolling", async () => {
+ const { terminal, tui, chat, dock } = setup(lines(20));
+ const pin = new TestComponent();
+ pin.lines = ["== chat name =="];
+ tui.enterFullscreen({ scroll: [chat], dock, pin });
+ await terminal.waitForRender();
+
+ let viewport = terminal.getViewport();
+ assert.strictEqual(viewport[0], "== chat name ==", "pin renders as the top row");
+ assert.strictEqual(viewport[1], "Line 13", "transcript window starts below the pin");
+ assert.strictEqual(viewport[7], "Line 19");
+ assert.strictEqual(viewport[8], "> prompt");
+ assert.strictEqual(viewport[9], "footer", "dock stays at the bottom");
+
+ terminal.sendInput(WHEEL_UP);
+ await terminal.waitForRender();
+ viewport = terminal.getViewport();
+ assert.strictEqual(viewport[0], "== chat name ==", "pin stays on top after scrolling");
+ assert.notStrictEqual(viewport[1], "Line 13", "transcript scrolled under the pin");
+
+ tui.stop();
+ });
+
+ it("maps drag selection to transcript rows below the pinned header", async () => {
+ const { terminal, tui, chat, dock } = setup(lines(20));
+ const pin = new TestComponent();
+ pin.lines = ["pinned"];
+ const copies: string[] = [];
+ tui.onCopy = (text) => copies.push(text);
+ tui.enterFullscreen({ scroll: [chat], dock, pin });
+ await terminal.waitForRender();
+
+ terminal.sendInput("\x1b[<0;1;2M");
+ terminal.sendInput("\x1b[<32;6;3M");
+ await terminal.waitForRender();
+ assert.ok(terminal.getWrites().includes("\x1b[7m"), "selection highlighted while dragging");
+
+ terminal.sendInput("\x1b[<0;6;3m");
+ await terminal.waitForRender();
+ assert.deepStrictEqual(copies, ["Line 13\nLine"]);
+
+ tui.stop();
+ });
+
+ it("drag-selecting dock text still copies with a pinned header", async () => {
+ const { terminal, tui, chat, dock } = setup(lines(20));
+ const pin = new TestComponent();
+ pin.lines = ["pinned"];
+ const copies: string[] = [];
+ tui.onCopy = (text) => copies.push(text);
+ tui.enterFullscreen({ scroll: [chat], dock, pin });
+ await terminal.waitForRender();
+
+ terminal.sendInput("\x1b[<0;3;9M");
+ terminal.sendInput("\x1b[<32;9;9M");
+ await terminal.waitForRender();
+ assert.ok(terminal.getWrites().includes("\x1b[7m"), "dock selection highlighted while dragging");
+
+ terminal.sendInput("\x1b[<0;9;9m");
+ await terminal.waitForRender();
+ assert.deepStrictEqual(copies, ["prompt"]);
+
+ tui.stop();
+ });
+
it("renders terminal images as compact metadata fallbacks", async () => {
setCapabilities({ images: "kitty", trueColor: true, hyperlinks: true });
setCellDimensions({ widthPx: 10, heightPx: 10 });