@effected/cli 0.10.0 → 0.12.0

package/ui-testing.d.ts

@@ -0,0 +1,527 @@
+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;
+}
+/**
+ * Options for {@link CliUiTest.session}: the terminal's, and the render path its screens mount on.
+ *
+ * @public
+ */
+interface CliUiTestSessionOptions extends CliUiTestOptions {
+  /**
+   * The path the session's screens render on. `"debug"`, the default, is `render`'s: Ink writes every frame whole and
+   * unthrottled, which is what `next`, `frame` and `frames` read best, and where `clear` does nothing. `"production"`
+   * renders screens as a real terminal does, erase moves and all, so `CliUi.run`'s `clear: true` is observable in
+   * {@link CliUiTestSession.transcript}: the cleared frame is gone from it. A live view mounted in a session always
+   * renders on the production path, whichever this is.
+   */
+  readonly renderPath?: "debug" | "production";
+}
+/**
+ * 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 (`UiStreams`), the marker-palette `CliTheme`,
+   * `CliInteractive` from the session's options, frame capture, and a `Console` whose writes the session keeps. Its
+   * type names `CliTheme` alone because that is the only one of them a program can require: `UiStreams`,
+   * `CliInteractive`, the capture and `Console` are `Context.Reference`s with defaults, which never appear in a
+   * requirement, so a type cannot say that the layer supplies them. Their defaults are the real process streams, a
+   * run that is not interactive, and the real console, so a session provided where it is shadowed fails quietly
+   * rather than by a type error. Hence the ordering below.
+   *
+   * @remarks
+   * **Where you provide it decides what it supplies.** Anything the program provides closer to the screens wins, so:
+   *
+   * - Provided **outside** a layer that supplies the same services, it is shadowed there. Under `CliRuntime.main`
+   *   with `env`, `CliEnv.layer` (provided inside `main`) supplies the theme and decides interactivity, as it does for
+   *   real, and the session keeps only the streams, the capture and the console. That is the intended way to test the
+   *   production wiring.
+   * - To have the session's own theme and `interactive` option win, provide it **inside** any presentation layer of
+   *   your own (closest to the program), or drop that layer from the test.
+   *
+   * The streams, the capture and the console are the session's wherever it is provided, since nothing else in the kit
+   * provides them.
+   */
+  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>;
+  /**
+   * What the terminal shows now, scrollback included, as plain text: what the session's screens and live views wrote to
+   * the terminal streams (`UiStreams`), with Ink's erases and clears applied, each line's trailing spaces trimmed and
+   * blank lines left out, as {@link CliUiTestLive.transcript} reads it.
+   *
+   * @remarks
+   * It holds the lines a live view writes above its frame through `handle.logConsole` (stdout's and stderr's, merged in the order
+   * written, as one terminal shows them; `stdoutWritten` and `stderrWritten` keep them apart), each run's committed frame, a frame printed as a string, and, with
+   * `renderPath: "production"`, each screen's frames as they stay on the terminal, so a screen run with `clear: true`
+   * leaves nothing. On the default debug path each screen frame is written whole, one after another, so the
+   * transcript shows every frame a screen drew rather than what a terminal would keep. What the program writes through
+   * `Console` is not here: that is `stdout` and `stderr`.
+   */
+  readonly transcript: Effect.Effect<string>;
+  /** Every byte written to the terminal streams, both of them in the order written, escapes included. */
+  readonly written: Effect.Effect<string>;
+  /**
+   * Every byte written to the terminal's stdout (`UiStreams.stdout`) alone, escapes included: with
+   * {@link CliUiTestSession.stderrWritten}, what tells a line on the wrong stream from one on the right, which the
+   * merged `transcript` and `written` cannot.
+   */
+  readonly stdoutWritten: Effect.Effect<string>;
+  /** Every byte written to the terminal's stderr (`UiStreams.stderr`) alone, escapes included. */
+  readonly stderrWritten: Effect.Effect<string>;
+  /**
+   * What the terminal's stdout alone shows now, as plain text: {@link CliUiTestSession.stdoutWritten} run through the
+   * same pipeline as {@link CliUiTestSession.transcript} (Ink's erases and clears applied, escapes stripped, trailing
+   * spaces trimmed, blank lines left out).
+   *
+   * @remarks
+   * Assert text per stream here rather than on the raw bytes, which split a painted line wherever the paint breaks
+   * (a counter's `Dry run` from its `0/2 repos`). A frame cleared on the production render path is absent from it
+   * and present in `stdoutWritten`.
+   */
+  readonly stdoutTranscript: Effect.Effect<string>;
+  /** What the terminal's stderr alone shows now, as plain text: {@link CliUiTestSession.stderrWritten} read as `stdoutTranscript` reads stdout. */
+  readonly stderrTranscript: 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` with `session({ renderPath: "production" })` and its `transcript`.
+   * 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.
+   *
+   * By default, as with `render`, a screen run with `clear` leaves its frames unchanged here: Ink renders screens in
+   * debug mode, where its `clear` does nothing. Pass `renderPath: "production"` to render them as a terminal does, and
+   * read `transcript` to see what stays on it: a cleared screen leaves nothing there. A live view a handler mounts
+   * (`CliUi.live`) always renders on the production path, and the lines it writes above its frame through
+   * `handle.logConsole` are in `transcript` and `written`.
+   * 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, whether the run is interactive, and the screens' render path
+   */
+  static readonly session: (options?: CliUiTestSessionOptions) => 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.
+   *
+   * @remarks
+   * Register it in either of two ways. Through the Vitest config, by the module whose default export it is, which
+   * needs no code in a test file:
+   *
+   * ```ts
+   * // vitest.config.ts
+   * export default defineConfig({ test: { snapshotSerializers: ["@effected/cli/ui/testing/serializer"] } })
+   * ```
+   *
+   * Or in a test file, with `expect.addSnapshotSerializer(CliUiTest.serializer)`.
+   *
+   * Snapshots are the one place a test needs `expect`: `assert` has no snapshot form, so a suite that asserts with
+   * `assert.*` everywhere else still writes `expect(frame).toMatchInlineSnapshot(...)` for a snapshot.
+   */
+  static readonly serializer: {
+    readonly test: (value: unknown) => boolean;
+    readonly serialize: (value: unknown) => string;
+  };
+}
+//#endregion
+export type { CliUiTestHandle, CliUiTestLive, CliUiTestNextOptions, CliUiTestOptions, CliUiTestScreen, CliUiTestSession, CliUiTestSessionOptions, CliUiTestView };
+//# sourceMappingURL=ui-testing.d.ts.map

package/ui-testing.js

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