@effected/cli 0.10.0 → 0.11.0

package/ui/testing/fakeStreams.js

@@ -0,0 +1,76 @@
+import { PassThrough, Writable } from "node:stream";
+
+//#region src/ui/testing/fakeStreams.ts
+const capture = (columns, rows, onWrite) => {
+	const chunks = [];
+	const stream = new Writable({ write(chunk, _encoding, callback) {
+		const text = chunk.toString();
+		chunks.push(text);
+		onWrite?.(text);
+		callback();
+	} });
+	Object.assign(stream, {
+		isTTY: true,
+		columns,
+		rows
+	});
+	return {
+		stream,
+		text: () => chunks.join("")
+	};
+};
+/**
+* Make in-memory stdin, stdout and stderr that satisfy Ink's stream contract: TTYs with a size, a recorded
+* `setRawMode`, `ref` and `unref`, and captured writes.
+*
+* @remarks
+* The third file licensed to touch Node, testing only: Ink's stream
+* contract is Node's, so the fakes are `node:stream` streams rather than a hand-rolled emitter that would have to
+* reproduce `readable`, `read()`, `setEncoding` and the write-callback barrier Ink waits on at unmount.
+*
+* @internal
+*/
+const makeFakeStreams = (options = {}) => {
+	const columns = options.columns ?? 80;
+	const rows = options.rows ?? 24;
+	const rawModes = [];
+	const stdin = new PassThrough();
+	Object.assign(stdin, {
+		isTTY: true,
+		setRawMode: (mode) => {
+			rawModes.push(mode);
+			return stdin;
+		},
+		ref: () => stdin,
+		unref: () => stdin
+	});
+	const stdout = capture(columns, rows, options.onStdoutWrite);
+	const stderr = capture(columns, rows);
+	return {
+		streams: {
+			stdin,
+			stdout: stdout.stream,
+			stderr: stderr.stream
+		},
+		rawModes,
+		stdout: stdout.text,
+		stderr: stderr.text,
+		input: (data) => {
+			stdin.write(data);
+		},
+		resize: (nextColumns, nextRows) => {
+			Object.assign(stdout.stream, {
+				columns: nextColumns,
+				rows: nextRows
+			});
+			Object.assign(stderr.stream, {
+				columns: nextColumns,
+				rows: nextRows
+			});
+			stdout.stream.emit("resize");
+		}
+	};
+};
+
+//#endregion
+export { makeFakeStreams };

package/ui/testing/terminalModel.js

@@ -0,0 +1,59 @@
+//#region src/ui/testing/terminalModel.ts
+const ESC = String.fromCharCode(27);
+/**
+* A small terminal model for the production render path: what a terminal shows after `written`, as its non-empty
+* lines.
+*
+* @remarks
+* It applies printable text, line feeds, the erase and cursor moves Ink's log-update writes (erase line, cursor up,
+* cursor to column one), and the clears of Ink's clear-terminal frame: `ESC[2J` blanks the visible screen, `ESC[3J`
+* drops the scrollback above it, `ESC[H` homes the cursor to the screen's top left. The visible screen is the last
+* `rows` lines; with `rows` unknown, the whole buffer counts as the screen, so a clear takes everything. Every other
+* escape is ignored. It does not wrap a line wider than the terminal. Shared by `CliUiTest.live`'s transcript and the
+* kit's own production-path tests.
+*
+* @param written - every byte written to the terminal
+* @param rows - the terminal's height, which decides how much of the buffer a clear takes as the screen
+*
+* @internal
+*/
+const screenAfter = (written, rows) => {
+	const lines = [""];
+	let row = 0;
+	let column = 0;
+	const screenTop = () => rows === void 0 ? 0 : Math.max(0, lines.length - rows);
+	const sequence = new RegExp(`${ESC}\\[([0-9;?]*)([A-Za-z])|${ESC}\\][^\\u0007]*\\u0007|([\\s\\S])`, "g");
+	for (const match of written.matchAll(sequence)) {
+		const [, params, command, character] = match;
+		if (character !== void 0) {
+			if (character === "\n") {
+				row++;
+				column = 0;
+				while (lines.length <= row) lines.push("");
+			} else if (character === "\r") column = 0;
+			else if (character >= " ") {
+				const line = lines[row] ?? "";
+				lines[row] = `${line.slice(0, column).padEnd(column)}${character}${line.slice(column + 1)}`;
+				column++;
+			}
+		} else if (command === "K") lines[row] = "";
+		else if (command === "A") row = Math.max(0, row - Number(params === "" ? 1 : params));
+		else if (command === "G") column = 0;
+		else if (command === "J" && params === "2") for (let index = screenTop(); index < lines.length; index++) lines[index] = "";
+		else if (command === "J" && params === "3") {
+			const top = screenTop();
+			lines.splice(0, top);
+			row = Math.max(0, row - top);
+			if (lines.length === 0) lines.push("");
+		} else if (command === "H") {
+			const [line, col] = params === "" ? [1, 1] : params.split(";").map((part) => Number(part === "" ? 1 : part));
+			row = screenTop() + (line ?? 1) - 1;
+			column = (col ?? 1) - 1;
+			while (lines.length <= row) lines.push("");
+		}
+	}
+	return lines.map((line) => line.trimEnd()).filter((line) => line !== "");
+};
+
+//#endregion
+export { screenAfter };

