@oh-my-pi/pi-tui 15.9.3 → 15.9.67

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 ## [Unreleased]
 
+## [15.9.67] - 2026-06-06
+### Added
+
+- Added `setPaddingX` to `Box` so horizontal padding can be updated programmatically after creation
+- Added `ScrollView`, a fixed-height viewport component for pre-rendered lines with optional right-edge scrollbars and imperative scroll/page controls.
+- Added optional `Terminal.hasEagerEraseScrollbackRisk()` so custom/test terminal implementations can override the global ED3-risk profile without mutating the shared `TERMINAL` object.
+
+### Changed
+
+- Changed `SelectList` to render its visible window through `ScrollView`, replacing the `(N/M)` text scroll indicator with a uniform right-edge scrollbar (the type-to-search hint line is preserved).
+
+### Fixed
+
+- Fixed unknown-viewport deferred renders freezing bottom-anchored live chrome; deferred history mutations can now repaint only the active-grid bottom row with relative cursor movement, so spinner/status tails keep advancing without rewriting rows a scrolled reader can still see.
+- Fixed autocomplete popups freezing live repaint on ED3-risk macOS/POSIX terminals with unknown native viewport position; direct autocomplete shrink frames now repaint the live viewport without zero-byte deferral and preserve the old bottom anchor when padding can clear stale popup rows without duplicating committed scrollback.
+- Fixed focused Up/Down navigation on ED3-risk macOS/POSIX terminals replaying the whole transcript after dirty foreground-stream renders; selector/editor frames now repaint non-destructively instead of emitting `CSI 3 J` on every arrow-key move ([#1962](https://github.com/can1357/oh-my-pi/issues/1962)).
+- Fixed tmux (and screen/zellij) pane scrollback losing the head of a long streamed assistant reply once it grew past the visible pane, and stranding the chrome/footer in pane history after a later collapse — producing the "repeating chunks and missing sections" reporters saw when scrolling back through tmux pane history ([#1974](https://github.com/can1357/oh-my-pi/issues/1974)). The renderer's foreground-streaming cap-to-viewport branch (introduced in 15.9.2 for ED3-risk hosts that can checkpoint-rebuild later) also activated inside multiplexers, where checkpoint reconcile is a no-op (`refreshNativeScrollbackIfDirty` short-circuits because `\x1b[3J` cannot erase pane history). Every streaming frame clipped `lines` to the visible tail and reset `#scrollbackHighWater` to 0, so any row that scrolled above the viewport top was committed nowhere — pane history stayed empty until streaming ended. Meanwhile `#planLiveRegionPinnedRender` was explicitly disabled for multiplexers, but its `#emitLiveRegionPinnedRepaint` is built from the exact primitives tmux accepts (relative cursor moves, per-line `\x1b[2K`, `\r\n` to scroll the sealed prefix past the viewport bottom) and never emits `\x1b[2J`/`\x1b[3J`. The pinned planner now runs in multiplexers too, the cap branch skips them, and the diff/append path commits incrementally into pane history; the actively-mutating live tail stays in the visible viewport only.
+
+## [15.9.5] - 2026-06-05
+
+### Changed
+
+- Changed terminal resize handling so any width or height change always performs a clean reset + redraw: the renderer now unconditionally clears the viewport and native scrollback (`CSI 2 J` / `CSI 3 J`) and replays the full transcript at the new geometry, replacing the previous matrix of conditional viewport-repaint / history-rebuild / deferred-mutation branches. Multiplexer panes still repaint the visible window in place (pane scrollback cannot be erased), but a resize during active ED3-risk foreground streaming now performs the same clean rebuild rather than downgrading to a non-destructive viewport repaint: the terminal already re-wrapped its saved lines at the old width, so the rebuild must erase them (ED 3) instead of leaving the mis-wrapped history on screen. As a deliberate tradeoff this drops the prior no-overflow and confirmed-scrolled guards on resize: a reader scrolled into history snaps back to the bottom and preexisting shell scrollback above the UI is cleared.
+
+### Fixed
+
+- Fixed ED3-risk foreground streaming dropping the scrolled-off head of an append-only live block that alone overflows the viewport (a long streamed assistant reply). The live-region pin again committed native scrollback only up to the live-region start, so once the live block grew past the viewport its earlier rows scrolled above the viewport top but were committed nowhere and repainted nowhere — they vanished, leaving the reply looking like a ~viewport-tall circular buffer. The `NativeScrollbackLiveRegion` seam now also reports an optional append-only `getNativeScrollbackCommitSafeEnd`, and the pinned commit boundary is the deeper of the sealed start and that append-only end: rows in `[liveRegionStart, commitSafeEnd)` above the viewport top commit to scrollback, while volatile live blocks (tool previews that collapse) omit the boundary and keep their mutable rows deferred — preserving the pending-box-above-running-box fix.
+
+## [15.9.4] - 2026-06-05
+
+### Added
+
+- Added `PI_TUI_SYNC_OUTPUT=0` and `PI_TUI_SYNC_OUTPUT=1` to explicitly disable or force-enable DEC 2026 synchronized-output mode, alongside `PI_FORCE_SYNC_OUTPUT=1` as a force-on alias
+- Added `PI_TUI_ED3_SAFE=1` environment override to treat a terminal as non-ED3-risk for eager native scrollback rebuilds on unknown POSIX hosts
+
+### Changed
+
+- Changed native-scrollback safety defaults to treat unknown POSIX, SSH, and multiplexer-shaped terminals as ED3-risk for passive rendering; checkpoint replay now requires a positive at-tail viewport proof instead of assuming prompt submit makes host scrollback safe.
+- Changed synchronized-output defaults to a conservative opt-in profile: DEC 2026 paint wrappers stay disabled for remote/multiplexer/VTE/unknown terminals unless explicitly forced, while the autowrap guards remain active.
+
+### Fixed
+
+- Fixed ED3-risk unknown-viewport renders repainting offscreen structural edits over stale native scrollback, which could duplicate or shift rows when async blocks collapsed or middle rows were deleted.
+- Fixed ED3-risk foreground streams committing mutable live-region rows into native scrollback, which could leave a stale `pending` tool box above the `running` box after the preview re-rendered.
+- Fixed TUI shutdown leaving paint-time terminal state and Kitty image data behind by restoring synchronized-output/autowrap modes and purging all transmitted Kitty image ids on stop.
+- Fixed stdin buffering splitting surrogate-pair text into UTF-16 halves and reduced timing sensitivity for incomplete escape sequences.
+- Fixed terminal content not reflowing after a resize on terminals using DEC 2048 in-band resize (kitty/Ghostty/iTerm2/WezTerm). `ProcessTerminal.columns`/`rows` returned the last cached in-band report even after the OS already knew the new size, so a SIGWINCH whose in-band report was dropped or malformed (split past the stdin flush window, `:`-subparameter fields) re-rendered the whole transcript at the stale width. OS resize events now reconcile cached in-band geometry against the live `process.stdout` dimensions, dropping a stale cached value so the next render uses the true size; a valid in-band report still re-seeds pixel sizing.
+
 ## [15.9.3] - 2026-06-05
 
 ### Fixed
@@ -1043,4 +1091,4 @@ Initial release under @oh-my-pi scope. See previous releases at [badlogic/pi-mon
 
 ### Fixed
 
-- **Readline-style Ctrl+W**: Now skips trailing whitespace before deleting the preceding word, matching standard readline behavior. ([#306](https://github.com/badlogic/pi-mono/pull/306) by [@kim0](https://github.com/kim0))
+- **Readline-style Ctrl+W**: Now skips trailing whitespace before deleting the preceding word, matching standard readline behavior. ([#306](https://github.com/badlogic/pi-mono/pull/306) by [@kim0](https://github.com/kim0))

package/dist/types/components/box.d.ts

@@ -9,6 +9,7 @@ export declare class Box implements Component {
     addChild(component: Component): void;
     removeChild(component: Component): void;
     clear(): void;
+    setPaddingX(paddingX: number): void;
     setBgFn(bgFn?: (text: string) => string): void;
     invalidate(): void;
     render(width: number): string[];

package/dist/types/components/image.d.ts

@@ -64,6 +64,8 @@ export declare class ImageBudget {
     endPass(): boolean;
     /** Image ids to delete from the terminal this frame; clears the pending set. */
     takePurgeIds(): readonly number[];
+    /** All image ids believed to be loaded in the terminal store; clears tracking. */
+    takeAllTransmittedIds(): readonly number[];
     /** Whether `imageId`'s data still needs to be transmitted to the terminal. */
     shouldTransmit(imageId: number): boolean;
     /**

package/dist/types/components/scroll-view.d.ts

@@ -0,0 +1,40 @@
+import type { Component } from "../tui";
+type ScrollbarMode = "auto" | "always" | "never";
+export interface ScrollViewTheme {
+    track?: (text: string) => string;
+    thumb?: (text: string) => string;
+}
+export interface ScrollViewOptions {
+    height: number;
+    /** Defaults to "auto". "auto" reserves a scrollbar column only when content overflows. */
+    scrollbar?: ScrollbarMode | boolean;
+    /** Logical row count for pre-windowed line slices. Defaults to lines.length. */
+    totalRows?: number;
+    theme?: ScrollViewTheme;
+    trackChar?: string;
+    thumbChar?: string;
+}
+/**
+ * Fixed-height viewport over pre-rendered lines, with optional right-edge scrollbar.
+ *
+ * ScrollView owns only the row offset. Callers remain responsible for producing
+ * already-wrapped logical lines appropriate for the current render width.
+ */
+export declare class ScrollView implements Component {
+    #private;
+    constructor(lines: readonly string[], options: ScrollViewOptions);
+    setLines(lines: readonly string[]): void;
+    setTotalRows(totalRows: number | undefined): void;
+    setHeight(height: number): void;
+    setScrollbar(scrollbar: ScrollViewOptions["scrollbar"]): void;
+    getScrollOffset(): number;
+    getMaxScrollOffset(): number;
+    setScrollOffset(offset: number): void;
+    scroll(delta: number): void;
+    page(delta: number): void;
+    scrollToTop(): void;
+    scrollToBottom(): void;
+    invalidate(): void;
+    render(width: number): string[];
+}
+export {};

package/dist/types/index.d.ts

@@ -6,6 +6,7 @@ export * from "./components/image";
 export * from "./components/input";
 export * from "./components/loader";
 export * from "./components/markdown";
+export * from "./components/scroll-view";
 export * from "./components/select-list";
 export * from "./components/settings-list";
 export * from "./components/spacer";

package/dist/types/stdin-buffer.d.ts

@@ -19,8 +19,8 @@
 import { EventEmitter } from "events";
 export type StdinBufferOptions = {
     /**
-     * Maximum time to wait for sequence completion (default: 10ms)
-     * After this time, the buffer is flushed even if incomplete
+     * Maximum time to wait for sequence completion (default: 75ms).
+     * After this time, a genuinely incomplete escape is flushed.
      */
     timeout?: number;
 };

package/dist/types/terminal-capabilities.d.ts

@@ -36,28 +36,23 @@ export declare function isNotificationSuppressed(): boolean;
  */
 export declare function isWindowsTerminalPreviewSixelSupported(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
 /**
- * Whether eager live-frame native scrollback rebuilds are unsafe when the
- * terminal viewport position is unobservable.
+ * Whether live-frame native scrollback rebuilds are unsafe when the terminal
+ * viewport position is unobservable.
  *
- * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). On the
- * terminals below, ED3 can disturb a reader parked in native scrollback during
- * streaming: kitty/ghostty/alacritty/VTE clamp the scroll offset back to the
- * active tail when saved lines are erased. WezTerm, macOS Terminal.app, and
- * iTerm2 expose scrollback-only clears via ED3/terminfo E3; that still
- * invalidates a reader's scrollback position during live streaming.
+ * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). Many
+ * terminals either clamp a scrolled reader back to the active tail or erase host
+ * scrollback when ED3 lands. The important property is not the brand name — it
+ * is that an unknown viewport position cannot be proven safe. Environment
+ * markers are therefore only used to prove *risk* or a strongly-known profile;
+ * unknown POSIX/remote/multiplexer shapes default to risky for passive renders.
  *
- * Windows Terminal erases its host scrollback on ED3 and repositions the
- * viewport against the shortened buffer, so a scrolled-up reader is yanked.
- * Native win32 is excluded here because the renderer guards it with dedicated
- * platform checks (the viewport position is never observable on Windows — see
- * `Terminal.isNativeViewportAtBottom`); a `WT_SESSION` sighting on any other
- * platform means the outer host is Windows Terminal fronting a WSL distro (WT
- * propagates the variable into the Linux environment), where the same ED3
- * yank applies. See #1610.
- *
- * Pure helper for tests and `TERMINAL` trait construction. See #1682 and #1719.
+ * Native win32 is excluded here because the renderer has dedicated ConPTY
+ * deferral paths; a `WT_SESSION` sighting on POSIX means Windows Terminal is the
+ * outer host fronting WSL, where the same ED3 yank applies. See #1610/#1682/#1799.
  */
 export declare function detectTerminalEagerEraseScrollbackRisk(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/** Whether DEC 2026 synchronized-output wrappers should be enabled by default. */
+export declare function shouldEnableSynchronizedOutputByDefault(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, terminalId?: TerminalId): boolean;
 /**
  * Whether the terminal applies Kitty-style DECCARA rectangular SGR changes
  * (`CSI Pt ; Pl ; Pb ; Pr ; <sgr> $ r`) extended to background color, so large

package/dist/types/terminal.d.ts

@@ -58,6 +58,11 @@ export interface Terminal {
      * (xterm.js-backed) implement this with a real answer.
      */
     isNativeViewportAtBottom?(): boolean | undefined;
+    /**
+     * Override the global terminal-profile ED3 risk decision for custom/test
+     * terminals. `undefined` falls back to the resolved `TERMINAL` profile.
+     */
+    hasEagerEraseScrollbackRisk?(): boolean | undefined;
     /**
      * Register a callback for terminal appearance (dark/light) changes.
      * Detection uses OSC 11 background color query with Mode 2031 as a change trigger.

package/dist/types/tui.d.ts

@@ -48,9 +48,21 @@ export interface Component {
  * line index where that suffix begins after each render. TUI treats that suffix
  * — and every root child rendered below it — as not yet safe to commit to native
  * scrollback on ED3-risk terminals whose viewport position is unobservable.
+ *
+ * `getNativeScrollbackCommitSafeEnd` optionally reports a *deeper* boundary
+ * inside that live suffix: the line index up to which the live region is
+ * append-only (its earlier rows never re-layout, only new rows append at the
+ * bottom — a streaming assistant message). Rows in `[liveRegionStart,
+ * commitSafeEnd)` that scroll above the viewport are safe to commit to native
+ * scrollback even though they are technically live, because they will never
+ * change. Without this, a single live block that alone overflows the viewport
+ * loses its scrolled-off head (committed nowhere, repainted nowhere). Volatile
+ * live blocks (tool previews that collapse) omit it, so their mutable rows stay
+ * deferred. Defaults to `liveRegionStart` when absent.
  */
 export interface NativeScrollbackLiveRegion {
     getNativeScrollbackLiveRegionStart(): number | undefined;
+    getNativeScrollbackCommitSafeEnd?(): number | undefined;
 }
 /**
  * Interface for components that can receive focus and display a cursor.
@@ -86,9 +98,8 @@ export interface RenderRequestOptions {
      */
     allowUnknownViewportMutation?: boolean;
 }
-/** Options for deferred native scrollback rebuild checkpoints. */
+/** Options for deferred native scrollback rebuild checkpoints. Reserved for API stability. */
 export interface NativeScrollbackRefreshOptions {
-    /** Allow replay when the terminal cannot report viewport state. Use only for explicit user submit checkpoints. */
     allowUnknownViewport?: boolean;
 }
 /** Type guard to check if a component implements Focusable */
@@ -204,8 +215,8 @@ export declare class TUI extends Container {
     setClearOnShrink(enabled: boolean): void;
     /**
      * Whether DEC 2026 synchronized-output wrappers are currently emitted around
-     * paints. Starts from `PI_NO_SYNC_OUTPUT` and is force-disabled at runtime if
-     * the terminal reports mode 2026 unsupported via DECRQM.
+     * paints. Starts from conservative terminal/env detection and is force-disabled
+     * at runtime if the terminal reports mode 2026 unsupported via DECRQM.
      */
     get synchronizedOutput(): boolean;
     /**
@@ -220,8 +231,8 @@ export declare class TUI extends Container {
      * (the viewport is never observable there and ConPTY hosts erase host
      * scrollback on ED3 — #1635/#1746); only the unknown POSIX case is forced to
      * rebuild. POSIX hosts known to disturb scrolled readers on xterm ED3
-     * (`CSI 3 J`, erase saved lines) also defer the eager opt-in; checkpoint and
-     * direct user-input rebuilds are unaffected.
+     * (`CSI 3 J`, erase saved lines) also defer the eager opt-in; checkpoint
+     * rebuilds are unaffected.
      *
      * Disabling stays active through one already-requested frame: the event batch
      * that ends a foreground stream both removes its UI rows (loader/status
@@ -252,6 +263,6 @@ export declare class TUI extends Container {
      * Callers should only invoke this at checkpoints where the user is expected to be
      * at the terminal bottom, such as after submitting a new prompt.
      */
-    refreshNativeScrollbackIfDirty(options?: NativeScrollbackRefreshOptions): boolean;
+    refreshNativeScrollbackIfDirty(_options?: NativeScrollbackRefreshOptions): boolean;
     requestRender(force?: boolean, options?: RenderRequestOptions): void;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "15.9.3",
+	"version": "15.9.67",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "15.9.3",
-		"@oh-my-pi/pi-utils": "15.9.3",
+		"@oh-my-pi/pi-natives": "15.9.67",
+		"@oh-my-pi/pi-utils": "15.9.67",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.4"
 	},

package/src/components/box.ts

@@ -42,6 +42,12 @@ export class Box implements Component {
 		this.#invalidateCache();
 	}
 
+	setPaddingX(paddingX: number): void {
+		if (this.#paddingX === paddingX) return;
+		this.#paddingX = paddingX;
+		this.#invalidateCache();
+	}
+
 	setBgFn(bgFn?: (text: string) => string): void {
 		this.#bgFn = bgFn;
 		// Don't invalidate here - we'll detect bgFn changes by sampling output

package/src/components/image.ts

@@ -163,6 +163,16 @@ export class ImageBudget {
 		return ids;
 	}
 
+	/** All image ids believed to be loaded in the terminal store; clears tracking. */
+	takeAllTransmittedIds(): readonly number[] {
+		if (this.#transmitted.size === 0) return EMPTY_IDS;
+		const ids = [...this.#transmitted];
+		this.#transmitted.clear();
+		this.#purgeIds = [];
+		this.#pendingTransmits = [];
+		return ids;
+	}
+
 	/** Whether `imageId`'s data still needs to be transmitted to the terminal. */
 	shouldTransmit(imageId: number): boolean {
 		return !this.#transmitted.has(imageId);

package/src/components/scroll-view.ts

@@ -0,0 +1,166 @@
+import type { Component } from "../tui";
+import { Ellipsis, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
+
+const DEFAULT_TRACK = "│";
+const DEFAULT_THUMB = "█";
+
+type ScrollbarMode = "auto" | "always" | "never";
+
+export interface ScrollViewTheme {
+	track?: (text: string) => string;
+	thumb?: (text: string) => string;
+}
+
+export interface ScrollViewOptions {
+	height: number;
+	/** Defaults to "auto". "auto" reserves a scrollbar column only when content overflows. */
+	scrollbar?: ScrollbarMode | boolean;
+	/** Logical row count for pre-windowed line slices. Defaults to lines.length. */
+	totalRows?: number;
+	theme?: ScrollViewTheme;
+	trackChar?: string;
+	thumbChar?: string;
+}
+
+function normalizeScrollbarMode(scrollbar: ScrollViewOptions["scrollbar"]): ScrollbarMode {
+	if (scrollbar === true) return "auto";
+	if (scrollbar === false) return "never";
+	return scrollbar ?? "auto";
+}
+
+function firstCellGlyph(value: string, fallback: string): string {
+	const glyph = Array.from(value)[0] ?? fallback;
+	return visibleWidth(glyph) === 1 ? glyph : fallback;
+}
+
+/**
+ * Fixed-height viewport over pre-rendered lines, with optional right-edge scrollbar.
+ *
+ * ScrollView owns only the row offset. Callers remain responsible for producing
+ * already-wrapped logical lines appropriate for the current render width.
+ */
+export class ScrollView implements Component {
+	#lines: string[];
+	#height: number;
+	#scrollOffset = 0;
+	#totalRows: number | undefined;
+	#scrollbar: ScrollbarMode;
+	#theme: Required<ScrollViewTheme>;
+	#trackChar: string;
+	#thumbChar: string;
+
+	constructor(lines: readonly string[], options: ScrollViewOptions) {
+		this.#lines = [...lines];
+		this.#height = Number.isFinite(options.height) ? Math.max(0, Math.trunc(options.height)) : 0;
+		this.#totalRows = options.totalRows === undefined ? undefined : Math.max(0, Math.trunc(options.totalRows));
+		this.#scrollbar = normalizeScrollbarMode(options.scrollbar);
+		this.#theme = {
+			track: options.theme?.track ?? (text => text),
+			thumb: options.theme?.thumb ?? (text => text),
+		};
+		this.#trackChar = firstCellGlyph(options.trackChar ?? DEFAULT_TRACK, DEFAULT_TRACK);
+		this.#thumbChar = firstCellGlyph(options.thumbChar ?? DEFAULT_THUMB, DEFAULT_THUMB);
+		this.#clampScrollOffset();
+	}
+
+	setLines(lines: readonly string[]): void {
+		this.#lines = [...lines];
+		this.#clampScrollOffset();
+	}
+
+	setTotalRows(totalRows: number | undefined): void {
+		this.#totalRows = totalRows === undefined ? undefined : Math.max(0, Math.trunc(totalRows));
+		this.#clampScrollOffset();
+	}
+
+	setHeight(height: number): void {
+		this.#height = Number.isFinite(height) ? Math.max(0, Math.trunc(height)) : 0;
+		this.#clampScrollOffset();
+	}
+
+	setScrollbar(scrollbar: ScrollViewOptions["scrollbar"]): void {
+		this.#scrollbar = normalizeScrollbarMode(scrollbar);
+	}
+
+	getScrollOffset(): number {
+		return this.#scrollOffset;
+	}
+
+	getMaxScrollOffset(): number {
+		const rowCount = this.#totalRows ?? this.#lines.length;
+		return Math.max(0, rowCount - this.#height);
+	}
+
+	setScrollOffset(offset: number): void {
+		this.#scrollOffset = Number.isFinite(offset) ? Math.trunc(offset) : 0;
+		this.#clampScrollOffset();
+	}
+
+	scroll(delta: number): void {
+		this.setScrollOffset(this.#scrollOffset + (Number.isFinite(delta) ? Math.trunc(delta) : 0));
+	}
+
+	page(delta: number): void {
+		const step = Math.max(1, this.#height - 1);
+		this.scroll(step * (Number.isFinite(delta) ? Math.trunc(delta) : 0));
+	}
+
+	scrollToTop(): void {
+		this.#scrollOffset = 0;
+	}
+
+	scrollToBottom(): void {
+		this.#scrollOffset = this.getMaxScrollOffset();
+	}
+
+	invalidate(): void {
+		// No cached layout to invalidate.
+	}
+
+	render(width: number): string[] {
+		this.#clampScrollOffset();
+		const safeWidth = Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : 0;
+		if (this.#height === 0) return [];
+		const showScrollbar = safeWidth > 0 && this.#shouldRenderScrollbar();
+		const contentWidth = Math.max(0, safeWidth - (showScrollbar ? 1 : 0));
+		const thumb = showScrollbar ? this.#thumbRange() : undefined;
+		const lines: string[] = [];
+		for (let row = 0; row < this.#height; row++) {
+			const sourceIndex = this.#totalRows === undefined ? this.#scrollOffset + row : row;
+			const source = this.#lines[sourceIndex] ?? "";
+			const truncated = truncateToWidth(replaceTabs(source), contentWidth, Ellipsis.Unicode);
+			if (!showScrollbar) {
+				lines.push(truncated);
+				continue;
+			}
+			const content = `${truncated}${" ".repeat(Math.max(0, contentWidth - visibleWidth(truncated)))}`;
+			const barGlyph = thumb && row >= thumb.start && row < thumb.end ? this.#thumbChar : this.#trackChar;
+			const styledBar =
+				thumb && row >= thumb.start && row < thumb.end ? this.#theme.thumb(barGlyph) : this.#theme.track(barGlyph);
+			lines.push(`${content}${styledBar}`);
+		}
+		return lines;
+	}
+
+	#clampScrollOffset(): void {
+		this.#scrollOffset = Math.max(0, Math.min(this.#scrollOffset, this.getMaxScrollOffset()));
+	}
+
+	#shouldRenderScrollbar(): boolean {
+		if (this.#height <= 0) return false;
+		if (this.#scrollbar === "never") return false;
+		if (this.#scrollbar === "always") return true;
+		return (this.#totalRows ?? this.#lines.length) > this.#height;
+	}
+
+	#thumbRange(): { start: number; end: number } {
+		if (this.#height <= 0) return { start: 0, end: 0 };
+		const rowCount = this.#totalRows ?? this.#lines.length;
+		if (rowCount <= this.#height) return { start: 0, end: this.#height };
+		const thumbSize = Math.max(1, Math.min(Math.floor((this.#height * this.#height) / rowCount), this.#height));
+		const travel = this.#height - thumbSize;
+		const maxOffset = this.getMaxScrollOffset();
+		const start = maxOffset === 0 ? 0 : Math.round((this.#scrollOffset / maxOffset) * travel);
+		return { start, end: start + thumbSize };
+	}
+}

package/src/components/select-list.ts

@@ -4,6 +4,7 @@ import { extractPrintableText } from "../keys";
 import type { SymbolTheme } from "../symbols";
 import type { Component } from "../tui";
 import { Ellipsis, padding, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
+import { ScrollView } from "./scroll-view";
 
 const DEFAULT_PRIMARY_COLUMN_WIDTH = 32;
 const PRIMARY_COLUMN_GAP = 2;
@@ -104,17 +105,29 @@ export class SelectList implements Component {
 		const endIndex = Math.min(startIndex + this.maxVisible, this.#filteredItems.length);
 
 		// Render visible items
+		const overflow = this.#filteredItems.length > this.maxVisible;
+		const rowWidth = Math.max(0, width - (overflow ? 1 : 0));
+		const rows: string[] = [];
 		for (let i = startIndex; i < endIndex; i++) {
 			const item = this.#filteredItems[i];
 			if (!item) continue;
 
 			const isSelected = i === this.#selectedIndex;
 			const descriptionText = item.description ? sanitizeSingleLine(item.description) : undefined;
-			lines.push(this.#renderItem(item, isSelected, width, descriptionText, primaryColumnWidth));
+			rows.push(this.#renderItem(item, isSelected, rowWidth, descriptionText, primaryColumnWidth));
 		}
 
-		// Add scroll/search status when needed
-		if (startIndex > 0 || endIndex < this.#filteredItems.length || showSearchStatus) {
+		const sv = new ScrollView(rows, {
+			height: rows.length,
+			scrollbar: "auto",
+			totalRows: this.#filteredItems.length,
+			theme: { track: t => this.theme.scrollInfo(t), thumb: t => this.theme.selectedPrefix(t) },
+		});
+		sv.setScrollOffset(startIndex);
+		lines.push(...sv.render(width));
+
+		// Add search status when relevant (scrollbar now indicates overflow)
+		if (showSearchStatus) {
 			lines.push(this.#renderStatusLine(width));
 		}
 
@@ -247,15 +260,8 @@ export class SelectList implements Component {
 	}
 
 	#renderStatusLine(width: number): string {
-		const selectedCount = this.#filteredItems.length === 0 ? 0 : this.#selectedIndex + 1;
-		const filteredCount = this.#filteredItems.length;
-		const count =
-			this.#filterQuery.trim() && filteredCount !== this.items.length
-				? `${selectedCount}/${filteredCount} of ${this.items.length}`
-				: `${selectedCount}/${filteredCount}`;
 		const query = sanitizeSingleLine(this.#filterQuery);
-		const searchSuffix = this.#shouldRenderSearchStatus() ? (query ? `  Search: ${query}` : "  Type to search") : "";
-		const statusText = `  (${count})${searchSuffix}`;
+		const statusText = query ? `  Search: ${query}` : "  Type to search";
 		return this.theme.scrollInfo(truncateToWidth(statusText, Math.max(1, width - 2), Ellipsis.Omit));
 	}
 

package/src/components/settings-list.ts

@@ -1,6 +1,7 @@
 import { getKeybindings } from "../keybindings";
 import type { Component } from "../tui";
 import { Ellipsis, padding, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
+import { ScrollView } from "./scroll-view";
 
 export interface SettingItem {
 	/** Unique identifier for this setting */
@@ -90,6 +91,22 @@ export class SettingsList implements Component {
 		return this.#renderMainList(width);
 	}
 
+	#renderItemRow(item: SettingItem, index: number, maxLabelWidth: number, rowWidth: number): string {
+		const isSelected = index === this.#selectedIndex;
+		const prefix = isSelected ? this.#theme.cursor : "  ";
+		const prefixWidth = visibleWidth(prefix);
+		const labelPadded = item.label + padding(Math.max(0, maxLabelWidth - visibleWidth(item.label)));
+		const labelText = this.#theme.label(labelPadded, isSelected, item.changed === true);
+		const separator = "  ";
+		const valueMaxWidth = rowWidth - prefixWidth - maxLabelWidth - visibleWidth(separator) - 2;
+		const valueText = this.#theme.value(
+			truncateToWidth(item.currentValue, valueMaxWidth, Ellipsis.Omit),
+			isSelected,
+			item.changed === true,
+		);
+		return truncateToWidth(prefix + labelText + separator + valueText, Math.max(0, rowWidth));
+	}
+
 	#renderMainList(width: number): string[] {
 		const lines: string[] = [];
 
@@ -98,48 +115,29 @@ export class SettingsList implements Component {
 			return lines;
 		}
 
-		// Calculate visible range with scrolling
+		const viewportHeight = Math.min(this.#maxVisible, this.#items.length);
 		const startIndex = Math.max(
 			0,
-			Math.min(this.#selectedIndex - Math.floor(this.#maxVisible / 2), this.#items.length - this.#maxVisible),
+			Math.min(this.#selectedIndex - Math.floor(viewportHeight / 2), this.#items.length - viewportHeight),
 		);
-		const endIndex = Math.min(startIndex + this.#maxVisible, this.#items.length);
-
-		// Calculate max label width for alignment
 		const maxLabelWidth = Math.min(30, Math.max(...this.#items.map(item => visibleWidth(item.label))));
-
-		// Render visible items
-		for (let i = startIndex; i < endIndex; i++) {
-			const item = this.#items[i];
-			if (!item) continue;
-
-			const isSelected = i === this.#selectedIndex;
-			const prefix = isSelected ? this.#theme.cursor : "  ";
-			const prefixWidth = visibleWidth(prefix);
-
-			// Pad label to align values
-			const labelPadded = item.label + padding(Math.max(0, maxLabelWidth - visibleWidth(item.label)));
-			const labelText = this.#theme.label(labelPadded, isSelected, item.changed === true);
-
-			// Calculate space for value
-			const separator = "  ";
-			const usedWidth = prefixWidth + maxLabelWidth + visibleWidth(separator);
-			const valueMaxWidth = width - usedWidth - 2;
-
-			const valueText = this.#theme.value(
-				truncateToWidth(item.currentValue, valueMaxWidth, Ellipsis.Omit),
-				isSelected,
-				item.changed === true,
-			);
-
-			lines.push(truncateToWidth(prefix + labelText + separator + valueText, width));
-		}
-
-		// Add scroll indicator if needed
-		if (startIndex > 0 || endIndex < this.#items.length) {
-			const scrollText = `  (${this.#selectedIndex + 1}/${this.#items.length})`;
-			lines.push(this.#theme.hint(truncateToWidth(scrollText, width - 2, Ellipsis.Omit)));
-		}
+		const itemRowsOverflow = this.#items.length > viewportHeight;
+		const itemRowWidth = Math.max(0, width - (itemRowsOverflow ? 1 : 0));
+		const visibleItems = this.#items.slice(startIndex, startIndex + viewportHeight);
+		const itemRows = visibleItems.map((item, index) =>
+			this.#renderItemRow(item, startIndex + index, maxLabelWidth, itemRowWidth),
+		);
+		const scrollView = new ScrollView(itemRows, {
+			height: viewportHeight,
+			scrollbar: "auto",
+			totalRows: this.#items.length,
+			theme: {
+				track: text => this.#theme.hint(text),
+				thumb: text => this.#theme.label(text, true, false),
+			},
+		});
+		scrollView.setScrollOffset(startIndex);
+		lines.push(...scrollView.render(width));
 
 		// Add description for selected item
 		const selectedItem = this.#items[this.#selectedIndex];

package/src/index.ts

@@ -10,6 +10,7 @@ export * from "./components/image";
 export * from "./components/input";
 export * from "./components/loader";
 export * from "./components/markdown";
+export * from "./components/scroll-view";
 export * from "./components/select-list";
 export * from "./components/settings-list";
 export * from "./components/spacer";