@step-forge/step-forge 0.0.24 → 0.0.25-alpha.2

package/dist/cli.cjs

@@ -12,6 +12,7 @@ let node_util = require("node:util");
 let node_child_process = require("node:child_process");
 let node_readline = require("node:readline");
 node_readline = require_gherkinParser.__toESM(node_readline, 1);
+let node_stream = require("node:stream");
 //#region src/runtime/config.ts
 const DEFAULT_FEATURES = "**/*.feature";
 const DEFAULT_STEPS = "**/*.steps.ts";
@@ -169,7 +170,7 @@ function selectScenarios(scenarios, options) {
 }
 //#endregion
 //#region src/runtime/reporters.ts
-const useColor$2 = !process.env.NO_COLOR && (process.stdout.isTTY ?? false) === true;
+const useColor$2 = !process.env.NO_COLOR && (!!process.env.FORCE_COLOR || (process.stdout.isTTY ?? false) === true);
 const wrap$1 = (open, close) => (s) => useColor$2 ? `\x1b[${open}m${s}\x1b[${close}m` : s;
 const c = {
 	green: wrap$1(32, 39),
@@ -183,16 +184,28 @@ const STATUS_MARK = {
 	failed: c.red("✗"),
 	skipped: c.yellow("-")
 };
+/** Display status of a whole scenario (skipped = every step skipped). */
+function scenarioStatus(result) {
+	if (result.status === "failed") return "failed";
+	if (result.steps.every((s) => s.status === "skipped")) return "skipped";
+	return "passed";
+}
+/** The scenario's display name, prefixed with its outline name for outline rows. */
+function scenarioLabel(result) {
+	return result.scenario.outline ? `${result.scenario.outline.name} › ${result.scenario.name}` : result.scenario.name;
+}
 /** ✓ / ✗ / - for a whole scenario (skipped = every step skipped). */
 function scenarioMark(result) {
-	if (result.status === "failed") return c.red("✗");
-	if (result.steps.every((s) => s.status === "skipped")) return c.yellow("-");
+	const status = scenarioStatus(result);
+	if (status === "failed") return c.red("✗");
+	if (status === "skipped") return c.yellow("-");
 	return c.green("✓");
 }
 /** Dot per scenario for the live heartbeat: `.` pass / `F` fail / `-` skip. */
 function scenarioDot(result) {
-	if (result.status === "failed") return c.red("F");
-	if (result.steps.every((s) => s.status === "skipped")) return c.yellow("-");
+	const status = scenarioStatus(result);
+	if (status === "failed") return c.red("F");
+	if (status === "skipped") return c.yellow("-");
 	return c.green(".");
 }
 /** Indent every non-empty line of a block by `pad` spaces. */
@@ -230,8 +243,7 @@ function failureDetail(stepResult, result, cwd) {
 * appended at the end.
 */
 function renderScenario(result, cwd, opts) {
-	const label = result.scenario.outline ? `${result.scenario.outline.name} › ${result.scenario.name}` : result.scenario.name;
-	const lines = [`${scenarioMark(result)} ${c.bold(label)}`];
+	const lines = [`${scenarioMark(result)} ${c.bold(scenarioLabel(result))}`];
 	const loc = result.scenario.line ? `${(0, node_path.relative)(cwd, result.scenario.file)}:${result.scenario.line}` : (0, node_path.relative)(cwd, result.scenario.file);
 	lines.push(indent(c.dim(loc), 4));
 	lines.push("");
@@ -346,6 +358,40 @@ function progressReporter(opts = {}) {
 function makeReporter(name, opts = {}) {
 	return name === "progress" ? progressReporter(opts) : prettyReporter(opts);
 }
+/**
+* Internal reporter for interactive mode. Emits one {@link RunEvent} per line
+* (NDJSON) and nothing human-facing, so a parent process can parse the stream
+* and own the rendering. Failure detail reuses {@link renderScenario} verbatim,
+* so the TUI's failures pane matches the non-interactive output.
+*/
+function eventsReporter(opts = {}) {
+	const cwd = opts.cwd ?? process.cwd();
+	const emit = (evt) => write$1(`${JSON.stringify(evt)}\n`);
+	return {
+		onScenarioEnd(result) {
+			const steps = {
+				passed: 0,
+				failed: 0,
+				skipped: 0
+			};
+			for (const s of result.steps) steps[s.status]++;
+			const status = scenarioStatus(result);
+			emit({
+				t: "scenario",
+				status,
+				name: scenarioLabel(result),
+				steps,
+				detail: status === "failed" ? renderScenario(result, cwd, { stepSource: false }) : void 0
+			});
+		},
+		onComplete(_results, durationMs) {
+			emit({
+				t: "complete",
+				durationMs
+			});
+		}
+	};
+}
 //#endregion
 //#region src/runtime/runner.ts
 /**
@@ -431,10 +477,30 @@ async function run(config, reporter = makeReporter(config.reporter, {
 }
 //#endregion
 //#region src/runtime/prompt.ts
+function freshResults() {
+	return {
+		running: false,
+		scenarios: {
+			passed: 0,
+			failed: 0,
+			skipped: 0
+		},
+		steps: {
+			passed: 0,
+			failed: 0,
+			skipped: 0
+		},
+		dots: [],
+		failures: [],
+		notes: []
+	};
+}
 const useColor$1 = !process.env.NO_COLOR && (process.stdout.isTTY ?? false) === true;
 const wrap = (open, close) => (s) => useColor$1 ? `\x1b[${open}m${s}\x1b[${close}m` : s;
 const color = {
 	green: wrap(32, 39),
+	red: wrap(31, 39),
+	yellow: wrap(33, 39),
 	cyan: wrap(36, 39),
 	dim: wrap(2, 22),
 	bold: wrap(1, 22),
@@ -458,18 +524,23 @@ var Prompt = class {
 	cursor;
 	selected = 0;
 	window = 0;
-	/** Optional dim status line shown just above the input (set by the caller). */
+	/** Optional dim status line shown just below the input (set by the caller). */
 	status = "";
-	/** Lines the pinned block currently occupies, so a redraw can erase them. */
-	rendered = 0;
+	results = freshResults();
+	failScroll = 0;
 	started = false;
-	/** While true the block is hidden so a run's output can own the screen. */
-	suspended = false;
+	/** Filtered key stream: raw stdin minus the mouse sequences we handle. */
+	input;
 	keyListener;
+	dataListener;
+	resizeListener;
+	signalCleanup;
+	/** Carry an incomplete mouse sequence split across stdin chunks. */
+	mousePending = "";
 	constructor(options) {
 		this.handlers = options.handlers;
 		this.prefix = options.prefix ?? "› ";
-		this.maxVisible = options.maxVisible ?? 10;
+		this.maxVisible = options.maxVisible ?? 8;
 		this.query = options.initialQuery ?? "";
 		this.cursor = this.query.length;
 	}
@@ -482,46 +553,106 @@ var Prompt = class {
 	get value() {
 		return this.query;
 	}
-	/** Enter raw mode, attach the keypress listener, and draw the block. */
+	/** Start a fresh run: reset counts/dots/failures and record its header. */
+	resetResults(header) {
+		this.results = freshResults();
+		this.results.header = header;
+		this.results.running = true;
+		this.failScroll = 0;
+		this.render();
+	}
+	/** Append a note line above the dots (diagnostics, errors, empty notices). */
+	note(line) {
+		this.results.notes.push(line);
+		this.render();
+	}
+	/** Push a standalone block into the scrollable failures pane (e.g. a crash). */
+	failureBlock(text) {
+		this.results.failures.push(text);
+		this.render();
+	}
+	/** Record one finished scenario: tally it, add its dot, keep any failure block. */
+	scenario(status, steps, detail) {
+		this.results.scenarios[status]++;
+		this.results.steps.passed += steps.passed;
+		this.results.steps.failed += steps.failed;
+		this.results.steps.skipped += steps.skipped;
+		this.results.dots.push(dotFor(status));
+		if (detail) this.results.failures.push(detail);
+		this.render();
+	}
+	/** Mark the run finished and record its wall-clock duration. */
+	complete(durationMs) {
+		this.results.running = false;
+		this.results.durationMs = durationMs;
+		this.render();
+	}
+	/** Enter the alternate screen + raw mode, attach listeners, and paint. */
 	start() {
 		if (this.started) return;
 		this.started = true;
-		node_readline.emitKeypressEvents(process.stdin);
 		if (process.stdin.isTTY) process.stdin.setRawMode(true);
+		write("\x1B[?1049h\x1B[?1000h\x1B[?1006h");
+		this.input = new node_stream.PassThrough();
+		node_readline.emitKeypressEvents(this.input);
 		this.keyListener = (str, key) => this.onKey(str, key ?? {});
-		process.stdin.on("keypress", this.keyListener);
+		this.input.on("keypress", this.keyListener);
+		this.dataListener = (chunk) => this.onStdinData(chunk);
+		process.stdin.on("data", this.dataListener);
 		process.stdin.resume();
+		this.resizeListener = () => this.render();
+		process.stdout.on("resize", this.resizeListener);
+		this.installSafetyNet();
 		this.render();
 	}
-	/** Erase the block, restore cooked mode, and detach the listener. */
+	/** Restore the terminal: leave the alt buffer, cooked mode, cursor visible. */
 	stop() {
 		if (!this.started) return;
 		this.started = false;
-		this.erase();
-		write("\x1B[?25h");
-		if (this.keyListener) process.stdin.off("keypress", this.keyListener);
-		if (process.stdin.isTTY) process.stdin.setRawMode(false);
+		if (this.dataListener) process.stdin.off("data", this.dataListener);
+		if (this.keyListener) this.input?.off("keypress", this.keyListener);
+		if (this.resizeListener) process.stdout.off("resize", this.resizeListener);
+		this.signalCleanup?.();
+		this.restoreTerminal();
 		process.stdin.pause();
+		this.input = void 0;
+		this.mousePending = "";
+	}
+	/** Force a repaint (after mutating `status`, say). No-op until started. */
+	redraw() {
+		if (this.started) this.render();
 	}
 	/**
-	* Erase the pinned block and hide it for the duration of an (async) run, so
-	* everything written to stdout in the meantime scrolls where the prompt was.
-	* Keypresses still update state but don't repaint until {@link endOutput}.
+	* Leave raw mode and the alternate screen buffer and show the cursor.
+	* Idempotent and synchronous so it is safe from an `exit`/signal handler —
+	* a crash or `kill` must never strand the terminal in raw/alt-buffer mode.
 	*/
-	beginOutput() {
-		if (!this.started) return;
-		this.erase();
-		this.suspended = true;
-	}
-	/** Redraw the pinned block below whatever output {@link beginOutput} let through. */
-	endOutput() {
-		if (!this.started) return;
-		this.suspended = false;
-		this.render();
+	restoreTerminal() {
+		if (process.stdin.isTTY) process.stdin.setRawMode(false);
+		write("\x1B[?1006l\x1B[?1000l");
+		write("\x1B[?25h");
+		write("\x1B[?1049l");
 	}
-	/** Force a redraw (after mutating `status`, say). No-op while suspended. */
-	redraw() {
-		if (this.started && !this.suspended) this.render();
+	/**
+	* Register process-level handlers so the terminal is always restored, even on
+	* `kill` (SIGTERM), a crash (`exit` fires with a non-zero code), or a stray
+	* SIGINT. In raw mode Ctrl-C arrives as a keypress (handled by `onKey`), not a
+	* signal, so these are a safety net rather than the normal quit path.
+	*/
+	installSafetyNet() {
+		const onExit = () => this.restoreTerminal();
+		const onSignal = () => {
+			this.restoreTerminal();
+			process.exit(130);
+		};
+		process.on("exit", onExit);
+		process.on("SIGINT", onSignal);
+		process.on("SIGTERM", onSignal);
+		this.signalCleanup = () => {
+			process.off("exit", onExit);
+			process.off("SIGINT", onSignal);
+			process.off("SIGTERM", onSignal);
+		};
 	}
 	onKey(str, key) {
 		if (key.ctrl && (key.name === "c" || key.name === "d")) {
@@ -544,6 +675,12 @@ var Prompt = class {
 			case "down":
 				this.move(1);
 				return;
+			case "pageup":
+				this.scrollFailures(-1);
+				return;
+			case "pagedown":
+				this.scrollFailures(1);
+				return;
 			case "left":
 				this.cursor = Math.max(0, this.cursor - 1);
 				this.render();
@@ -596,6 +733,57 @@ var Prompt = class {
 		this.reWindow();
 		this.render();
 	}
+	/** Scroll the failures pane by whole pages (PgUp/PgDn). */
+	scrollFailures(pages) {
+		this.adjustFailScroll(pages * this.failPage);
+	}
+	failPage = 1;
+	/** Move the failures viewport by `deltaLines` (clamped in {@link render}). */
+	adjustFailScroll(deltaLines) {
+		this.failScroll = Math.max(0, this.failScroll + deltaLines);
+		this.render();
+	}
+	/**
+	* Split a raw stdin chunk: decode SGR/legacy mouse sequences here (only the
+	* wheel is acted on — it scrolls the failures pane by a few lines) and forward
+	* everything else to readline. An incomplete trailing mouse sequence is held
+	* in {@link mousePending} for the next chunk. `latin1` keeps every byte 1:1 so
+	* the forwarded bytes reassemble exactly (including multibyte input).
+	*/
+	onStdinData(chunk) {
+		const buf = this.mousePending + chunk.toString("latin1");
+		let out = "";
+		let i = 0;
+		while (i < buf.length) {
+			if (buf.startsWith("\x1B[<", i)) {
+				const rel = /[Mm]/.exec(buf.slice(i + 3));
+				if (!rel) break;
+				const end = i + 3 + rel.index + 1;
+				this.handleMouse(buf.slice(i, end));
+				i = end;
+				continue;
+			}
+			if (buf.startsWith("\x1B[M", i)) {
+				if (i + 6 > buf.length) break;
+				this.handleMouse(buf.slice(i, i + 6));
+				i += 6;
+				continue;
+			}
+			out += buf[i];
+			i++;
+		}
+		this.mousePending = buf.slice(i);
+		if (out) this.input?.write(Buffer.from(out, "latin1"));
+	}
+	/** Act on a decoded mouse sequence — wheel up/down scrolls failures; else ignore. */
+	handleMouse(seq) {
+		let button = null;
+		const sgr = /^\x1b\[<(\d+);\d+;\d+[Mm]$/.exec(seq);
+		if (sgr) button = parseInt(sgr[1], 10);
+		else if (seq.length === 6) button = seq.charCodeAt(3) - 32;
+		if (button === null || (button & 64) === 0) return;
+		this.adjustFailScroll((button & 1) === 0 ? -3 : 3);
+	}
 	refilter() {
 		const q = this.query.trim().toLowerCase();
 		this.matches = this.all.map((s, index) => ({
@@ -610,9 +798,18 @@ var Prompt = class {
 		if (this.selected < this.window) this.window = this.selected;
 		else if (this.selected >= this.window + this.maxVisible) this.window = this.selected - this.maxVisible + 1;
 	}
-	/** Build the block's lines, top (suggestions) to bottom (input). */
-	buildLines() {
+	rows() {
+		return process.stdout.rows && process.stdout.rows > 0 ? process.stdout.rows : 24;
+	}
+	cols() {
+		return process.stdout.columns && process.stdout.columns > 0 ? process.stdout.columns : 80;
+	}
+	/** Prompt + selection lines. The input line is always row 0. */
+	topLines() {
 		const lines = [];
+		lines.push(`${color.bold(this.prefix)}${this.query}`);
+		if (this.status) lines.push(color.dim(this.status));
+		lines.push("");
 		const total = this.matches.length;
 		if (this.query.trim() && total === 0) lines.push(color.dim("  no matching tag, feature, or scenario"));
 		const end = Math.min(this.window + this.maxVisible, total);
@@ -623,37 +820,123 @@ var Prompt = class {
 			lines.push(active ? color.inverse(`❯ ${row}`) : `  ${row}`);
 		}
 		if (total > end) lines.push(color.dim(`  …and ${total - end} more`));
-		if (this.status) lines.push(color.dim(this.status));
-		lines.push(`${color.bold(this.prefix)}${this.query}`);
+		return lines;
+	}
+	/** Stats (header + summary) and the wrapped dots, above the failures pane. */
+	resultLines(cols) {
+		const lines = ["", divider("results", cols)];
+		const r = this.results;
+		if (!r.header) {
+			lines.push(color.dim("  no run yet — press enter to run the highlighted selection"));
+			return lines;
+		}
+		const done = r.scenarios.passed + r.scenarios.failed + r.scenarios.skipped;
+		lines.push(`  ${color.bold(`▶ ${r.header.label}`)} ${color.dim(`(run #${r.header.runCount} · ${r.header.clock})`)}`);
+		const scenarioTotal = r.running ? `${done}/${r.header.scenarioCount}` : done;
+		lines.push(`  ${countLine(String(scenarioTotal), "scenario", r.scenarios)}`);
+		const stepTotal = r.steps.passed + r.steps.failed + r.steps.skipped;
+		lines.push(`  ${countLine(String(stepTotal), "step", r.steps)}`);
+		lines.push(r.running ? color.dim("  running…") : color.dim(`  ${((r.durationMs ?? 0) / 1e3).toFixed(2)}s`));
+		for (const n of r.notes) lines.push(n);
+		if (r.dots.length) {
+			lines.push("");
+			const per = Math.max(1, cols - 2);
+			const dotRows = [];
+			for (let i = 0; i < r.dots.length; i += per) dotRows.push(`  ${r.dots.slice(i, i + per).join("")}`);
+			const maxDotRows = 6;
+			if (dotRows.length > maxDotRows) {
+				const hidden = dotRows.length - maxDotRows;
+				lines.push(color.dim(`  …${hidden} earlier row${hidden === 1 ? "" : "s"}`));
+				lines.push(...dotRows.slice(-6));
+			} else lines.push(...dotRows);
+		}
 		return lines;
 	}
 	render() {
-		if (this.suspended) return;
-		write("\x1B[?25l");
-		this.moveToBlockStart();
-		write("\x1B[0J");
-		const lines = this.buildLines();
-		write(lines.join("\r\n"));
-		this.rendered = lines.length;
-		write(`\r\x1b[${stringWidth(this.prefix) + this.cursor}C`);
+		if (!this.started) return;
+		const cols = this.cols();
+		const rows = this.rows();
+		const top = this.topLines();
+		const caretCol = Math.min(stringWidth(this.prefix) + this.cursor + 1, cols);
+		const above = [...top, ...this.resultLines(cols)];
+		const failLines = flattenFailures(this.results.failures);
+		const lines = [...above];
+		if (failLines.length) {
+			lines.push("", divider(`failures (${this.results.failures.length})`, cols));
+			const pane = Math.max(1, rows - lines.length - 1);
+			this.failPage = pane;
+			const maxScroll = Math.max(0, failLines.length - pane);
+			const off = Math.min(this.failScroll, maxScroll);
+			this.failScroll = off;
+			lines.push(...failLines.slice(off, off + pane));
+			if (maxScroll > 0) lines.push(color.dim(`  [${off + 1}-${off + Math.min(pane, failLines.length - off)}/${failLines.length}] · PgUp/PgDn to scroll`));
+		}
+		write("\x1B[?25l\x1B[H");
+		write(lines.slice(0, rows).map((l) => `${clip(l, cols)}\x1b[K`).join("\r\n"));
+		write("\x1B[J");
+		write(`\x1b[1;${Math.max(1, caretCol)}H`);
 		write("\x1B[?25h");
 	}
-	/** Erase the block and leave the caret at the block's top-left. */
-	erase() {
-		this.moveToBlockStart();
-		write("\x1B[0J");
-		this.rendered = 0;
-	}
-	/** Move the caret to column 0 of the block's first line. */
-	moveToBlockStart() {
-		if (this.rendered > 1) write(`\x1b[${this.rendered - 1}A`);
-		write("\r");
-	}
 };
+/** A green `.` / red `F` / yellow `-` for a finished scenario. */
+function dotFor(status) {
+	if (status === "failed") return color.red("F");
+	if (status === "skipped") return color.yellow("-");
+	return color.green(".");
+}
+/** `<total> <noun>s (X passed, Y failed, Z skipped)`, zero parts omitted. */
+function countLine(total, noun, counts) {
+	const part = (n, label, paint) => n > 0 ? paint(`${n} ${label}`) : null;
+	const parts = [
+		part(counts.passed, "passed", color.green),
+		part(counts.failed, "failed", color.red),
+		part(counts.skipped, "skipped", color.yellow)
+	].filter((x) => x !== null);
+	return `${total} ${noun}${total === "1" ? "" : "s"}${parts.length ? ` (${parts.join(", ")})` : ""}`;
+}
+/** Flatten failure blocks into lines, a blank line between blocks. */
+function flattenFailures(blocks) {
+	const out = [];
+	blocks.forEach((block, i) => {
+		if (i > 0) out.push("");
+		out.push(...block.split("\n"));
+	});
+	return out;
+}
+/** A dim `── label ─────` rule spanning the given width. */
+function divider(label, cols) {
+	const head = `── ${label} `;
+	const fill = Math.max(0, cols - head.length);
+	return color.dim(head + "─".repeat(fill));
+}
 /** Visible width, ignoring the ANSI escapes our color helpers may inject. */
 function stringWidth(s) {
 	return s.replace(/\x1b\[[0-9;]*m/g, "").length;
 }
+/**
+* Truncate `s` to `max` visible columns, preserving ANSI color escapes (which
+* have zero width) and re-resetting at the cut so a clipped color can't bleed.
+*/
+function clip(s, max) {
+	let width = 0;
+	let out = "";
+	const escape = /^\x1b\[[0-9;]*m/;
+	let i = 0;
+	while (i < s.length) {
+		const rest = s.slice(i);
+		const m = escape.exec(rest);
+		if (m) {
+			out += m[0];
+			i += m[0].length;
+			continue;
+		}
+		if (width >= max) return `${out}\x1b[0m`;
+		out += s[i];
+		width++;
+		i++;
+	}
+	return out;
+}
 function write(s) {
 	process.stdout.write(s);
 }
@@ -818,7 +1101,6 @@ var InteractiveSession = class {
 			return;
 		}
 		this.running = true;
-		this.prompt.beginOutput();
 		this.runLoop();
 	}
 	async runLoop() {
@@ -828,11 +1110,12 @@ var InteractiveSession = class {
 				if (this.armed) await this.executeOnce(this.armed);
 			} while (this.rerunQueued && this.armed && !this.dirty);
 		} catch (err) {
-			process.stdout.write(red(`\n  run failed: ${err instanceof Error ? err.message : err}\n`));
+			this.prompt.failureBlock(red(`run failed: ${err instanceof Error ? err.message : err}`));
+			this.prompt.complete(0);
 		} finally {
 			this.running = false;
 			this.prompt.status = this.status();
-			this.prompt.endOutput();
+			this.prompt.redraw();
 		}
 	}
 	/**
@@ -845,65 +1128,112 @@ var InteractiveSession = class {
 	*/
 	async executeOnce(choice) {
 		const selected = resolveScenarios(choice, this.scenarios());
-		const count = `${selected.length} scenario${selected.length === 1 ? "" : "s"}`;
-		process.stdout.write(`\n${bold(`▶ ${choiceLabel(choice)}`)} ${dim(`(${count} · run #${++this.runCount} · ${clock()})`)}\n\n`);
+		this.prompt.resetResults({
+			label: choiceLabel(choice),
+			scenarioCount: selected.length,
+			runCount: ++this.runCount,
+			clock: clock()
+		});
 		if (selected.length === 0) {
-			process.stdout.write(yellow("  no scenarios match this selection\n"));
+			this.prompt.note(yellow("  no scenarios match this selection"));
+			this.prompt.complete(0);
 			return;
 		}
-		const single = selected.length === 1;
-		if (single) await this.analyzeScenario(selected[0]);
-		await this.spawnRun(runArgs(choice, single, this.config));
+		if (selected.length === 1) for (const line of await this.analyzeScenario(selected[0])) this.prompt.note(line);
+		await this.spawnRun(runArgs(choice, this.config));
 	}
 	/** Every scenario across the current catalog, flattened. */
 	scenarios() {
 		return this.catalog.flatMap((f) => f.scenarios);
 	}
 	/**
-	* Run `step-forge` as a child process with `args`, streaming its output to the
-	* terminal (where the erased prompt was). Re-invokes the very CLI that's
-	* running us (`process.execPath` + `argv[1]`), so it works identically from
-	* the source tree and the built bin. Never rejects — a spawn error is reported
-	* and swallowed so the watch loop survives.
+	* Run `step-forge --events` as a child process and feed its NDJSON event
+	* stream into the results region as it arrives — live tallies, dots, and
+	* failure blocks. Re-invokes the very CLI that's running us (`process.execPath`
+	* + `argv[1]`), so it works identically from the source tree and the built bin.
+	* `FORCE_COLOR` keeps the child's rendered failure blocks coloured even though
+	* its stdout is a pipe. Never rejects — errors are surfaced and swallowed so
+	* the watch loop survives.
 	*/
 	spawnRun(args) {
 		return new Promise((resolve) => {
 			const child = (0, node_child_process.spawn)(process.execPath, [process.argv[1], ...args], {
 				cwd: this.config.cwd,
+				env: {
+					...process.env,
+					FORCE_COLOR: "1"
+				},
 				stdio: [
 					"ignore",
-					"inherit",
-					"inherit"
+					"pipe",
+					"pipe"
 				]
 			});
+			let completed = false;
+			let durationMs = 0;
+			let stdoutBuf = "";
+			let stderr = "";
+			child.stdout.setEncoding("utf8");
+			child.stdout.on("data", (chunk) => {
+				stdoutBuf += chunk;
+				let nl;
+				while ((nl = stdoutBuf.indexOf("\n")) !== -1) {
+					const line = stdoutBuf.slice(0, nl);
+					stdoutBuf = stdoutBuf.slice(nl + 1);
+					if (!line.trim()) continue;
+					let evt;
+					try {
+						evt = JSON.parse(line);
+					} catch {
+						continue;
+					}
+					if (evt.t === "scenario") this.prompt.scenario(evt.status, evt.steps, evt.detail);
+					else if (evt.t === "complete") {
+						completed = true;
+						durationMs = evt.durationMs;
+					}
+				}
+			});
+			child.stderr.setEncoding("utf8");
+			child.stderr.on("data", (chunk) => {
+				stderr += chunk;
+			});
 			child.on("error", (err) => {
-				process.stdout.write(red(`  could not start runner: ${err.message}\n`));
+				this.prompt.failureBlock(red(`could not start runner: ${err.message}`));
+				this.prompt.complete(0);
+				resolve();
+			});
+			child.on("close", () => {
+				if (completed) this.prompt.complete(durationMs);
+				else {
+					const detail = stderr.trim() || "(no output)";
+					this.prompt.failureBlock(red(`runner exited without reporting results:\n${detail}`));
+					this.prompt.complete(0);
+				}
 				resolve();
 			});
-			child.on("close", () => resolve());
 		});
 	}
 	/**
-	* Run the static analyzer over a single scenario and print any dependency /
-	* undefined / ambiguous diagnostics. The analyzer needs the optional
-	* `typescript` peer for AST extraction; if it's absent we note that and skip,
-	* never failing the run.
+	* Run the static analyzer over a single scenario and return any dependency /
+	* undefined / ambiguous diagnostics as note lines for the results region. The
+	* analyzer needs the optional `typescript` peer for AST extraction; if it's
+	* absent we note that and skip, never failing the run.
 	*/
 	async analyzeScenario(scenario) {
 		let analyzer;
 		try {
 			analyzer = await Promise.resolve().then(() => require("./analyzer-DIZPMxzN.cjs")).then((n) => n.analyzer_exports);
 		} catch {
-			process.stdout.write(dim("  analysis skipped: install `typescript` to enable it\n\n"));
-			return;
+			return [dim("  analysis skipped: install `typescript` to enable it")];
 		}
 		try {
 			const stepFiles = await require_gherkinParser.globFiles(this.config.steps, this.config.cwd);
 			const defs = analyzer.extractStepDefinitions(stepFiles);
 			const matched = analyzer.matchScenarioSteps(scenario, defs);
-			printDiagnostics(analyzer.defaultRules.flatMap((rule) => rule.check(scenario, matched)), this.config.cwd);
+			return formatDiagnostics(analyzer.defaultRules.flatMap((rule) => rule.check(scenario, matched)), this.config.cwd);
 		} catch (err) {
-			process.stdout.write(dim(`  analysis unavailable: ${err instanceof Error ? err.message : err}\n\n`));
+			return [dim(`  analysis unavailable: ${err instanceof Error ? err.message : err}`)];
 		}
 	}
 	status() {
@@ -981,9 +1311,10 @@ function choiceLabel(choice) {
 *   - feature → that single feature file
 *   - scenario → that feature file, name-anchored with `-n "/^…$/"` (the name is
 *     the outline name for an outline, so all its rows run)
-* A single scenario runs verbose; a population uses the configured reporter.
+* Always `--events`: the child emits its NDJSON run stream and the TUI renders
+* the results region itself.
 */
-function runArgs(choice, single, config) {
+function runArgs(choice, config) {
 	const args = [];
 	for (const glob of config.steps) args.push("-s", glob);
 	if (config.world) args.push("-w", config.world);
@@ -999,11 +1330,7 @@ function runArgs(choice, single, config) {
 			args.push(choice.file, "-n", `/^${escapeRegExp(choice.name)}$/`);
 			break;
 	}
-	if (single) args.push("-v");
-	else {
-		args.push("-r", config.reporter);
-		if (config.verbose) args.push("-v");
-	}
+	args.push("--events");
 	return args;
 }
 /** Escape a scenario name for use inside an anchored `-n` regex. */
@@ -1019,15 +1346,15 @@ function clock() {
 		d.getSeconds()
 	].map((n) => String(n).padStart(2, "0")).join(":");
 }
-function printDiagnostics(diagnostics, cwd) {
-	if (diagnostics.length === 0) return;
-	process.stdout.write(bold("  analyzer:\n"));
+function formatDiagnostics(diagnostics, cwd) {
+	if (diagnostics.length === 0) return [];
+	const lines = [bold("  analyzer:")];
 	for (const d of diagnostics) {
 		const mark = d.severity === "error" ? red("✗") : d.severity === "warning" ? yellow("!") : dim("i");
 		const loc = `${node_path.relative(cwd, d.file)}:${d.range.startLine}`;
-		process.stdout.write(`  ${mark} ${d.message} ${dim(`(${loc})`)}\n`);
+		lines.push(`  ${mark} ${d.message} ${dim(`(${loc})`)}`);
 	}
-	process.stdout.write("\n");
+	return lines;
 }
 //#endregion
 //#region src/runtime/cli.ts
@@ -1090,6 +1417,7 @@ function parseCli(argv) {
 				type: "boolean",
 				short: "i"
 			},
+			events: { type: "boolean" },
 			config: { type: "string" },
 			help: {
 				type: "boolean",
@@ -1120,17 +1448,18 @@ function parseCli(argv) {
 	return {
 		cwd: values.config ? node_path.resolve(process.cwd(), values.config) : process.cwd(),
 		overrides,
-		interactive: values.interactive ?? false
+		interactive: values.interactive ?? false,
+		events: values.events ?? false
 	};
 }
 async function main() {
-	const { cwd, overrides, interactive } = parseCli(process.argv.slice(2));
+	const { cwd, overrides, interactive, events } = parseCli(process.argv.slice(2));
 	const config = resolveConfig(cwd, await loadConfigFile(cwd), overrides);
 	if (interactive) {
 		await runInteractive(config);
 		return;
 	}
-	const { passed } = await run(config);
+	const { passed } = events ? await run(config, eventsReporter({ cwd: config.cwd })) : await run(config);
 	process.exitCode = passed ? 0 : 1;
 }
 main().catch((err) => {