@effected/cli 0.9.0 → 0.11.0

package/ui/testing/CliUiTest.js

@@ -0,0 +1,735 @@
+import { CliInteractive } from "../../CliInteractive.js";
+import { CliTheme } from "../../CliTheme.js";
+import { inkModules } from "../internal/ink.js";
+import { holder, holderSlot } from "../internal/Holder.js";
+import { UiStreams } from "../UiStreams.js";
+import { UiRenderOptions } from "../internal/renderOptions.js";
+import { CliUi } from "../CliUi.js";
+import { makeFakeStreams } from "./fakeStreams.js";
+import { screenAfter } from "./terminalModel.js";
+import { Cause, Console, Effect, Exit, Fiber, Inspectable, Layer, Option, Queue, Stream } from "effect";
+import { TerminalEnv } from "@effected/env";
+import { TestClock } from "effect/testing";
+
+//#region src/ui/testing/CliUiTest.ts
+/** The tokens, in the order their marker colours are numbered. */
+const TOKENS = [
+	"success",
+	"failure",
+	"warning",
+	"info",
+	"error",
+	"muted",
+	"accent",
+	"emphasis"
+];
+/** The marker palette: token N (1-based) paints in `#0000NN`, so a frame decodes back to the token. */
+const MARKER_STYLES = Object.fromEntries(TOKENS.map((token, index) => [token, { fg: `#0000${(index + 1).toString(16).padStart(2, "0")}` }]));
+const TOKEN_BY_BLUE = new Map(TOKENS.map((token, index) => [index + 1, token]));
+const NAMED = [
+	"black",
+	"red",
+	"green",
+	"yellow",
+	"blue",
+	"magenta",
+	"cyan",
+	"white"
+];
+/** The bytes a terminal in raw mode sends for each named key, as Ink's keypress parser reads them. */
+const KEY_BYTES = {
+	up: "\x1B[A",
+	down: "\x1B[B",
+	right: "\x1B[C",
+	left: "\x1B[D",
+	enter: "\r",
+	space: " ",
+	tab: "	",
+	"shift+tab": "\x1B[Z",
+	backspace: "",
+	delete: "\x1B[3~",
+	escape: "\x1B",
+	"ctrl+c": "",
+	home: "\x1B[H",
+	end: "\x1B[F",
+	pageup: "\x1B[5~",
+	pagedown: "\x1B[6~"
+};
+const ESCAPES = /\u001b\[([0-9;]*)m|\u001b\[[0-9;?]*[A-Za-z]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g;
+const hex = (r, g, b) => `#${[
+	r,
+	g,
+	b
+].map((channel) => channel.toString(16).padStart(2, "0")).join("")}`;
+/** Decode one run of SGR parameters into markup, against the stack of open styles. */
+const decodeSgr = (params, open) => {
+	let out = "";
+	const close = (kind) => {
+		for (let index = open.length - 1; index >= 0; index--) {
+			const entry = open[index];
+			if (entry?.kind === kind) {
+				out += entry.close;
+				open.splice(index, 1);
+				return;
+			}
+		}
+	};
+	const push = (kind, tag, closeTag) => {
+		if (kind === "fg" || kind === "bg") close(kind);
+		out += tag;
+		open.push({
+			kind,
+			close: closeTag
+		});
+	};
+	const colour = (kind, codes, at) => {
+		if (codes[at + 1] === 2) {
+			const [r, g, b] = [
+				codes[at + 2] ?? 0,
+				codes[at + 3] ?? 0,
+				codes[at + 4] ?? 0
+			];
+			const token = kind === "fg" && r === 0 && g === 0 ? TOKEN_BY_BLUE.get(b) : void 0;
+			if (token !== void 0) push(kind, `[${token}]`, `[/${token}]`);
+			else push(kind, `[${kind}:${hex(r, g, b)}]`, `[/${kind}]`);
+			return at + 4;
+		}
+		if (codes[at + 1] === 5) {
+			push(kind, `[${kind}:ansi256(${codes[at + 2] ?? 0})]`, `[/${kind}]`);
+			return at + 2;
+		}
+		return at;
+	};
+	const codes = params === "" ? [0] : params.split(";").map(Number);
+	for (let at = 0; at < codes.length; at++) {
+		const code = codes[at] ?? 0;
+		if (code === 0) while (open.length > 0) close(open[open.length - 1]?.kind ?? "fg");
+		else if (code === 1) push("b", "[b]", "[/b]");
+		else if (code === 2) push("dim", "[dim]", "[/dim]");
+		else if (code === 22) {
+			close("dim");
+			close("b");
+		} else if (code === 3) push("i", "[i]", "[/i]");
+		else if (code === 23) close("i");
+		else if (code === 4) push("u", "[u]", "[/u]");
+		else if (code === 24) close("u");
+		else if (code === 7) push("inverse", "[inverse]", "[/inverse]");
+		else if (code === 27) close("inverse");
+		else if (code === 9) push("s", "[s]", "[/s]");
+		else if (code === 29) close("s");
+		else if (code >= 30 && code <= 37) push("fg", `[fg:${NAMED[code - 30]}]`, "[/fg]");
+		else if (code >= 90 && code <= 97) push("fg", `[fg:${NAMED[code - 90]}Bright]`, "[/fg]");
+		else if (code === 38) at = colour("fg", codes, at);
+		else if (code === 39) close("fg");
+		else if (code >= 40 && code <= 47) push("bg", `[bg:${NAMED[code - 40]}]`, "[/bg]");
+		else if (code >= 100 && code <= 107) push("bg", `[bg:${NAMED[code - 100]}Bright]`, "[/bg]");
+		else if (code === 48) at = colour("bg", codes, at);
+		else if (code === 49) close("bg");
+	}
+	return out;
+};
+const styled = (ansi) => {
+	const open = [];
+	let out = "";
+	let last = 0;
+	for (const match of ansi.matchAll(ESCAPES)) {
+		out += ansi.slice(last, match.index);
+		last = match.index + match[0].length;
+		if (match[1] !== void 0) out += decodeSgr(match[1], open);
+	}
+	out += ansi.slice(last);
+	for (let index = open.length - 1; index >= 0; index--) out += open[index]?.close ?? "";
+	return out;
+};
+const trimLines = (text) => text.split("\n").map((line) => line.trimEnd()).join("\n");
+/**
+* Markup only this harness writes: a token tag opened and closed (`[info]…[/info]`), or a colour tag. A lone
+* `[info]` is a log prefix, and style-only tags (`[b]`, `[i]`) are too common in unrelated data, so neither is claimed.
+*/
+const MARKUP = new RegExp(`\\[(${TOKENS.join("|")})\\][\\s\\S]*?\\[/\\1\\]|\\[(?:fg|bg):[^\\]\\s]+\\]`);
+/** Run `register`'s check on native timers, which a `TestClock` cannot hold, until it says done. */
+const realTime = (poll) => Effect.callback((resume) => {
+	if (poll()) return resume(Effect.void);
+	const timer = setInterval(() => {
+		if (poll()) {
+			clearInterval(timer);
+			resume(Effect.void);
+		}
+	}, 2);
+	return Effect.sync(() => clearInterval(timer));
+});
+/**
+* Resume once every timer already due by the wall clock has run.
+*
+* @remarks
+* A zero-delay timer set straight away is not enough: during a timers phase the loop's time is the one cached when the
+* phase began, so after a long block a new timer can count as due before an older one the wall clock says is overdue.
+* `setImmediate` runs in the check phase, after the loop has refreshed its time; a zero-delay timer set there comes due
+* after every timer already overdue, so the next timers phase runs them first.
+*/
+const afterDueTimers = Effect.callback((resume) => {
+	let timer;
+	let after;
+	const immediate = setImmediate(() => {
+		timer = setTimeout(() => {
+			after = setImmediate(() => resume(Effect.void));
+		}, 0);
+	});
+	return Effect.sync(() => {
+		clearImmediate(immediate);
+		if (timer !== void 0) clearTimeout(timer);
+		if (after !== void 0) clearImmediate(after);
+	});
+});
+const QUIET_MS = 50;
+const TRAILING_QUIET_MS = 8;
+const ESCAPE_FLUSH_MS = 30;
+const MOUNT_LIMIT_MS = 2e3;
+const RERENDER_AFTER_END = "@effected/cli/ui/testing: rerender after the screen ended";
+const RERENDER_BEFORE_MOUNT = "@effected/cli/ui/testing: rerender before the screen mounted (waited 2 s; is another screen still mounted?)";
+const SCREEN_ENDED = "@effected/cli/ui/testing: a key was sent to a screen that has ended; take the screen mounted now with session.next()";
+const NEXT_DIED = (index, contains, mounted, why) => `@effected/cli/ui/testing: next waited for screen ${index + 1} to mount and ${contains === void 0 ? "draw" : `show "${contains}"`}, but ${why}; ${mounted} mounted so far`;
+const NOT_A_KEY = (method, text) => `@effected/cli/ui/testing: ${method}(${JSON.stringify(text)}): ${JSON.stringify(text)} is not a key name; send text with type(${JSON.stringify(text)}) or ${method}({ char: ${JSON.stringify(text)} })`;
+/** The bytes of a named key or a `{ char }`; a bare string that names no key is a defect saying how to send text. */
+const bytesOf = (key, method) => {
+	if (typeof key !== "string") return Effect.succeed(key.char);
+	return Object.hasOwn(KEY_BYTES, key) ? Effect.succeed(KEY_BYTES[key]) : Effect.die(new Error(NOT_A_KEY(method, key)));
+};
+/** A `Cancelled` from the root entrypoint, matched by shape: this entry may carry its own copy of the class. */
+const cancelledReason = (value) => {
+	if (typeof value !== "object" || value === null) return void 0;
+	const { _tag, reason } = value;
+	return _tag === "Cancelled" && (reason === "escape" || reason === "interrupt") ? reason : void 0;
+};
+/** Synchronized-update brackets and cursor show/hide: written around a frame, never a frame themselves. */
+const FRAME_BRACKETS = /\u001b\[\?(?:2026|25)[hl]/g;
+/** A chunk of nothing but control sequences: Ink erasing its frame to write a log line above it. */
+const CONTROLS_ONLY = /^(?:\u001b\[[0-9;?]*[A-Za-z])*$/;
+/** The erase and cursor moves log-update writes before a frame; colour (SGR, `m`) is part of the frame. */
+const LEADING_MOVES = /^(?:\u001b\[[0-9;?]*[A-Za-ln-z])+/;
+/**
+* The in-memory terminal `render`, `session` and `live` share: fake streams, the environment, and a capture per mount,
+* with the settle-and-send machinery that drives a screen.
+*
+* @remarks
+* In `"debug"` mode (screens) Ink writes each frame whole and the capture keeps it as written. In `"production"` mode
+* (the live view) Ink runs as it does for real: each render writes its erase moves and the new frame in one write, so
+* the capture keeps that write without its moves; a write of moves alone is Ink clearing the frame for a log line, not
+* a frame. stderr is the same stream as stdout there, as on a terminal, so the transcript holds both.
+*/
+const makeTerminal = (options, mode = "debug") => {
+	const columns = options.columns ?? 80;
+	const rows = options.rows ?? 24;
+	const color = options.color ?? "truecolor";
+	const captures = [];
+	let lastWrite = 0;
+	let frameDue = false;
+	const fake = makeFakeStreams({
+		columns,
+		rows,
+		onStdoutWrite: (chunk) => {
+			lastWrite = Date.now();
+			const current = captures.at(-1);
+			if (!frameDue || current === void 0 || current.ended) return;
+			if (mode === "debug") {
+				frameDue = false;
+				current.raws.push(chunk);
+				return;
+			}
+			const text = chunk.replace(FRAME_BRACKETS, "");
+			if (text === "") return;
+			frameDue = false;
+			if (CONTROLS_ONLY.test(text)) return;
+			current.raws.push(text.replace(LEADING_MOVES, "").replace(/\n+$/, ""));
+		}
+	});
+	const streams = mode === "production" ? {
+		...fake.streams,
+		stderr: fake.streams.stdout
+	} : fake.streams;
+	const stream = {
+		isTerminal: true,
+		color,
+		hyperlinks: false,
+		columns: Option.some(columns)
+	};
+	const terminal = TerminalEnv.layerTest({
+		stdinIsTerminal: true,
+		stdout: stream,
+		stderr: stream
+	});
+	const layer = Layer.mergeAll(CliTheme.layer({
+		tokens: MARKER_STYLES,
+		glyphs: options.glyphs ?? "unicode"
+	}).pipe(Layer.provide(terminal)), CliInteractive.layerTest(options.interactive ?? true), Layer.succeed(UiStreams, streams), Layer.succeed(UiRenderOptions, {
+		...mode === "debug" ? { debug: true } : {},
+		onRender: () => {
+			frameDue = true;
+		},
+		onMount: () => {
+			captures.push({
+				raws: [],
+				ended: false,
+				crash: void 0
+			});
+		},
+		onUnmount: (crash) => {
+			frameDue = false;
+			const current = captures.at(-1);
+			if (current === void 0) return;
+			current.ended = true;
+			current.crash = crash;
+		}
+	}));
+	/**
+	* Wait until a frame after `before` has been followed by a short quiet, so a reaction that renders twice is read
+	* whole; or, with no new frame, until quiet since the later of `since` and the last write. Never longer than
+	* `limitMs` from the first new frame once one has come, so a screen that never stops drawing still lets the wait end;
+	* counted from that frame rather than from `since`, so a loaded machine that was slow to draw it still gets the
+	* time to see the reaction that follows it.
+	*/
+	const settle = (raws, ended, before, since, limitMs = QUIET_MS) => Effect.suspend(() => {
+		let firstFrameAt;
+		const pastLimit = (now) => firstFrameAt !== void 0 && now - firstFrameAt >= limitMs;
+		const quiet = realTime(() => {
+			if (ended()) return true;
+			const now = Date.now();
+			if (raws().length > before) {
+				firstFrameAt ??= now;
+				return now - lastWrite >= TRAILING_QUIET_MS || pastLimit(now);
+			}
+			return now - Math.max(since, lastWrite) >= QUIET_MS && now - since >= QUIET_MS;
+		});
+		const confirmed = Effect.flatMap(quiet, () => {
+			const seen = lastWrite;
+			return Effect.flatMap(afterDueTimers, () => lastWrite === seen || ended() || pastLimit(Date.now()) ? Effect.void : confirmed);
+		});
+		return confirmed;
+	});
+	/**
+	* Drive and read the screen whose capture `capture` returns (none yet: no frames), ended when `ended` says. A crash
+	* is never swallowed: once `failed` (by default, the capture's own crash) holds a cause, every read and send dies
+	* with it, so a screen that drew nothing is never read as an empty one.
+	*/
+	const screen = (capture, ended, failed = () => {
+		const crash = capture()?.crash;
+		return crash === void 0 ? void 0 : Cause.die(crash.defect);
+	}) => {
+		const surfaced = (effect) => Effect.suspend(() => {
+			const cause = failed();
+			return cause === void 0 ? effect : Effect.die(Cause.squash(cause));
+		});
+		const raws = () => capture()?.raws ?? [];
+		const after = (before, since) => settle(raws, ended, before, since);
+		const send = (bytes, flushMs = 0) => Effect.suspend(() => {
+			if (ended()) return Effect.die(/* @__PURE__ */ new Error(SCREEN_ENDED));
+			const before = raws().length;
+			fake.input(bytes);
+			const sent = Date.now();
+			const flushed = flushMs === 0 ? Effect.void : realTime(() => Date.now() - sent >= flushMs);
+			return Effect.andThen(flushed, after(before, Date.now()));
+		});
+		return {
+			handle: {
+				press: (...keys) => Effect.forEach(keys, (key) => surfaced(Effect.flatMap(bytesOf(key, "press"), (bytes) => send(bytes, key === "escape" ? ESCAPE_FLUSH_MS : 0))), { discard: true }),
+				type: (text) => Effect.forEach([...text], (character) => surfaced(send(character)), { discard: true }),
+				chunk: (...keys) => surfaced(Effect.flatMap(Effect.forEach(keys, (key) => bytesOf(key, "chunk")), (bytes) => send(bytes.join(""), keys.at(-1) === "escape" ? ESCAPE_FLUSH_MS : 0))),
+				resize: (nextColumns, nextRows) => surfaced(Effect.suspend(() => {
+					const before = raws().length;
+					const since = Date.now();
+					fake.resize(nextColumns, nextRows);
+					return after(before, since);
+				})),
+				frame: surfaced(Effect.sync(() => trimLines(styled(raws().at(-1) ?? "")))),
+				rawFrame: surfaced(Effect.sync(() => raws().at(-1) ?? "")),
+				plainFrame: surfaced(Effect.sync(() => trimLines((raws().at(-1) ?? "").replace(ESCAPES, "")))),
+				frames: surfaced(Effect.sync(() => raws().map((raw) => trimLines(styled(raw)))))
+			},
+			raws,
+			after,
+			surfaced
+		};
+	};
+	return {
+		fake,
+		layer,
+		captures,
+		screen,
+		settle
+	};
+};
+/**
+* Mount `screen` on a fresh terminal for the enclosing scope, held in a swappable holder so a rerender changes only its
+* subtree under the same control: what `render` and `view` share. Ready once the first frame is drawn, the screen has
+* ended, or 2 s have passed. A crash surfaces on every read and send, as on a session's screen; with `refusal`, so does
+* a run refused as not interactive, for a view, which has no `result` to carry it.
+*/
+const mount = (screen, options, refusal) => Effect.gen(function* () {
+	const terminal = makeTerminal(options);
+	let ended = false;
+	let failure;
+	const slot = holderSlot();
+	let control;
+	const held = async (given) => {
+		control = given;
+		const initial = await screen(given);
+		return inkModules().react.createElement(holder(), {
+			initial,
+			bind: slot.bind
+		});
+	};
+	const fiber = yield* Effect.forkScoped(CliUi.run(held).pipe(Effect.provide(terminal.layer), Effect.onExit((exit) => Effect.sync(() => {
+		ended = true;
+		if (Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause) && (exit.cause.reasons.some(Cause.isDieReason) || cancelledReason(Cause.squash(exit.cause)) === void 0)) failure = exit.cause;
+	}))));
+	const { handle, raws, after, surfaced } = terminal.screen(() => terminal.captures[0], () => ended, refusal ? () => failure : void 0);
+	const mountedBy = Date.now() + MOUNT_LIMIT_MS;
+	yield* realTime(() => raws().length > 0 || ended || Date.now() >= mountedBy);
+	yield* after(0, Date.now());
+	const swapTo = (next) => Effect.gen(function* () {
+		const mountedBy = Date.now() + MOUNT_LIMIT_MS;
+		yield* realTime(() => slot.isBound() || ended || Date.now() >= mountedBy);
+		if (ended) return yield* Effect.die(/* @__PURE__ */ new Error(RERENDER_AFTER_END));
+		if (!slot.isBound() || control === void 0) return yield* Effect.die(/* @__PURE__ */ new Error(RERENDER_BEFORE_MOUNT));
+		const given = control;
+		const element = yield* Effect.promise(async () => next(given));
+		const before = raws().length;
+		const since = Date.now();
+		if (ended || !slot.swap(element)) {
+			const endedBy = Date.now() + MOUNT_LIMIT_MS;
+			yield* realTime(() => ended || Date.now() >= endedBy);
+			return yield* surfaced(Effect.die(/* @__PURE__ */ new Error(RERENDER_AFTER_END)));
+		}
+		yield* after(before, since);
+	});
+	const rerender = (next) => surfaced(Effect.andThen(swapTo(next), surfaced(Effect.void)));
+	return {
+		handle,
+		rerender,
+		fiber,
+		surfaced
+	};
+});
+/** A `Console` that keeps what is written: `log`, `info` and `debug` as stdout, `error`, `warn` and `trace` as stderr. */
+const capturingConsole = (ambient) => {
+	const out = [];
+	const err = [];
+	const line = (sink) => (...args) => {
+		sink.push(`${args.map((arg) => Inspectable.toStringUnknown(arg, 0)).join(" ")}\n`);
+	};
+	return {
+		writer: Object.assign(Object.create(ambient), {
+			log: line(out),
+			info: line(out),
+			debug: line(out),
+			error: line(err),
+			warn: line(err),
+			trace: line(err)
+		}),
+		out,
+		err
+	};
+};
+/**
+* Drive and read Ink screens in tests: mount a screen on in-memory streams, press keys, and read its frames as token
+* markup.
+*
+* @example
+* ```ts
+* import { assert, it } from "@effect/vitest"
+* import { Select } from "@effected/cli/ui"
+* import { CliUiTest } from "@effected/cli/ui/testing"
+* import { Effect } from "effect"
+*
+* it.effect("chooses the second option", () =>
+*   Effect.gen(function* () {
+*     const choices = [
+*       { label: "a", value: "a" },
+*       { label: "b", value: "b" },
+*     ]
+*     const handle = yield* CliUiTest.render(Select.screen({ message: "Pick one", choices }))
+*     yield* handle.press("down", "enter")
+*     assert.strictEqual(yield* handle.result, "b")
+*   }).pipe(Effect.scoped),
+* )
+* ```
+*
+* @public
+*/
+var CliUiTest = class {
+	constructor() {}
+	/**
+	* Mount `screen` on in-memory terminal streams for the enclosing scope.
+	*
+	* @remarks
+	* The screen runs under a fixed environment: a `TerminalEnv` test layer with the given columns and colour, a
+	* `CliTheme` whose every token paints in its own marker colour (so frames do not depend on the real palette), and
+	* `CliInteractive` set from `interactive`. Ink renders in debug mode, writing every frame in full; the frames
+	* are taken from those writes. Closing the scope unmounts the screen. The returned handle is ready once the first
+	* frame is drawn or the screen has ended.
+	*
+	* Waiting is on real time, through native timers a `TestClock` cannot hold, so the harness's own waits work under
+	* `it.effect` and `it.live` alike, and never sleep longer than 50 ms past the last write (30 ms first, for Esc). A
+	* screen test that itself sleeps, times out or retries on a schedule needs `it.live` (or real timers): under
+	* `it.effect` those run on the `TestClock`, which nothing advances while a screen waits on real time.
+	*
+	* The first frame is awaited for at most 2 s: a screen that draws nothing for longer gives a handle whose `frames`
+	* is `[]`. Screens run one at a time process-wide (`CliUi.run`), so a second handle opened while another is
+	* still mounted waits for that mount: it returns at the 2 s cap with no frames, and its keys queue in its input until
+	* it mounts.
+	*
+	* Debug frames bypass Ink's erase-and-redraw path, so a harness frame says nothing about what Ink writes between
+	* frames on a real terminal (a screen clear, for instance), nor about the final frame left in the scrollback once
+	* the screen ends (answered screens stay); a test of that needs the production render path.
+	* For the same reason `CliUi.run`'s `clear` has no visible effect on a harness frame, since Ink's `clear` does
+	* nothing in debug mode: test `clear` on the production render path, as the kit's own tests do.
+	* Unmounting is the scope's close; to draw a different screen, render it in a new scope.
+	*
+	* A crash is never swallowed. A screen thunk that throws (a classic-JSX `React is not defined` included) or a
+	* component that throws ends the run with a defect: `result` dies with it, and so does the next frame read, key,
+	* resize or rerender, so a crashed screen is never read as one that drew nothing. As with `view`, after a crash
+	* the frames drawn before it cannot be read. A run refused as not interactive is `result`'s `NotInteractive`, and
+	* its frames read as `[]`.
+	*
+	* @param screen - the screen to mount
+	* @param options - the terminal's size, colour and glyphs, and whether the run is interactive
+	*/
+	static render = (screen, options = {}) => Effect.map(mount(screen, options, false), ({ handle, rerender, fiber }) => ({
+		...handle,
+		rerender,
+		result: Fiber.join(fiber)
+	}));
+	/**
+	* Mount a display-only element on in-memory terminal streams for the enclosing scope: a status line, a live view,
+	* a component a consumer mounts in an Ink tree of its own.
+	*
+	* @remarks
+	* The same harness as {@link CliUiTest.render}, with the same options: the marker-palette theme, the fake streams
+	* and the debug frames, and the element is drawn inside the kit's providers, so `useTheme`, `useGlyphs`,
+	* `useTerminalSize` and `Styled` work in it. The handle reads frames and sends keys as a rendered screen's does, and
+	* `rerender` swaps in another element, but it has no `result`: a display-only element never ends on its own, so a
+	* `render` of one would leave `result` waiting forever. Closing the scope unmounts it.
+	*
+	* The kit's root keys stay bound, as on every screen: Esc or Ctrl-C ends the view, after which a key or a rerender
+	* is a defect.
+	*
+	* An element that crashes, or a run that is refused (`interactive: false` ends it with `NotInteractive`), is never
+	* swallowed: `view` dies with that error when it happens before the first frame, and otherwise the next frame read,
+	* key, resize or rerender does. After a crash every read dies with it, `frames` included, so the frames drawn before
+	* the crash cannot be read: the crash is the signal a test needs. A deliberate end (Esc or Ctrl-C) is not a crash:
+	* the frames stay readable, and only a key, resize or rerender after it dies, saying the screen has ended.
+	*
+	* @param element - the element to mount
+	* @param options - the terminal's size, colour and glyphs, and whether the run is interactive
+	*/
+	static view = (element, options = {}) => Effect.flatMap(mount(() => element, options, true), ({ handle, rerender, surfaced }) => {
+		const view = {
+			...handle,
+			rerender: (next) => rerender(() => next)
+		};
+		return surfaced(Effect.succeed(view));
+	});
+	/**
+	* A terminal for a whole program that runs screens of its own (a wizard, a handler calling `CliUi.prompt` several
+	* times): provide its `layer` around the program, then take each screen as it mounts with `next`.
+	*
+	* @remarks
+	* The same environment and the same waiting as {@link CliUiTest.render}, with the same options. The session also
+	* keeps what the program writes through `Console`, its own output beside the screens, as `stdout` and `stderr`.
+	*
+	* Run the program forked (`Effect.forkScoped`) and drive it from the test: `next` returns each screen once it has
+	* mounted and drawn, `press` and `type` settle as they do on a rendered screen, and joining the program's fiber
+	* gives its exit. Screens still run one at a time, process-wide, so `next` sees them in the order they mount.
+	*
+	* As with `render`, a screen run with `clear` leaves its frames unchanged here, and the final scrollback is not
+	* captured: Ink renders in debug mode, where its `clear` does nothing, so test `clear` on the production render path.
+	* The waits are real time: a session test that itself sleeps or times out needs `it.live`. To assert that no screen
+	* mounted (a non-interactive run, a flag that skips a prompt), check that `mounts` is `0` once the program has
+	* finished.
+	*
+	* A screen that crashes (its thunk or a component throws) is never swallowed: `next` dies with the crash when it has
+	* happened by then, whatever `contains` waited for, and otherwise the screen's next frame read, key or resize does.
+	* The program's own fiber dies with it too.
+	*
+	* Driving a whole `Command` handler: provide `layer`, a fresh `CliExit.layer` if the handler records a code, a
+	* `ConfigProvider` that sandboxes what the handler reads (`HOME`, the XDG directories), and the platform core's
+	* runner needs, then fork the program and take each screen with `next`:
+	*
+	* ```ts
+	* const session = yield* CliUiTest.session()
+	* const program = Effect.gen(function* () {
+	*   yield* Command.runWith(root, { version })(["init"])
+	*   return MutableRef.get((yield* CliExit).code)
+	* }).pipe(
+	*   Effect.provide(session.layer),
+	*   Effect.provide(CliExit.layer),
+	*   Effect.provide(NodeServices.layer),
+	*   Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromUnknown({ HOME: "/sandbox/home" })),
+	* )
+	* const fiber = yield* Effect.forkScoped(program)
+	* yield* (yield* session.next({ contains: "Profile" })).press("enter")
+	* const code = yield* Fiber.join(fiber)
+	* ```
+	*
+	* To exercise `CliRuntime.main` as well (its failure report and exit code), run the program through it with the
+	* session's layer provided around it instead; `main` provides its own `CliExit`.
+	*
+	* @param options - the terminal's size, colour and glyphs, and whether the run is interactive
+	*/
+	static session = (options = {}) => Effect.map(Console.Console, (ambient) => {
+		const terminal = makeTerminal(options);
+		const output = capturingConsole(ambient);
+		let taken = 0;
+		const next = (nextOptions = {}) => Effect.gen(function* () {
+			const index = taken++;
+			const { contains } = nextOptions;
+			const capture = () => terminal.captures[index];
+			const { handle, raws, after, surfaced } = terminal.screen(capture, () => capture()?.ended ?? false);
+			const shows = () => contains === void 0 ? raws().length > 0 : raws().some((raw) => raw.replace(ESCAPES, "").includes(contains));
+			const by = Date.now() + MOUNT_LIMIT_MS;
+			yield* realTime(() => shows() || capture()?.ended === true || Date.now() >= by);
+			yield* surfaced(Effect.void);
+			if (!shows()) {
+				const why = capture() === void 0 ? "none mounted within 2 s" : capture()?.ended === true ? "it unmounted first" : "it did not within 2 s";
+				return yield* Effect.die(new Error(NEXT_DIED(index, contains, terminal.captures.length, why)));
+			}
+			yield* after(0, Date.now());
+			return handle;
+		});
+		return {
+			layer: Layer.merge(terminal.layer, Layer.succeed(Console.Console, output.writer)),
+			next,
+			mounts: Effect.sync(() => terminal.captures.length),
+			stdout: Effect.sync(() => output.out.join("")),
+			stderr: Effect.sync(() => output.err.join(""))
+		};
+	});
+	/**
+	* Mount a live view (`CliUi.live`) on a fresh in-memory terminal for the enclosing scope, with an event stream the
+	* test publishes to, and read what it draws on the production render path.
+	*
+	* @remarks
+	* The options are `CliUi.live`'s without `events`, which the harness supplies, and the terminal's own (`columns`,
+	* `rows`, `color`, `glyphs`, `interactive`). The view runs as it does for real: Ink is interactive and not in debug
+	* mode, so frames are what Ink actually writes, committed frames stay on the terminal, and `transcript` shows what is
+	* left there, scrollback included, through a small terminal model (it does not wrap a line wider than the terminal).
+	* stderr is the same stream as stdout, as on a terminal, so a line logged through `handle.logConsole` lands in the
+	* transcript too.
+	*
+	* Write live tests with `it.effect`: the view's tick runs on the `TestClock`, so `advance` (or `TestClock.adjust`)
+	* drives it frame by frame, and the frame index is `floor(now / tickMillis)` from the clock's epoch. The waits after
+	* `publish`, `advance` and `resize` are real time, which the `TestClock` does not hold. Without `@effect/vitest`'s
+	* `it.effect`, provide the clock yourself: `Effect.provide(test, TestClock.layer())` (from `effect/testing`).
+	*
+	* @example
+	* ```ts
+	* import { assert, it } from "@effect/vitest"
+	* import { CliUiTest } from "@effected/cli/ui/testing"
+	* import { Effect } from "effect"
+	* import { Text } from "ink"
+	* import { createElement } from "react"
+	*
+	* type Event = { readonly _tag: "RunStarted" } | { readonly _tag: "RunEnded" }
+	*
+	* it.effect("turns the spinner on the tick", () =>
+	*   Effect.gen(function* () {
+	*     const view = yield* CliUiTest.live({
+	*       initial: 0,
+	*       reduce: (count: number, _event: Event) => count + 1,
+	*       render: (_count, frame) => createElement(Text, null, `frame ${frame}`),
+	*       isStart: (event) => event._tag === "RunStarted",
+	*       isTerminal: (event) => event._tag === "RunEnded",
+	*     })
+	*     yield* view.publish({ _tag: "RunStarted" })
+	*     // The clock starts at 0 and the tick is 80 ms, so 160 ms on is frame 2.
+	*     yield* view.advance("160 millis")
+	*     assert.include(yield* view.plainFrame, "frame 2")
+	*   }).pipe(Effect.scoped),
+	* )
+	* ```
+	*
+	* @param options - the live view's options without `events`, and the terminal's size, colour, glyphs and
+	* interactivity
+	*/
+	static live = (options) => Effect.gen(function* () {
+		const { columns, rows, color, glyphs, interactive, ...view } = options;
+		const terminal = makeTerminal({
+			...columns === void 0 ? {} : { columns },
+			...rows === void 0 ? {} : { rows },
+			...color === void 0 ? {} : { color },
+			...glyphs === void 0 ? {} : { glyphs },
+			...interactive === void 0 ? {} : { interactive }
+		}, "production");
+		const queue = yield* Queue.unbounded();
+		const handle = yield* CliUi.live({
+			...view,
+			events: Stream.fromQueue(queue)
+		}).pipe(Effect.provide(terminal.layer));
+		const raws = () => terminal.captures.flatMap((capture) => capture.raws);
+		const settled = (effect) => Effect.suspend(() => {
+			const before = raws().length;
+			const since = Date.now();
+			return Effect.andThen(effect, terminal.settle(raws, () => false, before, since));
+		});
+		const last = () => raws().at(-1) ?? "";
+		return {
+			publish: (event) => settled(Queue.offer(queue, event)),
+			end: Effect.andThen(Queue.end(queue), handle.done),
+			advance: (duration) => settled(TestClock.adjust(duration)),
+			resize: (nextColumns, nextRows) => settled(Effect.sync(() => terminal.fake.resize(nextColumns, nextRows))),
+			frame: Effect.sync(() => trimLines(styled(last()))),
+			rawFrame: Effect.sync(last),
+			plainFrame: Effect.sync(() => trimLines(last().replace(ESCAPES, ""))),
+			frames: Effect.sync(() => raws().map((raw) => trimLines(styled(raw)))),
+			transcript: Effect.sync(() => screenAfter(terminal.fake.stdout(), terminal.fake.streams.stdout.rows).join("\n")),
+			written: Effect.sync(() => terminal.fake.stdout()),
+			handle
+		};
+	});
+	/**
+	* Why a screen or a program was cancelled, read from its `Exit` or `Cause`: `"escape"` or `"interrupt"` when it
+	* carries a `Cancelled`, as a typed failure or as a defect, else `None`.
+	*
+	* @remarks
+	* Pure. A screen's `result` fails with `Cancelled` in the typed channel; a prompt cancelled where the program
+	* declares no such error carries it as a defect. Either way a test asks this instead of walking `cause.reasons`:
+	*
+	* ```ts
+	* const exit = yield* Fiber.await(program)
+	* assert.deepStrictEqual(CliUiTest.cancelReason(exit), Option.some("escape"))
+	* ```
+	*
+	* @param exitOrCause - the exit of a screen's `result` or of a program, or a bare cause
+	*/
+	static cancelReason = (exitOrCause) => {
+		const cause = Exit.isExit(exitOrCause) ? Exit.isFailure(exitOrCause) ? exitOrCause.cause : void 0 : exitOrCause;
+		for (const reason of cause?.reasons ?? []) {
+			const found = cancelledReason(reason._tag === "Fail" ? reason.error : reason._tag === "Die" ? reason.defect : void 0);
+			if (found !== void 0) return Option.some(found);
+		}
+		return Option.none();
+	};
+	/**
+	* Decode ANSI back to markup: a marker colour to its token (`[success]…[/success]`), any other foreground to
+	* `[fg:red]` or `[fg:#ff0000]` (backgrounds likewise as `[bg:…]`), bold to `[b]`, dim to `[dim]`, italic, underline,
+	* inverse and strikethrough to `[i]`, `[u]`, `[inverse]` and `[s]`. A reset closes everything open; every other
+	* escape (cursor, erase, hyperlinks) is dropped.
+	*
+	* @param ansi - text with escapes
+	*/
+	static styled = styled;
+	/**
+	* A Vitest snapshot serializer. It claims a string carrying escapes, a token tag opened and closed, or a colour
+	* tag (a raw or styled frame, or a `Render.ansi` string), but not a log line's lone `[info]` prefix, nor one whose
+	* only brackets are style tags like `[b]`, which unrelated data uses too. It prints the string as token markup with
+	* each line's trailing spaces trimmed, so a snapshot reads without escapes and does not churn with the palette.
+	* Register it with `expect.addSnapshotSerializer`.
+	*/
+	static serializer = {
+		test: (value) => typeof value === "string" && (value.includes("\x1B") || MARKUP.test(value)),
+		serialize: (value) => trimLines(styled(String(value)))
+	};
+};
+
+//#endregion
+export { CliUiTest };