package/ui-testing.d.ts

@@ -0,0 +1,446 @@
+import * as Cli from "@effected/cli";
+import { KeyName, LiveHandle, LiveOptions, Screen } from "@effected/cli/ui";
+import { ColorLevel } from "@effected/env";
+import { Cause, Duration, Effect, Exit, Layer, Option, Scope } from "effect";
+import { ReactElement } from "react";
+//#region src/ui/testing/CliUiTest.d.ts
+/**
+ * Options for {@link CliUiTest.render}, {@link CliUiTest.view} and {@link CliUiTest.session}, and the terminal's
+ * half of {@link CliUiTest.live}'s.
+ *
+ * @public
+ */
+interface CliUiTestOptions {
+  /** The terminal width the screen lays out at; 80 by default. */
+  readonly columns?: number;
+  /** The terminal height; 24 by default. */
+  readonly rows?: number;
+  /**
+   * The colour level of both streams; `"truecolor"` by default, so frames carry the marker palette that
+   * {@link CliUiTest.styled} decodes to token markup. `"none"` gives escape-free frames.
+   *
+   * @remarks
+   * Only truecolor keeps tokens apart. Below it, chalk maps every marker `#0000NN` to the same colour
+   * (`ansi256(16)` at `"256"`, black at `"basic"`), so token identity is lost; do not snapshot tokens from such a run.
+   */
+  readonly color?: ColorLevel;
+  /** The glyph set; Unicode by default. */
+  readonly glyphs?: "unicode" | "ascii";
+  /**
+   * Whether the run is interactive; `true` by default. `false` makes a screen fail with `NotInteractive`, and makes a
+   * live view print each run's final frame as a string instead of mounting it.
+   */
+  readonly interactive?: boolean;
+}
+/**
+ * A screen under test: drive it with keys and read its frames.
+ *
+ * @public
+ */
+interface CliUiTestScreen {
+  /**
+   * Press named keys, one after another. Each waits until the screen draws its next frame or 50 ms pass with
+   * nothing written; `"escape"` first waits a real 30 ms, because Ink holds a lone ESC for 20 ms before reporting
+   * it. Pressing, typing or chunking on a screen that has ended is a defect, not a key for whatever screen is mounted
+   * now.
+   *
+   * @remarks
+   * A `{ char }` item sends its text as typed, as `chunk` does, settling like a key: `press({ char: "n" }, "enter")`.
+   * A bare string that is not a key name (`press("n")`) is a defect naming `type("n")` and `{ char: "n" }`, since a
+   * letter is not a `KeyName`.
+   */
+  readonly press: (...keys: ReadonlyArray<KeyName | {
+    readonly char: string;
+  }>) => Effect.Effect<void>;
+  /** Type text, one character at a time, each settling like a key. */
+  readonly type: (text: string) => Effect.Effect<void>;
+  /**
+   * Press named keys together: all their bytes in ONE stdin write, then one settle, as a fast typist, a held key or
+   * a batching terminal delivers them.
+   *
+   * @remarks
+   * Ink dispatches every key of one read before React re-renders, so a handler that steps from state its render
+   * captured repeats the first key's move; {@link CliUiTestScreen.press}, which writes and settles key by key, can
+   * never show that. Use `chunk` to test a key handler against it. An `"escape"` inside a chunk joins the bytes after
+   * it, as on a real terminal; only a trailing one waits out Ink's ESC hold. A `{ char }` writes its text as typed:
+   * Ink hands text read in one go to `useInput` as one string, `"yy"` or `"y\r"`, which `useKeys` splits into keys.
+   */
+  readonly chunk: (...keys: ReadonlyArray<KeyName | {
+    readonly char: string;
+  }>) => Effect.Effect<void>;
+  /** Resize the terminal and emit `resize`, as a real one does, settling like a key. */
+  readonly resize: (columns: number, rows: number) => Effect.Effect<void>;
+  /** The latest frame as token markup ({@link CliUiTest.styled}), each line's trailing spaces trimmed. */
+  readonly frame: Effect.Effect<string>;
+  /** The latest frame as Ink wrote it, escapes included. */
+  readonly rawFrame: Effect.Effect<string>;
+  /** The latest frame as plain text: no escapes and no markup, each line's trailing spaces trimmed. */
+  readonly plainFrame: Effect.Effect<string>;
+  /** Every frame of this screen so far, oldest first, as token markup like {@link CliUiTestScreen.frame}. */
+  readonly frames: Effect.Effect<ReadonlyArray<string>>;
+}
+/**
+ * A screen mounted by {@link CliUiTest.render}: a {@link CliUiTestScreen} that can also be swapped and awaited.
+ *
+ * @public
+ */
+interface CliUiTestHandle<A> extends CliUiTestScreen {
+  /**
+   * Show another screen in place of the current one, settling like a key.
+   *
+   * @remarks
+   * `screen` is called with the same `ScreenControl` the first screen got, so `result` still resolves through it,
+   * and only the screen's own subtree is swapped: the error boundary, root keys and colour hold stay mounted. Ink's
+   * own `rerender` is never used. A rerender after the screen has ended is a defect, not a no-op, because a test
+   * that does it has lost track of the screen; so is one on a screen that has not mounted within 2 s, such as a
+   * handle queued behind another mounted screen.
+   */
+  readonly rerender: (screen: Screen<A>) => Effect.Effect<void>;
+  /** How the screen ended: its value, or `Cancelled` or `NotInteractive`. Waits for it to end. */
+  readonly result: Effect.Effect<A, Cli.Cancelled | Cli.NotInteractive>;
+}
+/**
+ * A display-only element mounted by {@link CliUiTest.view}: a {@link CliUiTestScreen} that can be swapped for another
+ * element, with no result to wait for.
+ *
+ * @public
+ */
+interface CliUiTestView extends CliUiTestScreen {
+  /**
+   * Show another element in place of the current one, settling like a key.
+   *
+   * @remarks
+   * Only the element's subtree is swapped: the kit's providers stay mounted. A rerender after the view has ended
+   * (Esc or Ctrl-C ends it, as on every screen) is a defect, not a no-op.
+   */
+  readonly rerender: (element: ReactElement) => Effect.Effect<void>;
+}
+/**
+ * Options for {@link CliUiTestSession.next}.
+ *
+ * @public
+ */
+interface CliUiTestNextOptions {
+  /**
+   * Text the screen must have shown, in plain text, before `next` returns it: in any frame since its mount, not
+   * necessarily the latest one. Read `plainFrame` to check what it shows now.
+   */
+  readonly contains?: string;
+}
+/**
+ * A terminal a whole program runs its screens on, from {@link CliUiTest.session}.
+ *
+ * @public
+ */
+interface CliUiTestSession {
+  /**
+   * Provide it around the program: in-memory terminal streams, the marker-palette `CliTheme`, `CliInteractive`
+   * from the session's options, frame capture, and a `Console` whose writes the session keeps.
+   *
+   * @remarks
+   * Anything the program provides closer to the screens wins: under `CliRuntime.main` with `env`, `CliEnv.layer`
+   * supplies the theme and decides interactivity, as it does for real, and the session keeps only the streams, the
+   * capture and the console.
+   */
+  readonly layer: Layer.Layer<Cli.CliTheme>;
+  /**
+   * Wait for the next screen to mount and draw (and, with `contains`, to show that text), and return it.
+   *
+   * @remarks
+   * Each call takes the next mount in order, counting every mount since the session began, so a screen that mounted
+   * before the call is not missed. It waits at most 2 s, then dies naming the screen's number, the text it waited
+   * for and how many screens had mounted. The returned screen's frames start at its own mount. A screen that crashed
+   * makes `next` die with the crash instead.
+   */
+  readonly next: (options?: CliUiTestNextOptions) => Effect.Effect<CliUiTestScreen>;
+  /**
+   * How many screens have mounted so far: every run that started mounting, one whose thunk threw before Ink drew
+   * included.
+   */
+  readonly mounts: Effect.Effect<number>;
+  /** What the program wrote to stdout through `Console` (`log`, `info`, `debug`), one line per call. */
+  readonly stdout: Effect.Effect<string>;
+  /** What the program wrote to stderr through `Console` (`error`, `warn`, `trace`), one line per call. */
+  readonly stderr: Effect.Effect<string>;
+}
+/**
+ * A live view mounted by {@link CliUiTest.live}: its event stream to publish to, and its output on the production
+ * render path.
+ *
+ * @public
+ */
+interface CliUiTestLive<E, S> {
+  /**
+   * Publish one event to the view's stream, then wait as a key press does: until the view draws its next frame and a
+   * short quiet follows, or 50 ms pass with nothing drawn.
+   */
+  readonly publish: (event: E) => Effect.Effect<void>;
+  /** End the event stream, then wait for the view to finish (`handle.done`): it dies with what the view died of. */
+  readonly end: Effect.Effect<void>;
+  /**
+   * Move the `TestClock` on by `duration`, which fires the view's tick, then wait as `publish` does. The test runs
+   * under `it.effect`, whose clock is a `TestClock`; under `it.live` there is no `TestClock` to move and `advance`
+   * dies, while the view's own tick runs on real time.
+   */
+  readonly advance: (duration: Duration.Input) => Effect.Effect<void>;
+  /** Resize the terminal, then wait as `publish` does. */
+  readonly resize: (columns: number, rows: number) => Effect.Effect<void>;
+  /**
+   * The last frame drawn, as token markup (see {@link CliUiTest.styled}); empty before the first.
+   *
+   * @remarks
+   * Frames are best-effort: each is the write Ink makes after a render, so a render whose output is unchanged, or
+   * empty, adds none, and a frame printed as a string (not interactive, or a degraded run) is not one. `transcript`
+   * and `written` are the authority on what reached the terminal.
+   */
+  readonly frame: Effect.Effect<string>;
+  /** The last frame drawn, as written: with its escape sequences. */
+  readonly rawFrame: Effect.Effect<string>;
+  /** The last frame drawn, as plain text. */
+  readonly plainFrame: Effect.Effect<string>;
+  /**
+   * The frames drawn, across every run, as token markup, oldest first: best-effort, as `frame` says (an unchanged or
+   * empty render adds none, and a printed string is not a frame); `transcript` and `written` are the authority.
+   */
+  readonly frames: Effect.Effect<ReadonlyArray<string>>;
+  /**
+   * What the terminal shows now, scrollback included, as plain text: every committed frame, every line logged above a
+   * frame, every frame printed as a string, and the frame drawn now, with Ink's erases and clears applied (a
+   * scrollback wipe shows as the loss of what was above the frame), each line's trailing spaces trimmed and blank
+   * lines left out. For assertions about what stays on the terminal. With `interactive: false`, the frames printed
+   * as strings show here and in `written`, and nowhere else.
+   */
+  readonly transcript: Effect.Effect<string>;
+  /**
+   * Every byte written to the terminal, escapes included: what to assert a sequence on, such as no `ESC[3J`
+   * (a scrollback wipe) anywhere in a run.
+   */
+  readonly written: Effect.Effect<string>;
+  /** The view's own handle: its `state`, its `logConsole`, `done` and `close`. */
+  readonly handle: LiveHandle<S>;
+}
+/**
+ * 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
+ */
+export declare class CliUiTest {
+  private 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 readonly render: <A>(screen: Screen<A>, options?: CliUiTestOptions) => Effect.Effect<CliUiTestHandle<A>, never, Scope.Scope>;
+  /**
+   * 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 readonly view: (element: ReactElement, options?: CliUiTestOptions) => Effect.Effect<CliUiTestView, never, Scope.Scope>;
+  /**
+   * 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 readonly session: (options?: CliUiTestOptions) => Effect.Effect<CliUiTestSession, never, Scope.Scope>;
+  /**
+   * 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 readonly live: <E, S>(options: Omit<LiveOptions<E, S>, "events"> & CliUiTestOptions) => Effect.Effect<CliUiTestLive<E, S>, never, Scope.Scope>;
+  /**
+   * 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 readonly cancelReason: (exitOrCause: Exit.Exit<unknown, unknown> | Cause.Cause<unknown>) => Option.Option<"escape" | "interrupt">;
+  /**
+   * 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 readonly styled: (ansi: string) => string;
+  /**
+   * 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 readonly serializer: {
+    readonly test: (value: unknown) => boolean;
+    readonly serialize: (value: unknown) => string;
+  };
+}
+//#endregion
+export type { CliUiTestHandle, CliUiTestLive, CliUiTestNextOptions, CliUiTestOptions, CliUiTestScreen, CliUiTestSession, CliUiTestView };
+//# sourceMappingURL=ui-testing.d.ts.map

package/ui-testing.js

@@ -0,0 +1,3 @@
+import { CliUiTest } from "./ui/testing/CliUiTest.js";
+
+export { CliUiTest };