@effected/cli 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/cli",
-	"version": "0.11.0",
+	"version": "0.13.0",
 	"private": false,
 	"description": "The presentation boundary of an effect/cli program: audience-aware output, a document IR and renderers, editor links, failure reports and logging, plus opt-in Ink screens, widgets and a live view",
 	"keywords": [
@@ -49,13 +49,18 @@
 			"import": "./ui-testing.js",
 			"default": "./ui-testing.js"
 		},
+		"./ui/testing/serializer": {
+			"types": "./ui-testing-serializer.d.ts",
+			"import": "./ui-testing-serializer.js",
+			"default": "./ui-testing-serializer.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
 		"@effected/github-commands": "^0.1.0"
 	},
 	"peerDependencies": {
-		"@effected/config-file": "^0.14.0",
+		"@effected/config-file": "^0.14.2",
 		"@effected/env": "^0.1.0",
 		"@effected/glob": "^0.10.0",
 		"@effected/walker": "^0.15.0",

package/ui/CliUi.js

@@ -1,12 +1,13 @@
 import { Cancelled } from "../Cancelled.js";
 import { CliInteractive } from "../CliInteractive.js";
 import { underGithubActions } from "../internal/autoFormat.js";
-import { CliTheme, themeForAudience } from "../CliTheme.js";
+import { CliTheme } from "../CliTheme.js";
 import { NotInteractive } from "../NotInteractive.js";
 import { answerWithoutPerson } from "../internal/fallbackAnswer.js";
 import { inkModules, loadInk, withInkColour } from "./internal/ink.js";
 import { errorBoundary } from "./internal/ErrorBoundary.js";
 import { UiStreams } from "./UiStreams.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";
@@ -25,7 +26,7 @@ import { Prompt } from "effect/cli";
 */
 const audienceTheme = Effect.gen(function* () {
 	const audience = yield* Effect.serviceOption(Audience);
-	return themeForAudience((yield* CliTheme).forStream("stdout"), Option.isSome(audience) ? audience.value.kind : void 0);
+	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) => {
@@ -37,7 +38,7 @@ const RootKeys = (props) => {
 const SCREEN_EXITED = "@effected/cli/ui: the screen exited without resolving or cancelling";
 const mount = (screen, theme, clear, crash, neutralize) => Effect.gen(function* () {
 	const overrides = yield* UiRenderOptions;
-	yield* Effect.acquireRelease(Effect.sync(() => overrides.onMount?.()), (_, exit) => Effect.sync(() => {
+	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);
@@ -80,7 +81,8 @@ const mount = (screen, theme, clear, crash, neutralize) => Effect.gen(function*
 		exitOnCtrlC: false,
 		patchConsole: false,
 		...overrides.debug === true ? { debug: true } : {},
-		...overrides.onRender === void 0 ? {} : { onRender: overrides.onRender }
+		...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();
@@ -204,7 +206,7 @@ var CliUi = 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.
@@ -248,8 +250,12 @@ var CliUi = 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
@@ -275,6 +281,10 @@ var CliUi = 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.
 	*
@@ -342,6 +352,80 @@ var CliUi = class CliUi {
 	* @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
+	});
 };
 
 //#endregion

package/ui/CliUiLive.js

@@ -1,18 +1,21 @@
 import { CliInteractive } from "../CliInteractive.js";
-import { underGithubActions } from "../internal/autoFormat.js";
-import { CliTheme, themeForAudience } from "../CliTheme.js";
+import { autoFormat, underGithubActions } from "../internal/autoFormat.js";
+import { CliLinks } from "../CliLinks.js";
+import { CliTheme } from "../CliTheme.js";
+import { Render } from "../Render.js";
 import { fromReact, inkModules, loadInk, withInkColour } from "./internal/ink.js";
 import { errorBoundary } from "./internal/ErrorBoundary.js";
 import { holder, holderSlot } from "./internal/Holder.js";
 import { UiStreams } from "./UiStreams.js";
 import { makeInkConsole } from "./internal/inkConsole.js";
+import { LazyViewShapeError, loadView } from "./internal/lazyView.js";
 import { mountPermit } from "./internal/mountPermit.js";
 import { drainPerformance, resolveDrain } from "./internal/perfDrain.js";
 import { UiRenderOptions } from "./internal/renderOptions.js";
 import { uiProviders } from "./internal/UiProviders.js";
 import { useTerminalSize } from "./UiTheme.js";
 import { Cause, Clock, Duration, Effect, Exit, Fiber, Option, PubSub, Pull, Queue, Schedule, Scheduler, Scope, Stream } from "effect";
-import { Audience } from "@effected/env";
+import { Audience, TerminalEnv } from "@effected/env";
 import { CommandNeutralizer } from "@effected/github-commands";
 
 //#region src/ui/CliUiLive.ts
@@ -48,7 +51,8 @@ const live = (options) => Effect.gen(function* () {
 	const begins = options.begins ?? ((event) => options.isStart(event));
 	if (!(Number.isFinite(tickMillis) && tickMillis > 0)) return yield* Effect.die(new Error(TICK_INVALID(tickMillis)));
 	const audience = yield* Effect.serviceOption(Audience);
-	const theme = themeForAudience((yield* CliTheme).forStream("stdout"), Option.isSome(audience) ? audience.value.kind : void 0);
+	const cliTheme = yield* CliTheme;
+	const theme = CliTheme.forAudience(cliTheme.forStream("stdout"), Option.isSome(audience) ? audience.value.kind : void 0);
 	const colour = theme.color;
 	const neutralize = yield* underGithubActions;
 	const provided = {
@@ -90,11 +94,25 @@ const live = (options) => Effect.gen(function* () {
 		run = void 0;
 		return current === void 0 ? Effect.succeed(void 0) : Effect.as(unmount(current), current);
 	}));
+	/**
+	* A lazy view's shape errors already warned about. A shape error is deterministic, and the lazy view keeps one
+	* error object for it, so a long watch session warns once for it, not once per run; any other failure is a fresh
+	* object, and warns each time.
+	*/
+	const shapesWarned = /* @__PURE__ */ new Set();
+	/** The degraded-run warning, unless it is a shape error this view has already warned about. */
+	const warning = (error) => {
+		if (error instanceof LazyViewShapeError) {
+			if (shapesWarned.has(error)) return Effect.void;
+			shapesWarned.add(error);
+		}
+		return Effect.logWarning(DEGRADED(error));
+	};
 	/** Stop drawing a run: unmount first, so the one warning never lands inside a frame, then warn. */
 	const degrade = (current, error) => Effect.suspend(() => {
 		if (current.degraded) return unmount(current);
 		current.degraded = true;
-		return Effect.andThen(unmount(current), Effect.logWarning(DEGRADED(error)));
+		return Effect.andThen(unmount(current), warning(error));
 	});
 	/** Act on a failure the boundary reported for the run mounted now, if any. */
 	const checkFailure = Effect.suspend(() => {
@@ -102,8 +120,16 @@ const live = (options) => Effect.gen(function* () {
 		const failed = current?.failed;
 		return current === void 0 || failed === void 0 ? Effect.void : degrade(current, failed.error);
 	});
+	/** Say once that a run stopped drawing: already said for a degraded run, and said here for one that never mounted. */
+	const warnOnce = (current, error) => Effect.suspend(() => {
+		if (current.degraded) return Effect.void;
+		current.degraded = true;
+		return warning(error);
+	});
 	/** The final frame as a string, at the stdout width (80 when it reports none) and with no height to fit. */
 	const printFrame = (current) => Effect.gen(function* () {
+		const viewLoaded = yield* Effect.exit(loadView(options.render));
+		if (Exit.isFailure(viewLoaded)) return yield* warnOnce(current, Cause.squash(viewLoaded.cause));
 		const { ink, react } = yield* loadInk;
 		const frame = yield* frameOf;
 		const reported = streams.stdout.columns;
@@ -123,15 +149,32 @@ const live = (options) => Effect.gen(function* () {
 		});
 		const text = yield* Effect.scoped(Effect.andThen(withInkColour(colour), Effect.sync(() => ink.renderToString(tree, { columns }))));
 		drainPerformance(drain);
-		if (failure !== void 0) {
-			if (!current.degraded) {
-				current.degraded = true;
-				yield* Effect.logWarning(DEGRADED(failure.error));
-			}
-			return;
-		}
+		if (failure !== void 0) return yield* warnOnce(current, failure.error);
 		bridge.print(neutralize ? CommandNeutralizer.text(text) : text);
 	});
+	/** The context `final`'s document is rendered with: `Doc.print`'s when the environment is there. */
+	const finalContext = Effect.gen(function* () {
+		const terminal = yield* Effect.serviceOption(TerminalEnv);
+		const links = yield* Effect.serviceOption(CliLinks);
+		if (Option.isSome(terminal) && Option.isSome(links) && Option.isSome(audience)) return yield* Render.context("stdout").pipe(Effect.provideService(CliTheme, cliTheme), Effect.provideService(TerminalEnv, terminal.value), Effect.provideService(CliLinks, links.value), Effect.provideService(Audience, audience.value));
+		return Render.contextOf({
+			audience: Option.isSome(audience) ? audience.value.kind : "human",
+			color: theme.color,
+			glyphs: theme.glyphs,
+			...neutralize ? { neutralizeWorkflowCommands: true } : {}
+		});
+	});
+	/** A run's `final` document, printed as `Doc.print` would, to the view's stdout; never Ink. */
+	const printFinal = (current, final) => Effect.gen(function* () {
+		const built = yield* Effect.exit(Effect.try({
+			try: () => final(state),
+			catch: (error) => error
+		}));
+		if (Exit.isFailure(built)) return yield* warnOnce(current, Cause.squash(built.cause));
+		const ctx = yield* finalContext;
+		const text = Render[yield* autoFormat(ctx.audience)](built.value, ctx);
+		if (text !== "") bridge.print(text);
+	});
 	/** Mount a run's view with the current state, its tick beside it; a failure degrades the run. */
 	const mount = (current) => Effect.gen(function* () {
 		const scope = yield* Scope.make("sequential");
@@ -149,8 +192,9 @@ const live = (options) => Effect.gen(function* () {
 		};
 		yield* Effect.gen(function* () {
 			yield* Effect.acquireRelease(mountPermit.take(1), () => mountPermit.release(1), { interruptible: true });
-			yield* Effect.acquireRelease(Effect.sync(() => overrides.onMount?.()), () => Effect.sync(() => overrides.onUnmount?.(void 0)));
+			yield* Effect.acquireRelease(Effect.sync(() => overrides.onMount?.("live")), () => Effect.sync(() => overrides.onUnmount?.(void 0)));
 			const { ink, react } = yield* loadInk;
+			yield* Effect.orDie(loadView(options.render));
 			yield* withInkColour(colour);
 			const frame = yield* frameOf;
 			const initial = elementOf(state, frame);
@@ -183,8 +227,8 @@ const live = (options) => Effect.gen(function* () {
 					interactive: true,
 					exitOnCtrlC: false,
 					patchConsole: false,
-					...overrides.debug === true ? { debug: true } : {},
-					...overrides.onRender === void 0 ? {} : { onRender: overrides.onRender }
+					...overrides.onRender === void 0 ? {} : { onRender: overrides.onRender },
+					...overrides.maxFps === void 0 ? {} : { maxFps: overrides.maxFps }
 				});
 				drainPerformance(drain);
 				return instance;
@@ -242,7 +286,10 @@ const live = (options) => Effect.gen(function* () {
 	/** End the run: unmount, which commits its frame; a degraded run that never painted prints its frame instead. */
 	const endRun = Effect.flatMap(takeRun, (current) => {
 		if (current === void 0) return Effect.void;
-		if (!interactive) return options.mode === "hosted" ? Effect.void : printFrame(current);
+		if (!interactive) {
+			if (options.mode === "hosted") return Effect.void;
+			return options.final === void 0 ? printFrame(current) : printFinal(current, options.final);
+		}
 		return Effect.suspend(() => {
 			const failed = current.failed;
 			const warned = failed === void 0 || current.degraded ? Effect.void : Effect.suspend(() => {

package/ui/Select.js

@@ -160,7 +160,11 @@ var Select = 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.

package/ui/TextInput.js

@@ -16,12 +16,24 @@ const init = (options = {}) => {
 		submitted: false
 	};
 };
-const isHigh = (code) => code >= 55296 && code <= 56319;
-const isLow = (code) => code >= 56320 && code <= 57343;
-/** The code-point boundary before `at`: one code unit back, two when that would land inside a surrogate pair. */
-const previous = (value, at) => at >= 2 && isLow(value.charCodeAt(at - 1)) && isHigh(value.charCodeAt(at - 2)) ? at - 2 : Math.max(0, at - 1);
-/** The code-point boundary after `at`. */
-const following = (value, at) => at + 1 < value.length && isHigh(value.charCodeAt(at)) && isLow(value.charCodeAt(at + 1)) ? at + 2 : Math.min(value.length, at + 1);
+const segmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
+/** The grapheme boundary before `at`: the start of the grapheme `at` is in or just after; 0 at the start. */
+const previous = (value, at) => {
+	let boundary = 0;
+	for (const { index } of segmenter.segment(value)) {
+		if (index >= at) break;
+		boundary = index;
+	}
+	return boundary;
+};
+/** The grapheme boundary after `at`: the end of the grapheme that starts at or contains `at`; the length at the end. */
+const following = (value, at) => {
+	for (const { index, segment } of segmenter.segment(value)) {
+		const end = index + segment.length;
+		if (end > at) return end;
+	}
+	return value.length;
+};
 const insert = (state, text) => ({
 	value: state.value.slice(0, state.cursor) + text + state.value.slice(state.cursor),
 	cursor: state.cursor + text.length,
@@ -137,6 +149,19 @@ const windowAround = (before, after, width, ellipsis) => {
 	const room = Math.max(0, width - Fmt.width(shownBefore));
 	return [shownBefore, Fmt.width(after) <= room ? after : room > mark ? `${head(after, room - mark)}${ellipsis}` : head(after, room)];
 };
+/**
+* The value masked either side of the cursor, one `mask` per grapheme of the whole value: the graphemes that start
+* before the cursor, then the rest, so the two always add up to the value's graphemes, wherever the cursor is.
+*/
+const maskedAround = (value, cursor, mask) => {
+	let before = 0;
+	let total = 0;
+	for (const { index } of segmenter.segment(value)) {
+		total++;
+		if (index < cursor) before++;
+	}
+	return [mask.repeat(before), mask.repeat(total - before)];
+};
 /** Shown in the help line only; the input reads every key itself. */
 const HELP = KeyTable.make([{
 	keys: ["enter"],
@@ -179,8 +204,8 @@ var TextInput = class TextInput {
 	static init = init;
 	/**
 	* 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
@@ -188,7 +213,8 @@ var TextInput = class TextInput {
 	static step = step;
 	/**
 	* 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
@@ -232,13 +258,27 @@ var TextInput = class TextInput {
 			for (const pressed of keys) setState((current) => step(current, pressed));
 		}));
 		const cursorGlyph = glyphs.kind === "unicode" ? "▏" : "|";
-		const [before, after] = windowAround(state.value.slice(0, state.cursor), state.value.slice(state.cursor), columns - Fmt.width(cursorGlyph), glyphs.ellipsis);
+		const latched = react.useRef(false);
+		if (state.value === "") latched.current = false;
+		else if (typeof props.mask === "function" && !latched.current && props.mask(state.value)) latched.current = true;
+		const masking = typeof props.mask === "function" ? latched.current : props.mask;
+		const mask = masking === void 0 || masking === false ? void 0 : masking === true ? glyphs.kind === "unicode" ? "•" : "*" : lineText(masking);
+		const [shownBefore, shownAfter] = mask === void 0 ? [state.value.slice(0, state.cursor), state.value.slice(state.cursor)] : maskedAround(state.value, state.cursor, mask);
+		const [before, after] = windowAround(shownBefore, shownAfter, columns - Fmt.width(cursorGlyph), glyphs.ellipsis);
 		return react.createElement(ink.Box, { flexDirection: "column" }, react.createElement(Styled, { token: "emphasis" }, Fmt.truncate(lineText(props.message), columns, { ellipsis: glyphs.ellipsis })), react.createElement(ink.Text, null, before, cursorGlyph, after, state.value === "" && props.placeholder !== void 0 ? react.createElement(Styled, { token: "muted" }, Fmt.truncate(lineText(props.placeholder), Math.max(0, columns - Fmt.width(cursorGlyph)), { ellipsis: glyphs.ellipsis })) : null), error === void 0 ? null : react.createElement(Styled, { token: "error" }, Fmt.truncate(lineText(error), columns, { ellipsis: glyphs.ellipsis })), react.createElement(KeyHelp, { tables: [HELP] }));
 	};
 	/**
 	* 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 screen = (options) => (control) => inkModules().react.createElement(TextInput.View, {
 		...options,

package/ui/internal/lazyView.js

@@ -0,0 +1,74 @@
+import { Effect } from "effect";
+
+//#region src/ui/internal/lazyView.ts
+/** Where a lazy view keeps its loader: a `Symbol.for` key, so two copies of the package agree on it. */
+const LOAD = Symbol.for("@effected/cli/ui/lazyView");
+const NOT_LOADED = "@effected/cli/ui: a CliUi.lazyView render was called before its module loaded; only CliUi.live loads it first";
+const kindOf = (value) => value === null ? "null" : Array.isArray(value) ? "an array" : typeof value === "object" ? "an object" : typeof value;
+const EXPECTED = "a view, (state, frame) => ReactElement, or a module whose default export is one: { default: view }";
+/** What a `load` resolved to that is no view: said with what was received and what is expected. */
+const NO_VIEW = (resolved) => {
+	if (typeof resolved !== "object" || resolved === null) return `@effected/cli/ui: CliUi.lazyView's load resolved to ${kindOf(resolved)}. Expected ${EXPECTED}`;
+	const named = Object.keys(resolved).filter((key) => key !== "default");
+	const exports = named.length === 0 ? "" : ` (it exports ${named.join(", ")})`;
+	return `@effected/cli/ui: CliUi.lazyView's load resolved to ${Object.hasOwn(resolved, "default") ? `a module whose default export is ${kindOf(resolved.default)}, not a function${exports}; a CommonJS module imported as ESM nests it one level deeper, as default.default` : `a module with no default export${exports}; resolve to the export itself, as .then((module) => module.name)`}. Expected ${EXPECTED}`;
+};
+/**
+* A load that resolved to no view: deterministic, so a lazy view keeps it (one error object for the handle's life) and
+* the live view warns about it once, where a failed import is tried again by the next run.
+*
+* @internal
+*/
+var LazyViewShapeError = class extends Error {};
+/** The view `load` resolved to: the value itself when it is a function (a `default` property on it is ignored), else
+* its `default` when that is a function; anything else throws, saying what it got. */
+const pick = (resolved) => {
+	if (typeof resolved === "function") return resolved;
+	if (typeof resolved === "object" && resolved !== null) {
+		const fallback = resolved.default;
+		if (typeof fallback === "function") return fallback;
+	}
+	throw new LazyViewShapeError(NO_VIEW(resolved));
+};
+/**
+* `CliUi.lazyView`: a `render` that draws with what `load` resolves to, loaded on first use: the render itself, or a
+* module whose default export it is. One load is shared: an import that rejected is cleared, so the next run loads
+* again; a load that resolved to no view is kept, a `LazyViewShapeError` every later run gets as is. Calling the render
+* before it has loaded is a defect, since only `CliUi.live` knows to load it first.
+*
+* @internal
+*/
+const lazyView = (load) => {
+	let loaded;
+	let pending;
+	const ensure = () => {
+		pending ??= load().then((resolved) => {
+			loaded = pick(resolved);
+		}, (error) => {
+			pending = void 0;
+			throw error;
+		});
+		return pending;
+	};
+	const render = (state, frame) => {
+		if (loaded === void 0) throw new Error(NOT_LOADED);
+		return loaded(state, frame);
+	};
+	return Object.assign(render, { [LOAD]: ensure });
+};
+/**
+* Load a lazy view's module before its render is first called; nothing for a render that is not lazy. Fails with what
+* the import failed with.
+*
+* @internal
+*/
+const loadView = (render) => {
+	const ensure = render[LOAD];
+	return ensure === void 0 ? Effect.void : Effect.asVoid(Effect.tryPromise({
+		try: ensure,
+		catch: (error) => error
+	}));
+};
+
+//#endregion
+export { LazyViewShapeError, lazyView, loadView };