@effected/cli 0.11.0 → 0.13.0

package/ui/testing/CliUiTest.js

@@ -212,12 +212,14 @@ const LEADING_MOVES = /^(?:\u001b\[[0-9;?]*[A-Za-ln-z])+/;
 * 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.
+* `screens` is the render path a screen mounts on; a live view always mounts on the production path. On the debug path
+* Ink writes each frame whole and the capture keeps it as written. On the production path 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. stdout and stderr are two
+* streams, each read alone, and `fake.written` is both in the order written: one terminal, for `written` and the
+* transcript.
 */
-const makeTerminal = (options, mode = "debug") => {
+const makeTerminal = (options, settings = { screens: "debug" }) => {
 	const columns = options.columns ?? 80;
 	const rows = options.rows ?? 24;
 	const color = options.color ?? "truecolor";
@@ -231,7 +233,7 @@ const makeTerminal = (options, mode = "debug") => {
 			lastWrite = Date.now();
 			const current = captures.at(-1);
 			if (!frameDue || current === void 0 || current.ended) return;
-			if (mode === "debug") {
+			if (current.mode === "debug") {
 				frameDue = false;
 				current.raws.push(chunk);
 				return;
@@ -243,10 +245,7 @@ const makeTerminal = (options, mode = "debug") => {
 			current.raws.push(text.replace(LEADING_MOVES, "").replace(/\n+$/, ""));
 		}
 	});
-	const streams = mode === "production" ? {
-		...fake.streams,
-		stderr: fake.streams.stdout
-	} : fake.streams;
+	const streams = fake.streams;
 	const stream = {
 		isTerminal: true,
 		color,
@@ -262,13 +261,16 @@ const makeTerminal = (options, mode = "debug") => {
 		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 } : {},
+		...settings.screens === "debug" ? { debug: true } : {},
+		maxFps: 1e3,
 		onRender: () => {
 			frameDue = true;
 		},
-		onMount: () => {
+		onMount: (kind) => {
+			const mode = kind === "live" ? "production" : settings.screens;
 			captures.push({
 				raws: [],
+				mode,
 				ended: false,
 				crash: void 0
 			});
@@ -482,7 +484,7 @@ var CliUiTest = class {
 	* 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.
+	* 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
@@ -541,8 +543,11 @@ var CliUiTest = class {
 	* 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.
+	* 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.
@@ -574,10 +579,11 @@ var CliUiTest = class {
 	* 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
+	* @param options - the terminal's size, colour and glyphs, whether the run is interactive, and the screens' render path
 	*/
 	static session = (options = {}) => Effect.map(Console.Console, (ambient) => {
-		const terminal = makeTerminal(options);
+		const { renderPath, ...terminalOptions } = options;
+		const terminal = makeTerminal(terminalOptions, { screens: renderPath ?? "debug" });
 		const output = capturingConsole(ambient);
 		let taken = 0;
 		const next = (nextOptions = {}) => Effect.gen(function* () {
@@ -601,7 +607,13 @@ var CliUiTest = class {
 			next,
 			mounts: Effect.sync(() => terminal.captures.length),
 			stdout: Effect.sync(() => output.out.join("")),
-			stderr: Effect.sync(() => output.err.join(""))
+			stderr: Effect.sync(() => output.err.join("")),
+			transcript: Effect.sync(() => screenAfter(terminal.fake.written(), terminal.fake.streams.stdout.rows).join("\n")),
+			written: Effect.sync(() => terminal.fake.written()),
+			stdoutWritten: Effect.sync(() => terminal.fake.stdout()),
+			stderrWritten: Effect.sync(() => terminal.fake.stderr()),
+			stdoutTranscript: Effect.sync(() => screenAfter(terminal.fake.stdout(), terminal.fake.streams.stdout.rows).join("\n")),
+			stderrTranscript: Effect.sync(() => screenAfter(terminal.fake.stderr(), terminal.fake.streams.stdout.rows).join("\n"))
 		};
 	});
 	/**
@@ -659,7 +671,7 @@ var CliUiTest = class {
 			...color === void 0 ? {} : { color },
 			...glyphs === void 0 ? {} : { glyphs },
 			...interactive === void 0 ? {} : { interactive }
-		}, "production");
+		}, { screens: "production" });
 		const queue = yield* Queue.unbounded();
 		const handle = yield* CliUi.live({
 			...view,
@@ -681,8 +693,8 @@ var CliUiTest = class {
 			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()),
+			transcript: Effect.sync(() => screenAfter(terminal.fake.written(), terminal.fake.streams.stdout.rows).join("\n")),
+			written: Effect.sync(() => terminal.fake.written()),
 			handle
 		};
 	});
@@ -723,7 +735,20 @@ var CliUiTest = class {
 	* 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`.
+	*
+	* @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 serializer = {
 		test: (value) => typeof value === "string" && (value.includes("\x1B") || MARKUP.test(value)),

package/ui/testing/fakeStreams.js

@@ -1,11 +1,12 @@
 import { PassThrough, Writable } from "node:stream";
 
 //#region src/ui/testing/fakeStreams.ts
-const capture = (columns, rows, onWrite) => {
+const capture = (columns, rows, both, onWrite) => {
 	const chunks = [];
 	const stream = new Writable({ write(chunk, _encoding, callback) {
 		const text = chunk.toString();
 		chunks.push(text);
+		both.push(text);
 		onWrite?.(text);
 		callback();
 	} });
@@ -44,8 +45,9 @@ const makeFakeStreams = (options = {}) => {
 		ref: () => stdin,
 		unref: () => stdin
 	});
-	const stdout = capture(columns, rows, options.onStdoutWrite);
-	const stderr = capture(columns, rows);
+	const both = [];
+	const stdout = capture(columns, rows, both, options.onStdoutWrite);
+	const stderr = capture(columns, rows, both);
 	return {
 		streams: {
 			stdin,
@@ -55,6 +57,7 @@ const makeFakeStreams = (options = {}) => {
 		rawModes,
 		stdout: stdout.text,
 		stderr: stderr.text,
+		written: () => both.join(""),
 		input: (data) => {
 			stdin.write(data);
 		},

package/ui-testing-serializer.d.ts

@@ -0,0 +1,14 @@
+//#region src/ui-testing-serializer.d.ts
+/**
+ * `CliUiTest.serializer`: it claims a string carrying escapes or token markup and prints it as token markup with each
+ * line's trailing spaces trimmed. See `CliUiTest.serializer` for what it claims.
+ *
+ * @public
+ */
+declare const serializer: {
+  readonly test: (value: unknown) => boolean;
+  readonly serialize: (value: unknown) => string;
+};
+//#endregion
+export { serializer as default };
+//# sourceMappingURL=ui-testing-serializer.d.ts.map

package/ui-testing-serializer.js

@@ -0,0 +1,33 @@
+import { CliUiTest } from "./ui/testing/CliUiTest.js";
+
+//#region src/ui-testing-serializer.ts
+/**
+* `CliUiTest.serializer` as a module's default export, for Vitest's `snapshotSerializers` config.
+*
+* @remarks
+* Vitest's `test.snapshotSerializers` takes module paths whose default export is a serializer, so registering this
+* one needs no `expect.addSnapshotSerializer` call and no shim file of your own:
+*
+* ```ts
+* // vitest.config.ts
+* import { defineConfig } from "vitest/config"
+*
+* export default defineConfig({
+*   test: { snapshotSerializers: ["@effected/cli/ui/testing/serializer"] },
+* })
+* ```
+*
+* A separate entrypoint so a program's runtime import graph never loads test code.
+*
+* @packageDocumentation
+*/
+/**
+* `CliUiTest.serializer`: it claims a string carrying escapes or token markup and prints it as token markup with each
+* line's trailing spaces trimmed. See `CliUiTest.serializer` for what it claims.
+*
+* @public
+*/
+const serializer = CliUiTest.serializer;
+
+//#endregion
+export { serializer as default };

package/ui-testing.d.ts

@@ -32,6 +32,21 @@ interface CliUiTestOptions {
    */
   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.
  *
@@ -134,13 +149,26 @@ interface CliUiTestNextOptions {
  */
 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.
+   * 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
-   * 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.
+   * **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>;
   /**
@@ -162,6 +190,43 @@ interface CliUiTestSession {
   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
@@ -271,7 +336,7 @@ export declare class CliUiTest {
    * 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.
+   * 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
@@ -320,8 +385,11 @@ export declare class CliUiTest {
    * 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.
+   * 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.
@@ -353,9 +421,9 @@ export declare class CliUiTest {
    * 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
+   * @param options - the terminal's size, colour and glyphs, whether the run is interactive, and the screens' render path
    */
-  static readonly session: (options?: CliUiTestOptions) => Effect.Effect<CliUiTestSession, never, Scope.Scope>;
+  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.
@@ -434,7 +502,20 @@ export declare class CliUiTest {
    * 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`.
+   *
+   * @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;
@@ -442,5 +523,5 @@ export declare class CliUiTest {
   };
 }
 //#endregion
-export type { CliUiTestHandle, CliUiTestLive, CliUiTestNextOptions, CliUiTestOptions, CliUiTestScreen, CliUiTestSession, CliUiTestView };
+export type { CliUiTestHandle, CliUiTestLive, CliUiTestNextOptions, CliUiTestOptions, CliUiTestScreen, CliUiTestSession, CliUiTestSessionOptions, CliUiTestView };
 //# sourceMappingURL=ui-testing.d.ts.map

package/ui.d.ts

@@ -39,6 +39,10 @@ interface LiveOptions<E, S> {
    * `useTerminalSize` work in it. When the final frame is printed as a string (not interactive, or a run that degraded
    * before it painted), `useTerminalSize().rows` is `Infinity`, since that frame has no height to fit: a render must
    * not allocate per row.
+   *
+   * To keep the view's module (its JSX, and so React) off every run that never draws it, pass
+   * `CliUi.lazyView(() => import("./view.js"))`: the module is loaded only when a run first mounts or prints its frame
+   * with Ink, so `--help`, a usage error, and, with `final`, a run that is not interactive, never load it.
    */
   readonly render: (state: S, frame: number) => ReactElement;
   /** Whether an event starts a run: by default, the only event that begins one (see `begins`). */
@@ -61,6 +65,28 @@ interface LiveOptions<E, S> {
    * string; hosted writes nothing, its host having its own output.
    */
   readonly mode?: "owned" | "hosted";
+  /**
+   * The final frame of a run that is not interactive (an agent, CI, a pipe, `TERM=dumb`), as a document: given, an
+   * `owned` view prints each run's `final(state)` at the run's end instead of rendering `render` to a string with Ink,
+   * so such a run loads neither Ink nor React, nor a `CliUi.lazyView` module.
+   *
+   * @remarks
+   * It is called once per run, at the run's terminal event (or when the events end mid-run), with the state then, and
+   * replaces the string that run would have printed: never both. It is rendered as `Doc.print` renders a document:
+   * `Render.context("stdout")` when the environment `CliRuntime.main` builds is there (`TerminalEnv`, `Audience` and
+   * `CliLinks`; otherwise the stdout theme, the `Audience` if any, and no width limit), the renderer the audience gets
+   * (`ansi` for a person, `plain` for an agent, `githubLog` under GitHub Actions), and an agent gets no escape. It is
+   * written where the view writes, to `UiStreams` stdout, so a host's capture of the view's output holds it. A document
+   * that renders to nothing prints nothing. A `final` that throws is the run degrading: one warning, nothing printed.
+   *
+   * An interactive run never calls it, and a `hosted` view never prints either way. It need not match the Ink frame:
+   * it is what a reader with no terminal gets.
+   *
+   * With `final` set, `render` is never called on a run that is not interactive, not even to build a string that would
+   * go unused: the run's output is `final(state)` alone. (Pinned by `CliUi.live.final.test.ts`, whose watch-mode test
+   * counts zero `render` calls over three runs.)
+   */
+  readonly final?: ((state: S) => Cli.Document) | undefined;
   /**
    * The frame tick, in milliseconds; 80 by default. While a run is drawn the view redraws on every tick, so a spinner
    * turns without events. Anything but a positive, finite number is a defect.
@@ -343,7 +369,7 @@ export declare class CliUi {
    * what is published before.
    *
    * `live` returns its handle at once, before Ink has loaded: it loads Ink when a run first mounts (or, when not
-   * interactive, when an owned run prints its final frame), and it waits on nothing asynchronous before returning, so
+   * interactive, when an owned run without a `final` prints its final frame), and it waits on nothing asynchronous before returning, so
    * a host outside Effect can take the handle with `Effect.runSync`. The handle works from the start: a `close`
    * before any run has mounted folds what is queued and ends the view as the events ending would, waiting for a mount
    * already under way, and one with no run to end loads nothing.
@@ -387,8 +413,12 @@ export declare class CliUi {
    * When the run is not interactive, nothing is mounted and Ink is loaded only when a string is due. In the `owned`
    * mode (the default) each run's final frame is written once to stdout, as a string laid out at stdout's width (80
    * when it reports none) with no height to fit, at its terminal event or when the stream ends. It is escape-free at
-   * colour `none`, and for an agent audience (`Audience`, when provided) whatever the terminal could do. In the
-   * `hosted` mode nothing is written.
+   * colour `none`, and for an agent audience (`Audience`, when provided) whatever the terminal could do. With a
+   * `final` document, that document is printed instead, once per run, rendered as `Doc.print` renders it, and Ink,
+   * React and a `CliUi.lazyView` module are never loaded: an agent, CI or piped run of a command with a live view pays
+   * for none of them. In the `hosted` mode nothing is written.
+   *
+   * Keep React off the runs that never draw (`--help`, a usage error) with `render: CliUi.lazyView(() => import(...))`.
    *
    * No input is mounted: the view reads no keys and never enters raw mode, so Ctrl-C stays the platform's SIGINT,
    * which interrupts the program and so closes the scope. Each run holds the process-wide mount permit from its
@@ -414,6 +444,10 @@ export declare class CliUi {
    * naming the peers, never a silent `otherwise`. Screens in sequence make a wizard: discover the defaults first,
    * pass each as an `otherwise`, and a non-interactive run returns exactly them.
    *
+   * Without `otherwise`, `NotInteractive` stays in the error type even after the caller checked `CliInteractive`, since
+   * the type cannot know. Catch the tag and fail with `CliError.UserError` to exit as a usage error (`64` under
+   * `CliRuntime.main`).
+   *
    * As with `CliUi.run`, do not log while the screen is mounted: a line written to the terminal from elsewhere tears
    * the frame.
    *
@@ -466,6 +500,79 @@ export declare class CliUi {
   static readonly lazy: <A>(load: () => Promise<{
     readonly default: Screen<A>;
   }>) => Screen<A>;
+  /**
+   * A live view's `render` whose module is loaded only when a run first draws it, so importing the command that uses
+   * the view loads neither the view's own code nor React: `CliUi.lazy` for `CliUi.live`.
+   *
+   * @remarks
+   * `load` resolves to the view, `(state, frame) => ReactElement`, exactly what `render` takes, so the frame index a
+   * spinner needs reaches it: either a module whose default export is the view (`() => import("./view.js")`), or the
+   * view itself (`() => import("./views.js").then((module) => module.syncView)`, for a named export).
+   *
+   * It is optional: `render` still takes the view directly, and needs no dynamic import. A view passed directly
+   * loads with the module that imports it, so it costs React on every run that loads that module; `lazyView` is
+   * how a command keeps React off the runs that never draw. `CliUi.live` loads the module before a run mounts with Ink, or before it
+   * prints a run's final frame as a string; a run that is not interactive and has a `final` document never loads it,
+   * nor Ink, nor React. An import that fails degrades the run, as a render that throws does: one warning, and the next
+   * run tries the import again. A load that resolves to no view (neither a function nor a module whose `default` is
+   * one) is a programming error, and deterministic, so it is kept for the view's life: every run degrades without
+   * loading again, and the view warns once, saying what it received and what is expected, rather than once per run. A
+   * view function that happens to carry a `default` property is the view.
+   *
+   * The returned function is for `CliUi.live`'s `render` alone: called before its module has loaded, it throws.
+   *
+   * Keep the `LiveOptions` (the state, the events and the `lazyView` call) in a module the view does not import. The
+   * view module usually imports the state's types or its fold from somewhere; if that somewhere is the module that
+   * holds the `import("./view.js")`, the dynamic import closes a cycle, which Biome's `noImportCycles` reports even
+   * though it is lazy. A layout that stays acyclic: the model (state, events, fold) in one module, the view importing
+   * the model, and the options (with `lazyView`) in a third that imports the model and loads the view.
+   *
+   * ```ts
+   * // commands/sync.ts: no JSX, no React
+   * const view = yield* CliUi.live({
+   *   events,
+   *   initial,
+   *   reduce,
+   *   render: CliUi.lazyView(() => import("./sync-view.js")),
+   *   final: (state) => [Doc.paragraph(`${state.done} synced`)],
+   *   isStart,
+   *   isTerminal,
+   * })
+   * ```
+   *
+   * @param load - resolves to the view, or to a module whose default export is the view
+   */
+  static readonly lazyView: <S>(load: () => Promise<((state: S, frame: number) => ReactElement) | {
+    readonly default: (state: S, frame: number) => ReactElement;
+  }>) => (state: S, frame: number) => ReactElement;
+  /**
+   * A screen whose answer is `f` of `screen`'s: it mounts `screen` and resolves with `f(value)` when `screen` resolves
+   * with `value`.
+   *
+   * @remarks
+   * Only the resolve is mapped. A cancel passes through unchanged, as the same `Cancelled`, and so does everything
+   * else about the screen: what it draws, its keys, a lazy load. `f` runs when the screen resolves; what it throws is
+   * thrown from the screen's resolve, so it is a defect of the run, as any other throw in a key handler is.
+   *
+   * The mapped screen is a `Screen` like any other, so it goes wherever a screen goes: `CliUi.run`, `CliUi.prompt`,
+   * `CliUi.fallback`, or around a `CliUi.lazy` one. The commonest use is a `Confirm` behind a boolean flag, where the
+   * fallback needs a `Screen<boolean>` and `Confirm` answers a whole `ConfirmResult`:
+   *
+   * ```ts
+   * const yes = Flag.Boolean("yes").pipe(
+   *   Flag.withFallbackPrompt(
+   *     CliUi.fallback(
+   *       CliUi.map(Confirm.screen({ message: "Publish?" }), (result) => result.confirmed),
+   *       { flag: "yes", otherwise: false },
+   *     ),
+   *   ),
+   * )
+   * ```
+   *
+   * @param screen - the screen to show
+   * @param f - turns its answer into the mapped screen's
+   */
+  static readonly map: <A, B>(screen: Screen<A>, f: (value: A) => B) => Screen<B>;
 }
 //#endregion
 //#region src/ui/UiKey.d.ts
@@ -1243,7 +1350,11 @@ export declare class Select {
    * Draw the select: the message, the list (the highlighted row in the accent token with the arrow glyph, disabled
    * rows muted, and at colour `none` ending in ` (disabled)` instead, every row cut to the width with the glyph set's
    * ellipsis), the highlighted choice's detail, and the
-   * key help. Enter calls `onSubmit` with the value; `q` cancels the screen with `"escape"`.
+   * key help.
+   *
+   * @remarks
+   * A choice's `detail` is drawn only while that choice is highlighted, as one muted line under the list, so the others'
+   * details are not on screen until the cursor reaches them. Enter calls `onSubmit` with the value; `q` cancels the screen with `"escape"`.
    *
    * Single-shot: the choices and the starting choice are read once, when the view mounts, and later changes to them
    * are ignored; after a submit it stays as it is. Render a new view (a new screen) to ask again.
@@ -1358,9 +1469,9 @@ interface TextInputState {
   /** The text. */
   readonly value: string;
   /**
-   * The insertion point, from 0 to the value's length, in UTF-16 code units, always on a code-point boundary: an
-   * astral character (an emoji) is never split. Editing is by code point, not by grapheme, so a character built
-   * from several code points (a flag, a family emoji) is still crossed one code point at a time.
+   * The insertion point, from 0 to the value's length, in UTF-16 code units. Left, right, backspace and delete move
+   * and delete by grapheme, so a character built from several code points (an emoji, a flag, a letter with a
+   * combining accent) is crossed and deleted whole, and the cursor never stops inside one it moved over.
    */
   readonly cursor: number;
   /** Whether enter was pressed; the view submits only when the value also validates. */
@@ -1387,8 +1498,30 @@ interface TextInputScreenOptions {
   readonly initial?: string;
   /** Shown, muted, while the value is empty. */
   readonly placeholder?: string;
-  /** Returns a message when the value cannot be submitted, or `undefined` when it can. */
+  /** Returns a message when the value cannot be submitted, or `undefined` when it can; given the real text. */
   readonly validate?: (value: string) => string | undefined;
+  /**
+   * Draw the value masked, so a secret typed or pasted into it is never drawn: one mask per grapheme, so an emoji, a
+   * flag or a letter with a combining accent is one mask, not one per code unit. `true` masks with `•` (`*` under ASCII
+   * glyphs); a string masks with that string, its controls removed. A predicate, `(value) => boolean`, is asked with
+   * the real value and masks with `•` from the first render it answers `true`, and then LATCHES: the value stays masked
+   * through every edit after (deleting a pasted token's first character never redraws the rest in clear) until the
+   * value is cleared to empty. So a field that holds an address (an `op://` reference) stays readable while typed and
+   * hides a value the moment it looks like a token. Match a giveaway ANYWHERE in the value, never as a prefix:
+   * `(value) => /gh[pousr]_|github_pat_/.test(value)` masks `op://v/` followed by a pasted token, which a prefix
+   * match never would. Frames drawn before it first answered `true` showed the text typed so far; a paste arrives
+   * whole, so a pasted token is masked from its first frame. Unmasked by default.
+   *
+   * @remarks
+   * Only the drawing changes: `validate` and the resolved value get the real text, the cursor moves through it as
+   * before, and the placeholder still shows while the value is empty. A masked frame never holds the text, so neither
+   * does the scrollback; erase the frame as well with `clear: true` on the run when even the mask's length should not
+   * stay behind.
+   *
+   * The message `validate` returns is drawn as it is, unmasked: a message that echoes the value (`"ghp_abc is a
+   * token"`) draws the secret in the frame. Say what is wrong without quoting the value.
+   */
+  readonly mask?: string | true | ((value: string) => boolean);
 }
 /**
  * Props of {@link TextInput.View}.
@@ -1435,8 +1568,8 @@ export declare class TextInput {
   static readonly init: (options?: TextInputInitOptions) => TextInputState;
   /**
    * Apply a key: a typed character (any, `q` included) or space is inserted at the cursor; backspace and delete
-   * remove around it; left, right, home and end move it, clamped to the text; enter marks it submitted. Every other
-   * key changes nothing.
+   * remove the grapheme before or after it; left and right move it a grapheme, home and end to either end, clamped
+   * to the text; enter marks it submitted. Every other key changes nothing.
    *
    * @param state - where the input is
    * @param key - the key pressed
@@ -1444,7 +1577,8 @@ export declare class TextInput {
   static readonly step: (state: TextInputState, key: UiKey) => TextInputState;
   /**
    * Draw the input: the message, the value with the cursor shown as `▏` (`|` under ASCII glyphs, so it stays visible
-   * without colour), the placeholder while empty, a validation message in the error token, and the key help. Enter
+   * without colour), or one mask per grapheme in its place with `mask`, the placeholder while empty, a validation
+   * message in the error token, and the key help. Enter
    * submits when `validate` passes; otherwise its message is shown until the next key other than enter, or a paste.
    *
    * @remarks
@@ -1459,7 +1593,15 @@ export declare class TextInput {
   /**
    * A ready-made screen for `CliUi.run`: the input, resolving with the submitted text.
    *
-   * @param options - the message, the starting text, the placeholder and the validator
+   * @remarks
+   * With `mask`, a secret is drawn as one mask per grapheme and never as itself, while the screen still resolves with
+   * the real text:
+   *
+   * ```ts
+   * const token = CliUi.run(TextInput.screen({ message: "Token reference?", mask: true }), { clear: true })
+   * ```
+   *
+   * @param options - the message, the starting text, the placeholder, the validator and the mask
    */
   static readonly screen: (options: TextInputScreenOptions) => Screen<string>;
 }