@effected/cli-kit 0.0.0-stage → 0.27.0

package/ui/CliUi.js

@@ -0,0 +1,509 @@
+import { Cancelled } from "../Cancelled.js";
+import { CliInteractive } from "../CliInteractive.js";
+import { CliTheme } from "../CliTheme.js";
+import { answerWithoutPerson } from "../internal/fallbackAnswer.js";
+import { NotInteractive } from "../NotInteractive.js";
+import { liveDetached } from "./CliUiDetached.js";
+import { live } from "./CliUiLive.js";
+import { routeStream } from "./CliUiRouteStream.js";
+import { errorBoundary } from "./internal/ErrorBoundary.js";
+import { inkModules, loadInk, withInkColour } from "./internal/ink.js";
+import { lazyView } from "./internal/lazyView.js";
+import { mountPermit } from "./internal/mountPermit.js";
+import { UiRenderOptions } from "./internal/renderOptions.js";
+import { useScreenGuard } from "./internal/ScreenContext.js";
+import { treeBase, uiProviders } from "./internal/UiProviders.js";
+import { KeyTable, useKeys } from "./KeyTable.js";
+import { UiStreams } from "./UiStreams.js";
+import { Cause, Deferred, Effect, Exit, Option, Semaphore } from "effect";
+import { Audience } from "@effected/env";
+import { Prompt } from "effect/cli";
+
+// src/ui/CliUi.ts
+/**
+* stdout's theme as the audience sees it: colourless for an agent (as `Render.context` makes it), so a screen's
+* `useTheme`, `Styled` and the widgets' colour-none markers never carry an escape for one. `Audience` is read only when
+* provided, so it stays out of the requirements.
+*/
+const audienceTheme = Effect.gen(function* () {
+	const audience = yield* Effect.serviceOption(Audience);
+	return CliTheme.forAudience((yield* CliTheme).forStream("stdout"), Option.isSome(audience) ? audience.value.kind : void 0);
+});
+/** The root keys: Esc cancels with `"escape"`, Ctrl-C with `"interrupt"`. `q` belongs to widgets, never here. */
+const RootKeys = (props) => {
+	useKeys(KeyTable.root, props.cancel);
+	const guard = useScreenGuard();
+	inkModules().ink.usePaste(guard(() => void 0));
+	return props.children;
+};
+const SCREEN_EXITED = "@effected/cli-kit/ui: the screen exited without resolving or cancelling";
+const mount = (screen, theme, clear, crash) => Effect.gen(function* () {
+	const overrides = yield* UiRenderOptions;
+	const base = yield* treeBase(theme);
+	yield* Effect.acquireRelease(Effect.sync(() => overrides.onMount?.("screen")), (_, exit) => Effect.sync(() => {
+		const died = Exit.isFailure(exit) ? exit.cause.reasons.find(Cause.isDieReason) : void 0;
+		const interrupted = Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause);
+		overrides.onUnmount?.(died !== void 0 ? { defect: died.defect } : interrupted ? void 0 : crash.current);
+	}));
+	const { ink, react } = yield* loadInk;
+	const streams = yield* UiStreams;
+	yield* withInkColour(theme.color);
+	const result = yield* Deferred.make();
+	const control = {
+		resolve: (value) => {
+			Deferred.doneUnsafe(result, Exit.succeed(value));
+		},
+		cancel: (reason) => {
+			Deferred.doneUnsafe(result, Exit.fail(new Cancelled({ reason })));
+		}
+	};
+	const element = yield* Effect.promise(async () => screen(control));
+	const die = (error) => {
+		if (crash.current === void 0) crash.current = { defect: error };
+		Deferred.doneUnsafe(result, Exit.die(error));
+	};
+	const tree = react.createElement(errorBoundary(), {
+		onError: die,
+		children: uiProviders({
+			...base,
+			cancel: control.cancel,
+			die
+		}, react.createElement(RootKeys, {
+			cancel: control.cancel,
+			children: element
+		}))
+	});
+	const instance = yield* Effect.acquireRelease(Effect.sync(() => ink.render(tree, {
+		stdin: streams.stdin,
+		stdout: streams.stdout,
+		stderr: streams.stderr,
+		interactive: true,
+		exitOnCtrlC: false,
+		patchConsole: false,
+		...overrides.debug === true ? { debug: true } : {},
+		...overrides.onRender === void 0 ? {} : { onRender: overrides.onRender },
+		...overrides.maxFps === void 0 ? {} : { maxFps: overrides.maxFps }
+	})), (instance) => Effect.promise(async () => {
+		if (clear) instance.clear();
+		const exited = instance.waitUntilExit();
+		instance.unmount();
+		await exited.catch(() => void 0);
+	}));
+	const exited = Effect.tryPromise({
+		try: () => instance.waitUntilExit(),
+		catch: (cause) => cause
+	}).pipe(Effect.orDie, Effect.flatMap(() => Effect.flatMap(Deferred.isDone(result), (done) => done ? Deferred.await(result) : Effect.die(/* @__PURE__ */ new Error(SCREEN_EXITED)))));
+	return yield* Effect.raceFirst(Deferred.await(result), exited);
+});
+/**
+* Interactive screens drawn with Ink, mounted as scoped resources.
+*
+* @example
+* ```ts
+* import { CliUi, Confirm } from "@effected/cli-kit/ui"
+* import { Effect } from "effect"
+*
+* // Answers `otherwise` when there is no person to ask, and fails with `Cancelled` when they back out.
+* const ask = CliUi.prompt(Confirm.screen({ message: "Overwrite the config?" }), {
+* 	otherwise: { confirmed: false, toggles: {} },
+* })
+* ```
+*
+* @public
+*/
+var CliUi = class CliUi {
+	constructor() {}
+	/**
+	* Mount `screen` and wait for it to resolve or cancel.
+	*
+	* @remarks
+	* When `CliInteractive` is false it fails with `NotInteractive` and mounts nothing; Ink and React are not even
+	* loaded. Otherwise it loads them, holds Ink's colour level at stdout's, and mounts the screen on
+	* `UiStreams` with Ink's own Ctrl-C exit off: Ctrl-C cancels with `"interrupt"` and Esc with `"escape"`.
+	*
+	* Mounting is one scoped resource. However the screen ends (resolved, cancelled, crashed, or the fiber
+	* interrupted), it is unmounted, raw mode and bracketed paste are off, the cursor is shown, and the colour level is
+	* restored. A
+	* component that throws is a defect, never a hang or a typed failure, and nothing of Ink's crash screen reaches
+	* stdout. So is a `useKeys` handler that throws; a handler a consumer registers with Ink's own `useInput` or
+	* `usePaste` is outside the kit, and what it throws escapes as Ink leaves it. A crash wins over an end in the same
+	* tick: a handler that cancels or resolves and then throws, or a component that throws before the screen has
+	* unmounted, is a defect, never the `Cancelled` or the value; a defect raised while the screen unmounts stays beside
+	* that crash in the cause rather than replacing it. An interrupt stays an interrupt, even when the tree reports a
+	* crash as it unmounts.
+	*
+	* A screen draws on stdout (`UiStreams`), and mounts only when `CliInteractive` is true: a human audience, a
+	* terminal on both stdin and stdout, and a `TERM` that is not `dumb`. `CliInteractive` reads `false` until a layer
+	* sets it (`CliRuntime.main`'s `env` does), so a program that never provides one always gets `NotInteractive`.
+	*
+	* Screens run one at a time, process-wide: Ink owns raw mode on the one terminal, so a second `run` waits until the
+	* first is released; so does a `run` while a {@link CliUi.live} view has a run drawn. A screen that itself awaits
+	* another `CliUi.run` therefore deadlocks, and nothing guards against it.
+	*
+	* Do not log while a screen is mounted. Ink redraws its frame by counting the lines it last wrote, and it is
+	* mounted with `patchConsole` off, so a line written to the terminal from elsewhere (an `Effect.log`, `CliLog`, a
+	* background fiber) lands inside the frame and tears it. Log before the screen mounts or after it resolves.
+	*
+	* With `clear` the last frame is erased as the screen unmounts, so a wizard of several screens leaves only what the
+	* program prints; without it the last frame stays, with the highlight where the answer was.
+	*
+	* @param screen - builds the element to mount from its {@link ScreenControl}
+	* @param options - whether to erase the last frame
+	*/
+	static run = (screen, options) => Effect.gen(function* () {
+		if (!(yield* CliInteractive)) return yield* Effect.fail(new NotInteractive());
+		const theme = yield* audienceTheme;
+		const crash = { current: void 0 };
+		const exit = yield* Effect.exit(Semaphore.withPermit(mountPermit, Effect.scoped(mount(screen, theme, options?.clear === true, crash))));
+		const crashed = crash.current;
+		const interrupted = Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause);
+		if (crashed === void 0 || interrupted) return yield* exit;
+		const dies = Exit.isFailure(exit) ? exit.cause.reasons.filter((reason) => Cause.isDieReason(reason) && !(reason.defect instanceof Cancelled)) : [];
+		if (dies.some((reason) => reason.defect === crashed.defect)) return yield* exit;
+		return yield* Effect.failCause(Cause.fromReasons([Cause.makeDieReason(crashed.defect), ...dies]));
+	});
+	/**
+	* The kit's context for an Ink tree the kit did not mount: stdout's theme and glyph set.
+	*
+	* @remarks
+	* Hand it to {@link UiProvider}. It loads Ink and React, as a screen's mount does, so the provider and the kit's
+	* hooks can render; a missing peer is a defect naming both. It is the only way to get a `UiContextValue`.
+	*
+	* Ink loads asynchronously, so this is an `Effect` that must run before the first render. A renderer that is itself
+	* synchronous (a test helper, a report-time `renderToString`) runs it once, with a top-level `await` at module
+	* scope, and then renders synchronously from the value as often as it likes:
+	*
+	* ```ts
+	* const value = await Effect.runPromise(CliUi.context.pipe(Effect.provide(themeLayer)))
+	*
+	* // later, synchronously:
+	* const text = renderToString(createElement(UiProvider, { value: { ...value, size: { columns, rows } } }, tree), {
+	*   columns,
+	* })
+	* ```
+	*/
+	static context = Effect.gen(function* () {
+		const base = yield* treeBase(yield* audienceTheme);
+		yield* loadInk;
+		return {
+			"~@effected/cli-kit/ui/UiContextValue": true,
+			...base
+		};
+	});
+	/**
+	* A live view over a stream: fold `events` into state, and draw it with Ink while a run is going, for the caller's
+	* scope.
+	*
+	* @remarks
+	* `events` is a `PubSub` subscription or a stream, folded in a fiber of the caller's scope. A subscription, made
+	* before the first publish, is the surest: nothing published after it is missed. `live` makes a stream's first pull
+	* before it returns, so one that subscribes on its first pull without forking (`Stream.fromPubSub`) is subscribed by
+	* then; one that forks its upstream (`Stream.merge`, `buffer`, a concurrent `flatMap`) subscribes later, and loses
+	* 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 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.
+	*
+	* End the view with `handle.close`: it stops taking events, folds what is still queued (a subscription's queued
+	* messages included), commits or prints the run as the events ending would, and waits for `done`. Then close the
+	* scope. A publisher may instead end a subscription with `PubSub.end(pubsub, last)`, which keeps everything: the view
+	* folds what is buffered and `last` once, then ends. A `PubSub.shutdown` drops what the view has not taken yet, and
+	* closing the scope by itself stops the fold at once: both lose a run's tail. Closing the scope unmounts whatever is drawn: the terminal is restored (the
+	* cursor shown, Ink's colour level put back) and nothing more is written. `done` completes when the events end.
+	*
+	* A run begins at an `isStart` event (or wherever `begins` says, given the state before and after the event) and ends
+	* at an `isTerminal` event; an event while no run is going that begins none is folded and not drawn, so what a program
+	* reports after a run ends never mounts a second copy of it. A run mounts the view; its end unmounts it, which leaves
+	* its last frame on the terminal, and the next run mounts afresh below it. A start while a run is drawn redraws in
+	* place: the frame is never cleared, so nothing above it is erased. The state is never reset by the kit: a reducer that wants a fresh run
+	* resets it on the start.
+	*
+	* The frame is at most the terminal's rows less one, re-read on every render and on a resize, so a tall frame never
+	* makes Ink wipe the scrollback; its width is Ink's own. The clamp
+	* lags one paint when the terminal gets shorter: Ink re-lays out and repaints the tree it already has on a resize,
+	* before React re-renders with the new row count, so a frame already at the old height can be drawn once taller
+	* than the terminal, which Ink answers by clearing the screen and its scrollback. Only a shrink in height while
+	* the frame is at its full height does it; a frame that keeps a few rows spare never meets it.
+	*
+	* While a run is drawn the view also redraws on a tick of `tickMillis` (80 by default), a schedule in the run's
+	* scope: interrupted with the run or the scope, it never outlives them. Its timer is not unref'd, so while a run is
+	* drawn it keeps the process alive: the run's terminal event, or the scope's close, is what lets the process exit.
+	* The frame index never steps back. Events that arrive at
+	* once, in one chunk or in several the view had not yet caught up with, are folded together and drawn once. The view
+	* takes events from `events` as fast as the stream yields them, so a stream that applies backpressure buffers in the
+	* view while it draws.
+	*
+	* A run whose drawing fails (a `render` that throws, or a mount that fails) degrades rather than ending the view:
+	* it is unmounted, leaving its last good frame on the terminal, then one warning is logged (`Effect.logWarning`),
+	* and the fold goes on. At its terminal event, a run with no frame left on the terminal (it never painted, or its
+	* last good frame threw too) writes its final frame once, as a string. The next run mounts afresh, and so does a
+	* start that comes while a degraded run is going: it ends that run as its terminal event would. A `reduce` that
+	* throws, or an `events` stream that dies, unmounts the run, then `done` dies with the error.
+	*
+	* 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. 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
+	* mount to its end, so a `CliUi.run` during a run waits for the run to end, and one between runs mounts at once.
+	*
+	* While a run is drawn, write logs through `logConsole`, provided around the work the view reports on: its lines
+	* land above the frame. A line written to the terminal any other way tears the frame. A host forwarding output it
+	* did not write itself prints it with `printAbove`, which says whether a frame was mounted to print it above.
+	*
+	* The view draws on stdout (`UiStreams`), at stdout's colour level and glyphs, and mounts only when the run is
+	* interactive (`CliInteractive`).
+	*
+	* @param options - the events, the fold, the drawing, and what starts and ends a run
+	*/
+	static live = live;
+	/**
+	* A live view hosted by code that is not built on Effect: a test runner's reporter, a bundler plugin, a build hook.
+	*
+	* @remarks
+	* It runs `CliUi.live` in a fiber of its own, under `env` and in a scope of its own, and returns at once. A `PubSub`
+	* given as `events` is subscribed before it returns, so the first event published after the call is not lost.
+	* `env` is the environment the view reads, built by the host, which owns the platform: under Node,
+	* `CliEnv.layer().pipe(Layer.provide(NodeServices.layer))`; a test gives `CliEnv.layerTest` with a session's layer.
+	*
+	* End it with `close`, and only then shut the `PubSub` down: `close` folds the subscription's queued tail, commits
+	* the last run and releases the scope, and a shutdown before it drops that tail. `close` never rejects; `exit`
+	* says how the view ended. Forward output the host did not write through `printAbove`, or hand
+	* `CliUi.routeStream` the detached view's `printAbove` as its printer.
+	*
+	* A render that needs an environment service is given as an effect that makes the render function: it runs once
+	* under `env`, before the view is set up, so `CliLinks` or `TerminalEnv` come from the same build the view reads and
+	* the layer is not built a second time to resolve them. `env` must provide what that effect reads.
+	*
+	* Inside an Effect program, use `CliUi.live` in a scope instead.
+	*
+	* @example
+	* ```ts
+	* const view = CliUi.liveDetached(
+	* 	{
+	* 		...options,
+	* 		render: Effect.gen(function* () {
+	* 			const links = yield* CliLinks
+	* 			return (state: State, frame: number) => drawWith(links, state, frame)
+	* 		}),
+	* 	},
+	* 	CliEnv.layer().pipe(Layer.provide(NodeServices.layer)),
+	* )
+	* ```
+	*
+	* @param options - the live view's options, with the events as a `PubSub` or a stream and the render given directly
+	*   or as an effect that makes it
+	* @param env - the environment the view runs under, providing what a render effect reads
+	*/
+	static liveDetached = liveDetached;
+	/**
+	* A stream to hand to a writer in place of a terminal stream, which routes what it writes line by line through
+	* `printer`, usually a live view's `printAbove`, and writes whatever the printer declines to `original`.
+	*
+	* @remarks
+	* For output the program does not write itself: a child process's stderr, or the streams of a test runner or a
+	* bundler running in-process. Each complete line is offered to `printer`; a `false` (no frame mounted) writes it,
+	* with its line break, to `original`. Text without a line break yet is held until one comes, until `flush`, or
+	* until it passes `maxHeld` characters, when it is offered as a line of its own. Bytes are decoded as UTF-8 across
+	* writes, so a character split between two writes arrives whole.
+	*
+	* Everything written to `original` is the decoded text, so a character split across two writes, by whichever path,
+	* arrives once and whole. A write that is nothing but escape sequences (a cursor hide, a clear-screen) goes
+	* straight to `original` when no partial line is held, since there is nothing to print above a frame. Ending
+	* `writable` flushes the held text, so a writer's last line with no line break is printed, not lost. A line's own cursor
+	* movements still tear the frame; `carriageReturn: "last"` keeps only what a progress bar redrawn with `\r` would
+	* have shown.
+	*
+	* The returned `writable` reports the original's `isTTY`, `columns`, `rows`, `getColorDepth`, `hasColors` and
+	* `getWindowSize` where the original has them. A printer that throws fails the write. Node only, as `./ui` is.
+	*
+	* @example
+	* ```ts
+	* const view = CliUi.liveDetached(options, env)
+	* const routed = CliUi.routeStream(process.stderr, view.printAbove, { stream: "stderr" })
+	* runner.errorStream = routed.writable
+	* // ...at the end
+	* routed.flush()
+	* await view.close()
+	* ```
+	*
+	* @param original - the stream the writer would have written to
+	* @param printer - where each line is offered first: `true` when it printed it, `false` with nothing written
+	* @param options - the printer's stream, the hold limit, carriage returns and a text tap
+	* @throws RangeError when `maxHeld` is not a non-negative integer
+	*/
+	static routeStream = routeStream;
+	/**
+	* Run `screen` from a handler when the run is interactive; otherwise answer with `otherwise`, or fail with
+	* `NotInteractive` when there is none.
+	*
+	* @remarks
+	* `CliUi.run` with a default: not interactive, it returns `otherwise` and Ink and React are never loaded.
+	* Interactive, it mounts the screen, and a cancel is the typed `Cancelled` a handler can catch, which
+	* `CliRuntime.main` otherwise renders as one line with exit `130`. A missing Ink in an interactive run is a defect
+	* 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.
+	*
+	* It has two forms. With a real `otherwise` (any value but `undefined`) the error type is `Cancelled` alone, since a
+	* non-interactive run answers and cannot fail. Without one, or with `{ otherwise: undefined }`, which counts as not
+	* given, `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`). `A` is read from the screen, never from `otherwise`.
+	*
+	* As with `CliUi.run`, do not log while the screen is mounted: a line written to the terminal from elsewhere tears
+	* the frame.
+	*
+	* @param screen - the screen to show
+	* @param options - the non-interactive default, and whether to erase the last frame
+	*/
+	static prompt = (screen, options) => CliUi.run(screen, options?.clear === true ? { clear: true } : void 0).pipe(Effect.catchTag("NotInteractive", (error) => {
+		const otherwise = options?.otherwise;
+		return otherwise === void 0 ? Effect.fail(error) : Effect.succeed(otherwise);
+	}));
+	/**
+	* A fallback for `Flag.withFallbackPrompt` or `Argument.withFallbackPrompt` that shows a screen when the run is
+	* interactive: `CliPrompt.fallback` for screens.
+	*
+	* @remarks
+	* Interactive, the screen mounts and its answer is the parameter's value. Not interactive, `otherwise` is used when
+	* given and Ink and React are never loaded; without it the parameter fails as missing, exactly as with no fallback,
+	* so core renders its own message and `CliRuntime.main` exits `64`. Name the parameter with `flag` (the name
+	* without dashes) or `argument` so that error can be built.
+	*
+	* The options are `CliPromptFallbackOptions` (from `@effected/cli-kit`), the same as `CliPrompt.fallback`'s, and `clear`
+	* as for {@link CliUi.run}.
+	*
+	* It runs during parsing, whose environment is core's alone, so it reads `CliTheme` if one is there: with
+	* `CliRuntime.main`'s `env` (`CliEnv.layer`), or provided around the program. With no theme it treats the run as
+	* not interactive, and when `CliInteractive` is on it says so once, at debug level. Interactivity is
+	* `CliInteractive`, which an audience flag can set before parsing under `CliAudience`. Core calls a fallback only
+	* when its `TerminalCapabilities.canPrompt` is `true`; `CliInteractive.layer` and `layerTest` hold it there so that
+	* `otherwise` survives a piped run, and a `canPrompt: false` provided inside the program bypasses this fallback,
+	* as it does `CliPrompt.fallback`.
+	*
+	* As with `CliPrompt.fallback`, the screen runs here rather than being handed to core, whose fallback runner
+	* turns a quit into the missing-parameter error, which would exit `64`. A cancel (Esc, Ctrl-C) is `Cancelled`,
+	* raised as a defect because core's parse step turns every typed failure into a usage error, so only
+	* `CliRuntime.main` (or `CliRuntime.reportFailures`) renders it, as one line with exit `130`. A missing Ink in an
+	* interactive run is a defect naming the peers, never a silent `otherwise`.
+	*
+	* After the screen has unmounted, core still runs the answered `Prompt.succeed` it is handed against the
+	* terminal, exactly as it does for `CliPrompt.fallback`: `Prompt.run` opens the terminal's input in a scope (on
+	* Node a readline over stdin, in raw mode) before looking at the prompt. That is harmless. The prompt is already
+	* answered, so nothing is read and no key is waited for; the scope closes at once, restoring the mode and closing
+	* the reader; and Ink has already let go of stdin, so the two never hold it together. Not interactive, the screen
+	* never mounts, and `CliPrompt.gateTerminal`, which `CliEnv.layer` installs, keeps that subscription off the real
+	* terminal altogether.
+	*
+	* @param screen - the screen to show
+	* @param options - the parameter it stands in for, the non-interactive default, and whether to erase the last frame
+	*/
+	static fallback = (screen, options) => {
+		let explained = false;
+		return Effect.gen(function* () {
+			const theme = yield* Effect.serviceOption(CliTheme);
+			if (Option.isNone(theme)) {
+				if (!explained && (yield* CliInteractive)) {
+					explained = true;
+					const name = "flag" in options ? `--${options.flag}` : `<${options.argument}>`;
+					yield* Effect.logDebug(`@effected/cli-kit/ui: CliUi.fallback for ${name} answered without its screen: CliInteractive is on, but no CliTheme is provided around parsing (CliRuntime.main's env provides one)`);
+				}
+				return yield* answerWithoutPerson(options);
+			}
+			return yield* CliUi.run(screen, options.clear === true ? { clear: true } : void 0).pipe(Effect.provideService(CliTheme, theme.value), Effect.map((answer) => Prompt.succeed(answer)), Effect.catchTag("Cancelled", (cancelled) => Effect.die(cancelled)), Effect.catchTag("NotInteractive", () => answerWithoutPerson(options)));
+		});
+	};
+	/**
+	* A screen whose module is loaded only when it mounts, so importing the command that uses it loads neither the
+	* screen's own code nor React.
+	*
+	* @param load - imports the module whose default export is the screen
+	*/
+	static lazy = (load) => async (control) => (await load()).default(control);
+	/**
+	* 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 lazyView = lazyView;
+	/**
+	* 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 map = (screen, f) => (control) => screen({
+		resolve: (value) => control.resolve(f(value)),
+		cancel: control.cancel
+	});
+};
+
+export { CliUi };

package/ui/CliUiDetached.js

@@ -0,0 +1,36 @@
+import { live } from "./CliUiLive.js";
+import { Deferred, Effect, Exit, Fiber, PubSub, Scope } from "effect";
+
+// src/ui/CliUiDetached.ts
+/** @internal */
+const liveDetached = (options, env) => {
+	const scope = Effect.runSync(Scope.make());
+	const { events: source, render: drawing, ...rest } = options;
+	const render = Effect.isEffect(drawing) ? drawing : Effect.succeed(drawing);
+	const events = PubSub.isPubSub(source) ? Effect.runSync(PubSub.subscribe(source).pipe(Scope.provide(scope))) : source;
+	const mounted = Effect.runSync(Deferred.make());
+	const program = Effect.flatMap(render, (draw) => live({
+		...rest,
+		render: draw,
+		events
+	})).pipe(Effect.tap((handle) => Deferred.succeed(mounted, handle)), Effect.flatMap((handle) => handle.done), Scope.provide(scope), Effect.provide(env), Effect.onExit((exit) => Deferred.done(mounted, Exit.isFailure(exit) ? Exit.failCause(exit.cause) : Exit.die(/* @__PURE__ */ new Error("CliUi.liveDetached: the view ended")))));
+	const fiber = Effect.runFork(program);
+	const exit = Effect.runPromise(Fiber.await(fiber));
+	const handle = Effect.runPromise(Deferred.await(mounted));
+	let closing;
+	let print;
+	handle.then((mountedHandle) => {
+		print = mountedHandle.printAbove;
+	}, () => void 0);
+	return {
+		handle,
+		exit,
+		printAbove: (stream, line) => closing === void 0 && print !== void 0 ? print(stream, line) : false,
+		close: () => {
+			closing ??= Effect.runPromise(Deferred.await(mounted).pipe(Effect.flatMap((mountedHandle) => mountedHandle.close), Effect.exit, Effect.ensuring(Scope.close(scope, Exit.void)), Effect.asVoid));
+			return closing;
+		}
+	};
+};
+
+export { liveDetached };