Fix multiline text exceeding console height leaving garbage when scrolling

sindresorhus · sindresorhus · commit 45d30aded22b · 2025-09-12T03:57:24.000+07:00
Fixes #121
diff --git a/example-overflow.js b/example-overflow.js
@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import chalk from 'chalk';
+import ora from './index.js';
+
+console.log(chalk.bold.cyan('\n📏 Terminal Height Overflow Test - Fixed Version 📏'));
+console.log(chalk.gray('This demo shows the fix for issue #121 - multiline content exceeding terminal height.\n'));
+
+// Get terminal dimensions
+const rows = process.stderr.rows || 30;
+const cols = process.stderr.columns || 80;
+
+console.log(chalk.yellow(`Your terminal: ${rows} rows × ${cols} columns`));
+console.log(chalk.green(`Creating spinner with ${rows + 10} lines (exceeds by 10 lines)\n`));
+
+// Create content that exceeds terminal height
+const lines = [];
+for (let i = 1; i <= rows + 10; i++) {
+	const emoji = ['🔴', '🟠', '🟡', '🟢', '🔵', '🟣'][i % 6];
+	lines.push(`${emoji} Line ${String(i).padStart(3, '0')}: Processing item #${i}`);
+}
+
+const spinner = ora({
+	text: lines.join('\n'),
+	spinner: 'dots',
+	color: 'cyan',
+}).start();
+
+// Update a few times
+let updates = 0;
+const interval = setInterval(() => {
+	updates++;
+	if (updates <= 3) {
+		spinner.color = ['yellow', 'green', 'magenta'][updates - 1];
+		spinner.text = `Update ${updates}/3\n${lines.join('\n')}`;
+	} else {
+		clearInterval(interval);
+		spinner.succeed('Done! Content that exceeded terminal height has been properly cleared.');
+
+		console.log('\n' + chalk.bold.green('✅ The Fix:'));
+		console.log(chalk.white('When content exceeds terminal height, ora now:'));
+		console.log(chalk.gray('  1. Detects the overflow (lines > terminal rows)'));
+		console.log(chalk.gray('  2. Truncates content to fit terminal with message'));
+		console.log(chalk.gray('  3. Prevents garbage lines from being written'));
+
+		console.log('\n' + chalk.bold.yellow('🔍 Try scrolling up now!'));
+		console.log(chalk.gray('You should NOT see leftover spinner frames above.'));
+		console.log(chalk.gray('Content was truncated to prevent overflow.\n'));
+	}
+}, 1000);
diff --git a/index.d.ts b/index.d.ts
@@ -37,7 +37,7 @@ export type Options = {
 	readonly suffixText?: string | SuffixTextGenerator;
 
 	/**
-	The name of one of the provided spinners. See [`example.js`](https://github.com/BendingBender/ora/blob/main/example.js) in this repo if you want to test out different spinners. On Windows (expect for Windows Terminal), it will always use the line spinner as the Windows command-line doesn't have proper Unicode support.
+	The name of one of the provided spinners. See `example.js` in this repo if you want to test out different spinners. On Windows (except for Windows Terminal), it will always use the line spinner as the Windows command-line doesn't have proper Unicode support.
 
 	@default 'dots'
 
diff --git a/index.js b/index.js
@@ -276,8 +276,21 @@ class Ora {
 		}
 
 		this.clear();
-		this.#stream.write(this.frame());
-		this.#linesToClear = this.#lineCount;
+
+		let frameContent = this.frame();
+		let actualLineCount = this.#lineCount;
+
+		// If content would exceed viewport height, truncate it to prevent garbage
+		const consoleHeight = this.#stream.rows;
+		if (consoleHeight && consoleHeight > 1 && this.#lineCount > consoleHeight) {
+			const lines = frameContent.split('\n');
+			const maxLines = consoleHeight - 1; // Reserve one line for truncation message
+			frameContent = [...lines.slice(0, maxLines), '... (content truncated to fit terminal)'].join('\n');
+			actualLineCount = maxLines + 1; // Truncated lines + message line
+		}
+
+		this.#stream.write(frameContent);
+		this.#linesToClear = actualLineCount;
 
 		return this;
 	}
diff --git a/test.js b/test.js
@@ -983,3 +983,140 @@ Example output:
   ... 1 more item
 ]
 */
+
+test('multiline text exceeding console height', t => {
+	// Create a mock stream with limited height
+	const stream = getPassThroughStream();
+	stream.rows = 5; // Simulate a console with 5 rows
+	stream.columns = 80;
+	stream.isTTY = true;
+
+	let writtenContent = '';
+
+	// Override write to capture content
+	const originalWrite = stream.write;
+	stream.write = function (content) {
+		writtenContent = content;
+		return originalWrite.call(this, content);
+	};
+
+	const spinner = ora({
+		stream,
+		text: Array.from({length: 10}, (_, i) => `Line ${i + 1}`).join('\n'), // 10 lines (exceeds 5 row height)
+		color: false,
+		isEnabled: true,
+	});
+
+	spinner.start();
+	spinner.render(); // Force a render
+
+	// When content exceeds viewport, should truncate with message
+	t.true(writtenContent.includes('Line 1'), 'Should include some original content');
+	t.true(writtenContent.includes('(content truncated to fit terminal)'), 'Should show truncation message');
+
+	// Should not include all 10 lines
+	const lineCount = (writtenContent.match(/Line \d+/g) || []).length;
+	t.true(lineCount < 10, 'Should truncate some lines');
+	t.true(lineCount <= 5, 'Should not exceed terminal height');
+
+	spinner.stop();
+});
+
+test('multiline text within console height', t => {
+	// Create a mock stream with sufficient height
+	const stream = getPassThroughStream();
+	stream.rows = 10; // Simulate a console with 10 rows
+	stream.columns = 80;
+	stream.isTTY = true;
+
+	let writtenContent = '';
+
+	// Override write to capture content
+	const originalWrite = stream.write;
+	stream.write = function (content) {
+		writtenContent = content;
+		return originalWrite.call(this, content);
+	};
+
+	const spinner = ora({
+		stream,
+		text: Array.from({length: 5}, (_, i) => `Line ${i + 1}`).join('\n'), // 5 lines (within 10 row height)
+		color: false,
+		isEnabled: true,
+	});
+
+	spinner.start();
+	spinner.render();
+
+	// When content is within viewport, should not truncate
+	t.true(writtenContent.includes('Line 1'), 'Should include first line');
+	t.true(writtenContent.includes('Line 5'), 'Should include last line');
+	t.false(writtenContent.includes('(content truncated to fit terminal)'), 'Should not show truncation message');
+
+	spinner.stop();
+});
+
+test('multiline text with undefined terminal rows', t => {
+	// Test fallback behavior when stream.rows is undefined
+	const stream = getPassThroughStream();
+	delete stream.rows; // Ensure rows is undefined
+	stream.columns = 80;
+	stream.isTTY = true;
+
+	let writtenContent = '';
+
+	// Override write to capture content
+	const originalWrite = stream.write;
+	stream.write = function (content) {
+		writtenContent = content;
+		return originalWrite.call(this, content);
+	};
+
+	const spinner = ora({
+		stream,
+		text: Array.from({length: 10}, (_, i) => `Line ${i + 1}`).join('\n'),
+		color: false,
+		isEnabled: true,
+	});
+
+	spinner.start();
+	spinner.render();
+
+	// When terminal height is unknown, should not truncate (no truncation applied)
+	t.true(writtenContent.includes('Line 1'), 'Should include first line');
+	t.true(writtenContent.includes('Line 10'), 'Should include last line');
+	t.false(writtenContent.includes('(content truncated to fit terminal)'), 'Should not truncate when height is unknown');
+
+	spinner.stop();
+});
+
+test('multiline text with very small console height', t => {
+	// Test edge case: console height = 1 (should not truncate since no room for message)
+	const stream = getPassThroughStream();
+	stream.rows = 1;
+	stream.columns = 80;
+	stream.isTTY = true;
+
+	let writtenContent = '';
+	const originalWrite = stream.write;
+	stream.write = function (content) {
+		writtenContent = content;
+		return originalWrite.call(this, content);
+	};
+
+	const spinner = ora({
+		stream,
+		text: 'Line 1\nLine 2\nLine 3', // 3 lines (exceeds 1 row height)
+		color: false,
+		isEnabled: true,
+	});
+
+	spinner.start();
+	spinner.render();
+
+	// When console is too small (1 row), should not truncate because no room for message
+	t.true(writtenContent.includes('Line 1'), 'Should include content');
+	t.false(writtenContent.includes('(content truncated to fit terminal)'), 'Should not truncate when console too small for message');
+
+	spinner.stop();
+});
