feat: add streamPreview API for live streaming output preview

## Problem
`streamPreview` only handled `\n`-terminated lines. Programs like `curl`
that use `\r` (carriage return) to update progress in-place were not
displayed — the data stayed buffered and invisible.

## Changes
- Handle `\r` in both completed lines and partial lines — keep content
after last `\r`
- Flush partial lines to display so `\r`-only updates render immediately
- Include partial line content in flush output
- Updated example to use `curl` and `ping` (real commands)
- Added test: `handles carriage return for in-place updates`
- Also includes sort-order fix (stacked on #33)

Stacks on: pvtnbr/tasuku#33

Author: privatenumber

.github/media/stream-preview.gif

@@ -0,0 +1,14 @@
+Output .github/media/stream-preview.gif
+Set Theme "Dracula"
+Set FontFamily "Menlo"
+Set FontSize 16
+Set Width 950
+Set Height 200
+Set Padding 20
+
+Hide
+Type "node examples/stream-preview.js"
+Show
+Sleep 500ms
+Enter
+Sleep 8s

.github/media/stream-preview.tape

@@ -257,6 +257,7 @@ type TaskFunction = (taskInnerApi: {
     setOutput(output: string | { message: string }): void
     setWarning(warning: Error | string): void
     setError(error: Error | string): void
+    streamPreview: Writable
     startTime(): void
     stopTime(): number
 }) => Promise<unknown>
@@ -281,6 +282,28 @@ Call with a string to set the output of the task.
 
 <img src=".github/media/task-output.png">
 
+#### streamPreview
+A `Writable` stream for displaying live output below the task. Pipe a child process or any readable stream into it to show a scrolling preview of the output.
+
+Handles both `\n` (newline) and `\r` (carriage return) — programs like `curl` that use `\r` for in-place progress bars work out of the box.
+
+```ts
+import { spawn } from 'node:child_process'
+import { pipeline } from 'node:stream/promises'
+
+await task('Download', async ({ streamPreview }) => {
+    const child = spawn('curl', ['-o', '/dev/null', 'https://example.com/file'])
+    await pipeline(child.stderr, streamPreview)
+})
+```
+
+<img src=".github/media/stream-preview.gif">
+
+By default, shows the last 5 lines. Use the `previewLines` option to change this. When there are more lines than the limit, a `(+ N lines)` indicator is shown.
+
+> [!NOTE]
+> `setOutput()` and `streamPreview` render independently. If both are used, static output appears above the stream preview.
+
 #### setWarning()
 Call with a string or Error instance to put the task in a warning state.
 
@@ -311,10 +334,17 @@ await task('Multi-phase', async ({ startTime, stopTime, setStatus }) => {
 ```
 
 #### options
-Type: `{ showTime?: boolean }`
+Type: `{ showTime?: boolean, previewLines?: number }`
 
 Optional task options.
 
+##### previewLines
+Type: `number`
+
+Default: `5`
+
+Maximum number of lines to display in the `streamPreview` output (minimum 1). When the stream produces more lines, older lines scroll off and a `(+ N lines)` indicator shows the total.
+
 ##### showTime
 When `true`, automatically starts the elapsed time counter when the task begins. Equivalent to calling `startTime()` at the start of the task function.
 

README.md

@@ -0,0 +1,15 @@
+import { spawn } from 'node:child_process';
+import { pipeline } from 'node:stream/promises';
+import task from '#tasuku';
+
+// Rate-limited to 2MB/s so progress is visible (~4 seconds for ~9MB file)
+await task('Download TypeScript', async ({ streamPreview }) => {
+	const child = spawn('curl', [
+		'--limit-rate',
+		'2m',
+		'-o',
+		'/dev/null',
+		'https://cdn.jsdelivr.net/npm/typescript@latest/lib/typescript.js',
+	]);
+	await pipeline(child.stderr, streamPreview);
+});

examples/stream-preview.js

@@ -1,4 +1,6 @@
+import { Writable } from 'node:stream';
 import pMap from 'p-map';
+import stripAnsi from 'strip-ansi';
 import { createRenderer, type Renderer } from './renderer.js';
 import { reactive, setRenderCallback } from './reactive.js';
 import {
@@ -16,7 +18,95 @@ import {
 	runSymbol,
 } from './types.js';
 
-const createTaskInnerApi = (taskState: TaskObject) => {
+const defaultPreviewLines = 5;
+
+const createStreamPreview = (
+	taskState: TaskObject,
+	maxLines: number,
+): Writable => {
+	const lines: string[] = [];
+	let totalLines = 0;
+	let partialLine = '';
+
+	// Resolve \r within a string: keep content after the last \r.
+	// For trailing \r (nothing after), keep the last non-empty segment.
+	const resolveCarriageReturn = (text: string) => {
+		const segments = text.split('\r');
+		return segments.reverse().find(Boolean) ?? '';
+	};
+
+	const flush = () => {
+		const displayPartial = partialLine.includes('\r')
+			? resolveCarriageReturn(partialLine)
+			: partialLine;
+		const output = displayPartial
+			? [...lines, displayPartial].join('\n')
+			: lines.join('\n');
+		taskState.streamOutput = output;
+		taskState.streamTruncatedLines = Math.max(0, totalLines - maxLines);
+	};
+
+	return new Writable({
+		write(chunk: Buffer, _encoding, callback) {
+			const text = stripAnsi(partialLine + chunk.toString());
+			const parts = text.split(/\r?\n/);
+
+			// Last element is either empty (if chunk ended with \n) or a partial line
+			partialLine = parts.pop()!;
+
+			for (const rawLine of parts) {
+				// Handle \r (carriage return) — keep content after last \r
+				const line = rawLine.includes('\r')
+					? resolveCarriageReturn(rawLine)
+					: rawLine;
+				lines.push(line);
+				totalLines += 1;
+				if (lines.length > maxLines) {
+					lines.shift();
+				}
+			}
+
+			// Trim accumulated \r segments to prevent unbounded growth
+			if (partialLine.includes('\r')) {
+				const resolved = resolveCarriageReturn(partialLine);
+				// Keep trailing \r as boundary marker for next chunk
+				partialLine = partialLine.endsWith('\r')
+					? `${resolved}\r`
+					: resolved;
+			}
+
+			if (parts.length > 0 || partialLine) {
+				flush();
+			}
+
+			callback();
+		},
+
+		final(callback) {
+			// Flush any remaining partial line
+			if (partialLine) {
+				const line = partialLine.includes('\r')
+					? resolveCarriageReturn(partialLine)
+					: partialLine;
+				lines.push(line);
+				totalLines += 1;
+				if (lines.length > maxLines) {
+					lines.shift();
+				}
+				partialLine = '';
+				flush();
+			}
+			callback();
+		},
+	});
+};
+
+const createTaskInnerApi = (
+	taskState: TaskObject,
+	options?: TaskOptions,
+) => {
+	let stream: Writable | undefined;
+
 	const api: TaskInnerAPI = {
 		task: createTaskFunction(taskState.children),
 		setTitle(title) {
@@ -36,6 +126,15 @@ const createTaskInnerApi = (taskState: TaskObject) => {
 					)
 			);
 		},
+		get streamPreview() {
+			if (!stream) {
+				stream = createStreamPreview(
+					taskState,
+					Math.max(1, Math.trunc(options?.previewLines ?? defaultPreviewLines)),
+				);
+			}
+			return stream;
+		},
 		setWarning(warning) {
 			taskState.state = 'warning';
 
@@ -63,7 +162,10 @@ const createTaskInnerApi = (taskState: TaskObject) => {
 			return taskState.elapsedMs;
 		},
 	};
-	return api;
+	return {
+		api,
+		destroyStream: () => stream?.destroy(),
+	};
 };
 
 let renderer: Renderer | undefined;
@@ -90,7 +192,7 @@ const registerTask = <T>(
 	return {
 		task,
 		[runSymbol]: async () => {
-			const api = createTaskInnerApi(task);
+			const { api, destroyStream } = createTaskInnerApi(task, options);
 
 			task.state = 'loading';
 
@@ -106,13 +208,15 @@ const registerTask = <T>(
 				// Auto-stop timer on error
 				api.stopTime();
 				api.setError(error as Error);
+				destroyStream();
 				// Flush render before throwing to prevent overwriting subsequent output
 				renderer?.flushRender();
 				throw error;
 			}
 
 			// Auto-stop timer on completion
 			api.stopTime();
+			destroyStream();
 
 			if (task.state === 'loading') {
 				task.state = 'success';

src/index.ts

@@ -170,18 +170,35 @@ export const createRenderer = (
 
 		line += '\n';
 
-		if (task.output) {
-			const outputIndent = `${indent}  `;
-			const styleText = (text: string) => (useColors
-				? gray(text)
-				: text);
+		const outputIndent = `${indent}  `;
+		const styleText = (text: string) => (useColors
+			? gray(text)
+			: text);
 
+		// Static output: → prefix
+		if (task.output) {
 			line += `${task.output
 				.split('\n')
 				.map((outputLine, index) => `${outputIndent}${styleText(index === 0 ? `→ ${outputLine}` : outputLine)}`)
 				.join('\n')}\n`;
 		}
 
+		// Stream preview: ⎿ prefix with aligned continuation
+		if (task.streamOutput) {
+			const continuationIndent = `${outputIndent}   `;
+			line += `${task.streamOutput
+				.split('\n')
+				.map((outputLine, index) => (index === 0
+					? `${outputIndent}⎿  ${styleText(outputLine)}`
+					: `${continuationIndent}${styleText(outputLine)}`))
+				.join('\n')}\n`;
+
+			if (task.streamTruncatedLines) {
+				const truncatedText = `(+ ${task.streamTruncatedLines} lines)`;
+				line += `${continuationIndent}${styleText(truncatedText)}\n`;
+			}
+		}
+
 		// Render children recursively
 		if (hasChildren) {
 			line += renderTaskList(task.children, depth + 1);

src/renderer.ts

@@ -1,3 +1,4 @@
+import type { Writable } from 'node:stream';
 import type { Options as PMapOptions } from 'p-map';
 
 type State = 'pending' | 'loading' | 'error' | 'warning' | 'success';
@@ -46,12 +47,15 @@ export type TaskObject = {
 	children: TaskObject[];
 	status?: string;
 	output?: string;
+	streamOutput?: string;
+	streamTruncatedLines?: number;
 	startedAt?: number;
 	elapsedMs?: number;
 };
 
 export type TaskOptions = {
 	showTime?: boolean;
+	previewLines?: number;
 };
 
 export type TaskList = TaskObject[] & {
@@ -65,6 +69,7 @@ export type TaskInnerAPI = {
 	setWarning(warning?: Error | string): void;
 	setError(error?: Error | string): void;
 	setOutput(output: string | { message: string }): void;
+	streamPreview: Writable;
 	startTime(): void;
 	stopTime(): number;
 };

src/types.ts

@@ -8,6 +8,7 @@ await describe('tasuku', ({ runTestSuite }) => {
 	// Task behavior
 	runTestSuite(import('./specs/task-states.spec.js'));
 	runTestSuite(import('./specs/elapsed-time.spec.js'));
+	runTestSuite(import('./specs/stream-preview.spec.js'));
 
 	// Rendering
 	runTestSuite(import('./specs/rendering.spec.js'));

tests/index.ts

@@ -275,7 +275,7 @@ export default testSuite(({ describe }) => {
 					);
 
 					console.log('TASKS_DONE');
-					await setTimeout(200);
+					await setTimeout(2000);
 					`,
 				}, { tempDir });
 
@@ -322,7 +322,7 @@ export default testSuite(({ describe }) => {
 					);
 
 					console.log('ALL_DONE');
-					await setTimeout(200);
+					await setTimeout(2000);
 					`,
 				}, { tempDir });
 
@@ -379,7 +379,7 @@ export default testSuite(({ describe }) => {
 					);
 
 					console.log('TASKS_DONE');
-					await setTimeout(200);
+					await setTimeout(2000);
 					`,
 				}, { tempDir });