@effected/cli-kit 0.0.0-stage → 0.27.0

package/ui.d.ts

@@ -0,0 +1,2013 @@
+import * as Cli from "@effected/cli-kit";
+import { Console, Context, Effect, Exit, Layer, Option, PubSub, Scope, Stream } from "effect";
+import { Param } from "effect/cli";
+import { ReactElement, ReactNode } from "react";
+import { Writable } from "node:stream";
+import { Key } from "ink";
+import { ColorLevel } from "@effected/env";
+/**
+ * Options for `CliUi.live`.
+ *
+ * @public
+ */
+interface LiveOptions<E, S> {
+  /**
+   * The events to fold: a `PubSub` subscription, or a stream.
+   *
+   * A subscription (`PubSub.subscribe`, made before the first publish) is the surest: the view takes from it directly,
+   * so nothing published after the subscribe is missed, and `LiveHandle.close` folds every message still queued in it
+   * before the view ends. A publisher can also end it from its side, and the two ends differ:
+   *
+   * - `PubSub.end(pubsub, last)` keeps everything: the view folds what is buffered, then `last` once (core repeats a
+   *   final message to every later take; the view takes it once), then ends. Make `last` an `isTerminal` event to
+   *   commit the run with it; otherwise the run is committed as drawn.
+   * - `PubSub.shutdown` drops what the view has not taken yet. End with `close` (or `PubSub.end`) first.
+   *
+   * A stream: `live` makes its first pull before it returns, so one that subscribes on its first pull without forking
+   * (`Stream.fromPubSub`) is subscribed by then and sees an event published at once. One that forks its upstream
+   * (`Stream.merge`, `buffer`, a concurrent `flatMap`) subscribes later, and an event published before that is lost.
+   * `close` folds what the view has already pulled; what the stream holds and has not yielded is the stream's.
+   */
+  readonly events: Stream.Stream<E> | PubSub.Subscription<E>;
+  /** The state before the first event. */
+  readonly initial: S;
+  /** Fold one event into the state. The kit never resets the state: a reducer that wants a fresh run resets it. */
+  readonly reduce: (state: S, event: E) => S;
+  /**
+   * Draw the state. `frame` is the wall clock in ticks of `tickMillis` (`floor(now / tickMillis)`, from `Clock`), so a
+   * spinner keeps turning across runs. Rendered inside the kit's providers: `useTheme`, `useGlyphs`, `Styled` and
+   * `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`). */
+  readonly isStart: (event: E) => boolean;
+  /**
+   * Whether an event begins a run while none is going, given the state before and after it is folded; `isStart` by
+   * default, so only a start begins one. Given, it replaces that default rather than adding to it, so keep `isStart`
+   * in it to begin on a start as well as on something else, such as a stream that a program joins mid-run:
+   * `(event, before, after) => isStart(event) || (before.phase === "idle" && after.phase !== "idle")`.
+   * An event that begins nothing while no run is going is folded and not drawn. A start while a run is going redraws
+   * that run in place, and this is not asked then; a start while a degraded run is going ends that run and begins a
+   * fresh one.
+   */
+  readonly begins?: (event: E, before: S, after: S) => boolean;
+  /** Whether an event ends a run: its frame is committed to the terminal and the view unmounts until the next. */
+  readonly isTerminal: (event: E) => boolean;
+  /**
+   * `"owned"` (the default) for a view that owns its output, `"hosted"` for one drawn inside a host's (a test
+   * reporter). They differ only when the run is not interactive: owned writes each run's final frame once, as a
+   * 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.
+   */
+  readonly tickMillis?: number;
+}
+/**
+ * The handle of a live view.
+ *
+ * @public
+ */
+interface LiveHandle<S> {
+  /** The current state of the fold. */
+  readonly state: Effect.Effect<S>;
+  /**
+   * A `Console` whose every method writes above the frame while a run is mounted, and straight to the stream otherwise;
+   * none falls through to the program's own console. Output is split as Node's console splits it: `log`, `info`,
+   * `debug`, `dir`, `dirxml`, `table`, `count`, `timeLog`, `timeEnd` and a group's label to stdout, and `error`,
+   * `warn`, `trace` and a failed `assert` to stderr; a group indents what follows. An `Error` argument is written with
+   * its stack. `clear` does nothing, since erasing the screen would take the scrollback above the frame. Provide it
+   * around the work done while the view is mounted; a line written to the terminal any other way tears the frame.
+   *
+   * `Console.Console` is the seam: the kit's logger (`CliLogger`, `CliLog`) and `Effect.log*` write through whatever
+   * `Console` the fiber has, so they need no reference to the view. A host whose logging lives outside the view's
+   * owner provides the handle's console at the top of the program it runs, and every log line under it lands above
+   * the frame: `Effect.provideService(program, Console.Console, handle.logConsole)`. Output that never goes through
+   * Effect's `Console` (another library's own `process.stderr` writes) still tears the frame.
+   */
+  readonly logConsole: Console.Console;
+  /**
+   * Print one line above the frame if a run's frame is mounted now, and say whether it did: `true` when `line` and a
+   * line break went through Ink's writer for `stream`, above the frame, and `false`, having written nothing, when no
+   * frame is mounted.
+   *
+   * @remarks
+   * For a host that forwards output it did not write itself (a child process's stderr, a test runner's captured
+   * streams) and must know where it went. `logConsole` answers the same question silently, writing to `UiStreams`
+   * when no frame is mounted; `printAbove` leaves that case to the caller, who may have somewhere better to send the
+   * line, or may already be writing to the stream it would land on.
+   *
+   * A frame is mounted only during an interactive run: from the run's mount until just before its unmount. Between
+   * runs, before the first, after `close`, in a degraded run, and always when the view is not interactive (an agent,
+   * CI, a pipe, `TERM=dumb`, which never mounts), it returns `false`. The check and the write are one synchronous step,
+   * so the answer is never stale: a separate "is a frame mounted" query could be answered by one run and acted on in
+   * the gap before the next. Synchronous, like `logConsole`, so a Node stream's `write` callback can call it.
+   *
+   * `true` means Ink's writer accepted the line, not that it reached the terminal: while a render has handed the
+   * terminal to a child process (`useApp().suspendTerminal`), Ink drops what its writers are handed, and so does
+   * `logConsole`.
+   *
+   * The line is written as given: no formatting, no group indent, and no sanitising. A line break inside `line` is
+   * kept, and each of its lines lands above the frame. A cursor movement inside it (a `\r`, a cursor-up, an erase
+   * line, as a child's own progress bar writes) moves the cursor Ink repaints the frame from, and tears the frame.
+   *
+   * @param stream - the stream the line belongs on: Ink's stdout writer or its stderr writer
+   * @param line - the text to print, without a trailing line break
+   * @returns `true` if Ink's writer above a mounted frame took the line; `false`, with nothing written, otherwise
+   */
+  readonly printAbove: (stream: "stdout" | "stderr", line: string) => boolean;
+  /**
+   * Completes once the events have ended (the stream ended, the subscription's `PubSub` was ended with `PubSub.end` or
+   * shut down, or `close` ended them) and the last run's frame is committed. Dies with what the view died of: a `reduce` that threw, or a
+   * stream that died.
+   */
+  readonly done: Effect.Effect<void>;
+  /**
+   * End the view cleanly, then wait for `done`.
+   *
+   * @remarks
+   * It stops taking events, folds what the view holds and has not folded yet, and ends the run as the events ending
+   * does: an `isTerminal` event among them commits its run as usual, and a run with no terminal event is committed as
+   * drawn (owned and not interactive: its final frame is printed once). With a subscription, that includes every
+   * message still queued in it, so a run's tail published just before the close is never lost, as it would be to a
+   * `PubSub.shutdown`. With a stream, it is what the view has already pulled; elements the stream holds and has not
+   * yielded are the stream's own.
+   *
+   * Safe from the moment `live` returns, before Ink has loaded: a run whose mount is still under way is mounted and
+   * then ended, and a view with no run to end loads nothing.
+   *
+   * Idempotent: a second `close`, concurrent or later, waits for the same end and writes nothing more. After the events
+   * have ended it only waits for `done`. It dies as `done` does (a `reduce` that threw, a stream that died). Closing
+   * the caller's scope instead of calling `close` stops the view at once (nothing still queued is folded); closing it
+   * after `close` releases what is left. A `close` after the scope has closed completes at once, there being nothing
+   * left to end, where `done` is interrupted. A host ends its view with:
+   *
+   * ```ts
+   * handle.close.pipe(Effect.ensuring(Scope.close(scope, Exit.void)))
+   * ```
+   */
+  readonly close: Effect.Effect<void>;
+}
+/**
+ * Options for `CliUi.liveDetached`: those of `CliUi.live`, with the events given as a `PubSub` or a stream, and the
+ * render given directly or as an effect that makes it.
+ *
+ * @typeParam R - the services a `render` effect reads, which the `env` layer provides
+ *
+ * @public
+ */
+interface DetachedLiveOptions<E, S, R = never> extends Omit<LiveOptions<E, S>, "events" | "render"> {
+  /**
+   * The events to fold. A `PubSub` is subscribed before `liveDetached` returns, in the view's own scope, so an event
+   * published right after the call is seen and `close` folds every message still queued. A stream is read as
+   * `CliUi.live` reads one.
+   */
+  readonly events: PubSub.PubSub<E> | Stream.Stream<E>;
+  /**
+   * Draw the state, as `CliUi.live`'s `render`; or an effect that makes that function, run once under `env` before
+   * the view is set up, so a render that needs an environment service (`CliLinks` to build links, `TerminalEnv` for
+   * the terminal's capabilities) reads it from the layer the view already builds rather than from a second build.
+   *
+   * @remarks
+   * A render effect that dies is the view's setup failing: `handle` rejects, `close` resolves, and `exit` carries
+   * the die, as for an `env` layer that dies. It can return a `CliUi.lazyView`.
+   */
+  readonly render: LiveOptions<E, S>["render"] | Effect.Effect<LiveOptions<E, S>["render"], never, R>;
+}
+/**
+ * A live view running outside Effect, from `CliUi.liveDetached`.
+ *
+ * @public
+ */
+interface DetachedLive<S> {
+  /**
+   * The view's handle once `CliUi.live` has set it up (it loads Ink asynchronously). Rejects if the view could not be
+   * set up; the rejection is handled, so a host that never awaits it sees no unhandled rejection.
+   */
+  readonly handle: Promise<LiveHandle<S>>;
+  /**
+   * The handle's `printAbove`: print one line above the frame and say whether it did. `false`, with nothing written,
+   * before the handle is set up, whenever no run's frame is mounted, and from the moment `close` is called, so the
+   * host writes the line itself.
+   */
+  readonly printAbove: (stream: "stdout" | "stderr", line: string) => boolean;
+  /**
+   * End the view and release it.
+   *
+   * @remarks
+   * In order: `printAbove` stops printing; the view's setup is awaited (one that died counts as settled); the
+   * handle's `close` folds every message still queued in the subscription and commits the last run; then the view's
+   * scope is closed, which unsubscribes and unmounts. Shut the `PubSub` down only after the returned promise
+   * resolves: a `PubSub.shutdown` before it drops the events the view has not taken yet.
+   *
+   * Idempotent: every call returns the same promise. It never rejects; how the view ended is `exit`.
+   */
+  readonly close: () => Promise<void>;
+  /**
+   * How the view ended: a success when its events ended or `close` ended them, the failure it died of (a `reduce`
+   * that threw, a stream that died, a setup that failed), or an interrupt when its scope closed under it.
+   */
+  readonly exit: Promise<Exit.Exit<void>>;
+}
+/**
+ * Options for `CliUi.routeStream`.
+ *
+ * @public
+ */
+interface RouteStreamOptions {
+  /** Which of the printer's streams the lines belong on. */
+  readonly stream: "stdout" | "stderr";
+  /**
+   * The most characters held back waiting for a line break; 8192 by default. Past it, the held text is offered as a
+   * line of its own, so a writer that never ends a line cannot grow the buffer without bound.
+   */
+  readonly maxHeld?: number | undefined;
+  /**
+   * What a line holding a carriage return is printed as: `keep` (the default) prints it as written, and `last` prints
+   * only the text after its last `\r`, which is what a terminal would have shown of a progress bar redrawn in place.
+   * A CRLF line ending is a line ending either way. A line written to the original stream is always written as it came.
+   */
+  readonly carriageReturn?: "keep" | "last" | undefined;
+  /**
+   * Called with every piece of text written, decoded, before it is routed: a tap for a recorder.
+   *
+   * @remarks
+   * Every write reaches it, a write of nothing but escape sequences (a cursor hide, a clear-screen) included, though
+   * such a write is never offered to the printer. A write holding only the first bytes of a character reaches it when
+   * the character completes, or as U+FFFD at `flush`.
+   */
+  readonly onText?: ((text: string) => void) | undefined;
+}
+/**
+ * A stream routed line by line through a printer, from `CliUi.routeStream`.
+ *
+ * @public
+ */
+interface RoutedStream {
+  /**
+   * The stream to hand to the writer in place of the original. It reports the original's `isTTY`, `columns`, `rows`,
+   * `getColorDepth`, `hasColors` and `getWindowSize`, where the original has them, so a library that sizes its output
+   * to the terminal still sees one.
+   */
+  readonly writable: Writable;
+  /**
+   * Turn routing on (the default) or off. Turned off, the text held waiting for a line break is written to the
+   * original, and every later write goes straight to it, decoded, until routing is turned back on.
+   */
+  readonly route: (on: boolean) => void;
+  /**
+   * Offer the text held waiting for a line break to the printer now, or write it to the original if it declines.
+   * It ends the decoding too: a character split across writes whose second half has not arrived is written as
+   * U+FFFD. Ending `writable` (`end()`) flushes the same way, so a last line with no line break is never lost.
+   */
+  readonly flush: () => void;
+}
+/**
+ * What the kit's hooks read in a tree the kit did not mount: the theme, the glyph set, and optionally the size.
+ *
+ * @remarks
+ * Only `CliUi.context` mints one, because only it also loads the Ink and React the provider renders with. A value
+ * without the brand does not compile, which stops one being built by accident; the brand is a plain key, so a
+ * literal that spells it out compiles, and must never be written. Spread a minted value to change its fields
+ * (`{ ...value, size }`).
+ *
+ * @public
+ */
+interface UiContextValue {
+  /** Set by `CliUi.context` alone; never set it yourself. */
+  readonly "~@effected/cli-kit/ui/UiContextValue": true;
+  /** The theme of the stream the tree draws on. */
+  readonly theme: Cli.StreamTheme;
+  /** The glyph set in use. */
+  readonly glyphs: Cli.GlyphSet;
+  /** The terminal size the tree is laid out at, which `useTerminalSize` reads in place of the stdout's. */
+  readonly size?: {
+    readonly columns: number;
+    readonly rows: number;
+  };
+  /**
+   * How a `DocView` under it shows an absolute path: `CliUi.context` sets it from the run's `displayPath`
+   * (`CliEnvOptions.displayPath`), so a frame shows a path as `Doc.print` and a live view's `final` do. Absent, a
+   * nested provider keeps the one above it, and with none the path is shown as given.
+   */
+  readonly displayPath?: ((absolute: string) => string) | undefined;
+  /**
+   * Whether the GitHub Actions runner reads the output (`CliUi.context` sets it from `CurrentRuntimeEnv`, when one is
+   * provided): a `DocView` under it neutralizes any line its data would turn into a workflow command. `false` opts the
+   * tree out of that under GitHub Actions, the consumer's choice; a nested provider cannot clear it once a provider
+   * above it has set it.
+   */
+  readonly neutralizeWorkflowCommands?: boolean;
+}
+/**
+ * Props of {@link UiProvider}.
+ *
+ * @public
+ */
+interface UiProviderProps {
+  /** The context, from `CliUi.context`. */
+  readonly value: UiContextValue;
+  /** The tree. */
+  readonly children?: ReactNode;
+}
+/**
+ * Provide the kit's context to an Ink tree the kit did not mount, so `useTheme`, `useGlyphs`, `Styled` and
+ * `useTerminalSize` work in it.
+ *
+ * @remarks
+ * Take the value from `CliUi.context`, which also loads Ink and React: the provider and the kit's hooks render with
+ * the modules the kit loaded. A screen mounted by `CliUi.run` already has this context.
+ *
+ * With `size`, `useTerminalSize` reads it instead of the stdout Ink draws on, less one column and one row as ever.
+ * Give it to Ink's `renderToString`, whose terminal hooks see the process's own stdout rather than the width it lays
+ * out at: `renderToString(tree, { columns })` with `size: { columns, rows }` keeps the kit's widgets cut to that
+ * width. A tree given a `size` no longer follows the terminal's resizes.
+ *
+ * Standalone, there is no screen to end: a kit widget's own quit key, such as `Select`'s `q`, does nothing, and an
+ * input handler a kit widget registers is called as is, so what it throws escapes as Ink leaves it. Nested inside a `CliUi.run` screen, it overrides only the theme, the glyphs and the size: the screen's
+ * cancel and its defect route pass through, so `q` still cancels and a throwing handler is still the screen's defect.
+ * Ink's colour level is the host's: `Styled` passes the theme's props, none at colour `none`.
+ *
+ * @param props - the context, and the tree
+ *
+ * @public
+ */
+export declare const UiProvider: (props: UiProviderProps) => ReactElement;
+/**
+ * How a screen ends: with a result, or cancelled for a reason.
+ *
+ * @remarks
+ * Only the first call counts. Resolving with an empty value (`[]`, `""`) is a result, not a cancel.
+ *
+ * @public
+ */
+interface ScreenControl<A> {
+  /** End the screen with `value`. */
+  readonly resolve: (value: A) => void;
+  /** End the screen as cancelled: `"escape"` for Esc or a widget's quit key, `"interrupt"` for Ctrl-C. */
+  readonly cancel: (reason: "escape" | "interrupt") => void;
+}
+/**
+ * A screen: given its control, the React element to mount, or a promise of one.
+ *
+ * @remarks
+ * The kit's widgets sanitise the text they draw from data; a screen's own components (Ink's `Text`, `Styled`) draw
+ * what they are given, so text from data in them is the screen author's to pass through `Fmt.sanitize` first.
+ *
+ * @public
+ */
+type Screen<A> = (control: ScreenControl<A>) => ReactElement | Promise<ReactElement>;
+/**
+ * Options for {@link CliUi.run}.
+ *
+ * @public
+ */
+interface CliUiRunOptions {
+  /**
+   * Erase the screen's last frame as it unmounts, however it ended; `false` by default, which leaves the last frame
+   * on the terminal, as a record of the answer.
+   */
+  readonly clear?: boolean;
+}
+/**
+ * Options for {@link CliUi.prompt}.
+ *
+ * @public
+ */
+interface CliUiPromptOptions<A> {
+  /** The value to use when the run is not interactive. Without it a non-interactive run fails with `NotInteractive`. */
+  readonly otherwise?: A;
+  /** Erase the screen's last frame as it unmounts; `false` by default. See {@link CliUiRunOptions.clear}. */
+  readonly clear?: boolean;
+}
+/**
+ * Options for {@link CliUi.fallback}: `CliPrompt.fallback`'s, and whether the screen erases its last frame.
+ *
+ * @public
+ */
+type CliUiFallbackOptions<A> = Cli.CliPromptFallbackOptions<A> & {
+  /** Erase the screen's last frame as it unmounts; `false` by default. See {@link CliUiRunOptions.clear}. */
+  readonly clear?: boolean;
+};
+/**
+ * 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
+ */
+export declare class CliUi {
+  private 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 readonly run: <A>(screen: Screen<A>, options?: CliUiRunOptions) => Effect.Effect<A, Cli.Cancelled | Cli.NotInteractive, Cli.CliTheme>;
+  /**
+   * 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 readonly context: Effect.Effect<UiContextValue, never, Cli.CliTheme>;
+  /**
+   * 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 readonly live: <E, S>(options: LiveOptions<E, S>) => Effect.Effect<LiveHandle<S>, never, Scope.Scope | Cli.CliTheme>;
+  /**
+   * 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 readonly liveDetached: <E, S, R = never>(options: DetachedLiveOptions<E, S, R>, env: Layer.Layer<Cli.CliTheme | NoInfer<R>>) => DetachedLive<S>;
+  /**
+   * 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 readonly routeStream: (original: NodeJS.WritableStream, printer: (stream: "stdout" | "stderr", line: string) => boolean, options: RouteStreamOptions) => RoutedStream;
+  /**
+   * 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 readonly prompt: {
+    <A>(screen: Screen<A>, options: CliUiPromptOptions<A> & {
+      readonly otherwise: Exclude<A, undefined>;
+    }): Effect.Effect<A, Cli.Cancelled, Cli.CliTheme>;
+    <A>(screen: Screen<A>, options?: CliUiPromptOptions<A>): Effect.Effect<A, Cli.Cancelled | Cli.NotInteractive, Cli.CliTheme>;
+  };
+  /**
+   * 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 readonly fallback: <A>(screen: Screen<A>, options: CliUiFallbackOptions<A>) => Param.FallbackPrompt<A>;
+  /**
+   * 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 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>;
+}
+/**
+ * The named keys a screen understands and a test can press.
+ *
+ * @remarks
+ * Letters, digits and punctuation are not named: they arrive as typed text.
+ *
+ * @public
+ */
+type KeyName = "up" | "down" | "left" | "right" | "enter" | "space" | "tab" | "shift+tab" | "backspace" | "delete" | "escape" | "ctrl+c" | "home" | "end" | "pageup" | "pagedown";
+/**
+ * A key as a screen sees it: a named key, or typed text.
+ *
+ * @remarks
+ * Space is always `Named("space")`, never `Char(" ")`, so a key table binds it once. A `Char` is what Ink delivers
+ * as one input, so a paste arrives as one `Char` holding the pasted text.
+ *
+ * @public
+ */
+export type UiKey = {
+  readonly _tag: "Named";
+  readonly name: KeyName;
+} | {
+  readonly _tag: "Char";
+  readonly char: string;
+};
+/**
+ * Normalising Ink's input into {@link (UiKey:type)}s.
+ *
+ * @remarks
+ * A typed `const` rather than the house static-class form by force, not by
+ * choice: a class cannot share its name with the {@link (UiKey:type)} union
+ * (TS2300, duplicate identifier), and that union is the key model itself.
+ *
+ * @public
+ */
+export declare const UiKey: {
+  /**
+   * The key Ink reported to a `useInput` handler, or `undefined` for one the kit does not name: a Ctrl or Meta
+   * combination other than Ctrl-C, or an input holding a control character.
+   */
+  readonly fromInk: (input: string, key: Key) => UiKey | undefined;
+  /** A named key. */
+  readonly named: (name: KeyName) => UiKey;
+  /** Typed text. */
+  readonly char: (char: string) => UiKey;
+};
+/**
+ * One row of a {@link KeyTable}: the keys that trigger an action, and the help line that names it.
+ *
+ * @public
+ */
+interface Binding<Action> {
+  /** The keys, named or typed (`{ char: "q" }`); any of them triggers the action. */
+  readonly keys: ReadonlyArray<KeyName | {
+    readonly char: string;
+  }>;
+  /** What the keys do. */
+  readonly action: Action;
+  /** The words `KeyHelp` shows beside the keys. */
+  readonly help: string;
+  /** Bound but left out of the help line. */
+  readonly hidden?: boolean;
+}
+/**
+ * One entry of a key table's help: the key labels and what they do.
+ *
+ * @public
+ */
+interface KeyHelpRow {
+  /** The keys, labelled for the glyph set and joined with `/`. */
+  readonly label: string;
+  /** What they do. */
+  readonly help: string;
+}
+/**
+ * Options for {@link useKeys}.
+ *
+ * @public
+ */
+interface UseKeysOptions {
+  /** Whether the keys are read; `true` by default. */
+  readonly isActive?: boolean;
+}
+/**
+ * The keys a widget understands, as data: the one source both for dispatching input and for the help line, so the
+ * two cannot drift apart.
+ *
+ * @remarks
+ * Read it with {@link useKeys}, whose handler must step from current state, never render-closure state: several keys
+ * from one stdin read are dispatched before React re-renders.
+ *
+ * @public
+ */
+export declare class KeyTable<Action> {
+  /** The bindings, in priority order. */
+  readonly bindings: ReadonlyArray<Binding<Action>>;
+  private constructor();
+  /**
+   * A table from its bindings. When two bindings share a key, the first wins. A `{ char: " " }` key is stored as
+   * the named `"space"`, the only form in which Ink reports a space.
+   *
+   * @param bindings - the bindings, in priority order
+   */
+  static readonly make: <Action_1>(bindings: ReadonlyArray<Binding<Action_1>>) => KeyTable<Action_1>;
+  /**
+   * The keys every screen has: Esc cancels with `"escape"` (help: cancel), and Ctrl-C cancels with `"interrupt"`,
+   * bound but hidden. `q` is never a root key: it belongs to a widget's own table, so a text input can type it.
+   */
+  static readonly root: KeyTable<"escape" | "interrupt">;
+  /**
+   * The action of the first binding that holds `key`, or `None`.
+   *
+   * @param key - the key pressed
+   */
+  readonly match: (key: UiKey) => Option.Option<Action>;
+  /**
+   * The help rows of every binding not hidden that can still fire, in order, labelled for `glyphs`: `↑/↓` under
+   * Unicode, `up/down` under ASCII.
+   *
+   * @remarks
+   * A key an earlier binding already holds (hidden or not) can never fire a later one, so a later binding is
+   * labelled with its remaining keys only, and left out when none remain.
+   *
+   * @param glyphs - the glyph set the labels are drawn with
+   */
+  readonly help: (glyphs: Cli.GlyphSet) => ReadonlyArray<KeyHelpRow>;
+}
+/**
+ * Read the keys of `table` and dispatch the action each one matches; keys the table does not bind are ignored.
+ *
+ * @remarks
+ * One Ink `useInput` per call, and nothing else reads input.
+ *
+ * Text read in one go (`"yy"`, `"y\r"`) reaches Ink's `useInput` as one string; it is split here into a key per
+ * grapheme (a decomposed letter or a ZWJ emoji is one key), a line break (CR, LF or CR LF) as one enter, a tab as tab, a
+ * space as space, so `{ char: "y" }` matches each `y`. A `{ char }` binding matches in NFC, whichever form was typed.
+ * A bracketed paste never reaches it: the screen takes pastes on Ink's paste channel, so pasted text cannot press a
+ * widget's keys (a pasted `q` does not cancel); `TextInput` reads pastes as text.
+ *
+ * Several keys from one stdin read (a fast typist, a held arrow, a terminal that batches) are each dispatched
+ * before React re-renders, so `dispatch` must never step from state captured in the render that created it: the
+ * second key would see the first key's starting point and repeat its move. Step with a functional update
+ * (`setState((current) => step(current, action))`), a `useReducer` dispatch, or a ref the handler itself advances.
+ *
+ * Inside a screen mounted by `CliUi.run`, a `dispatch` that throws ends the screen as a defect carrying the error, as a
+ * component that throws in render does; it never escapes as an uncaught exception.
+ *
+ * @param table - the keys to read
+ * @param dispatch - receives each matched action
+ * @param options - whether the keys are read
+ *
+ * @public
+ */
+export declare const useKeys: <Action>(table: KeyTable<Action>, dispatch: (action: Action) => void, options?: UseKeysOptions) => void;
+/**
+ * An extra on/off row a {@link Confirm} hosts beneath its yes/no answer.
+ *
+ * @public
+ */
+interface ConfirmToggle<K extends string> {
+  /** Names the toggle in the result. */
+  readonly key: K;
+  /** What the row shows. */
+  readonly label: string;
+  /** Whether it starts on. */
+  readonly value: boolean;
+}
+/**
+ * What a {@link Confirm} resolves with: the answer, and every toggle by key.
+ *
+ * @public
+ */
+interface ConfirmResult<K extends string> {
+  /** Yes or no. */
+  readonly confirmed: boolean;
+  /**
+   * Each toggle's final value, by its key. Partial, because a toggle passed conditionally may be absent: read one
+   * with a fallback, `toggles.promote ?? false`.
+   */
+  readonly toggles: Readonly<Partial<Record<K, boolean>>>;
+}
+/**
+ * Where a {@link Confirm} is.
+ *
+ * @public
+ */
+interface ConfirmState<K extends string> {
+  /** The answer. */
+  readonly confirmed: boolean;
+  /** The highlighted row: 0 is the yes/no row, each toggle follows. */
+  readonly row: number;
+  /** The toggles and their current values. */
+  readonly toggles: ReadonlyArray<ConfirmToggle<K>>;
+  /** Whether enter was pressed. */
+  readonly submitted: boolean;
+}
+/**
+ * What a key does in a {@link Confirm}.
+ *
+ * @public
+ */
+type ConfirmAction = "up" | "down" | "toggle" | "yes" | "no" | "flip" | "submit" | "cancel";
+/**
+ * Options for {@link Confirm.init}.
+ *
+ * @public
+ */
+interface ConfirmInitOptions<K extends string> {
+  /** The starting answer; no (`false`) by default. */
+  readonly initial?: boolean;
+  /** Extra on/off rows, with unique keys. */
+  readonly toggles?: ReadonlyArray<ConfirmToggle<K>>;
+}
+/**
+ * Options for {@link Confirm.screen}.
+ *
+ * @public
+ */
+interface ConfirmScreenOptions<K extends string> extends ConfirmInitOptions<K> {
+  /** The question. */
+  readonly message: string;
+}
+/**
+ * Props of {@link Confirm.View}.
+ *
+ * @public
+ */
+interface ConfirmViewProps<K extends string> extends ConfirmScreenOptions<K> {
+  /** Receives the answer and the toggles when enter is pressed. */
+  readonly onSubmit: (result: ConfirmResult<K>) => void;
+}
+/**
+ * A yes/no question, optionally with extra on/off rows beneath it: a pure reducer, its key table, a view and a
+ * ready-made screen.
+ *
+ * @remarks
+ * The rows are the yes/no row first, then each toggle. `y` and `n` set the answer and `←`/`→` flip it, from any
+ * row; `↑`/`↓` move between rows; space flips the highlighted toggle and does nothing on the yes/no row; enter
+ * submits; `q` cancels with `"escape"`. Toggle keys must be unique; `init` throws, and `screen` dies, on a repeat.
+ * With no toggles, the help line leaves out the row and toggle keys. Toggles that do not fit the terminal scroll
+ * in a window under the answer row, so the question, the answer and the help line stay on screen.
+ * The answer starts as no unless `initial` says otherwise, and `←`/`→` flip it whichever row is highlighted.
+ *
+ * A toggle passed conditionally is absent from the result when it was left out, so read it back with a fallback:
+ *
+ * ```ts
+ * import { CliUi, Confirm } from "@effected/cli-kit/ui"
+ * import { Effect } from "effect"
+ *
+ * const publish = (drafts: number) =>
+ *   Effect.gen(function* () {
+ *     const { confirmed, toggles } = yield* CliUi.run(
+ *       Confirm.screen({
+ *         message: "Publish the release?",
+ *         toggles: drafts > 0 ? [{ key: "promote", label: `promote ${drafts} drafts to stable`, value: true }] : [],
+ *       }),
+ *     )
+ *     const promote = toggles.promote ?? false
+ *     return { confirmed, promote }
+ *   })
+ * ```
+ *
+ * @public
+ */
+export declare class Confirm {
+  private constructor();
+  /**
+   * A confirm with its answer (no by default) and toggles, on the yes/no row.
+   *
+   * @param options - the starting answer and the toggles
+   */
+  static readonly init: <K extends string>(options?: ConfirmInitOptions<K>) => ConfirmState<K>;
+  /**
+   * Apply an action (see the class remarks for what each key does).
+   *
+   * @param state - where the confirm is
+   * @param action - the action
+   */
+  static readonly step: <K extends string>(state: ConfirmState<K>, action: ConfirmAction) => ConfirmState<K>;
+  /**
+   * The answer and every toggle's value by key.
+   *
+   * @param state - where the confirm is
+   */
+  static readonly result: <K extends string>(state: ConfirmState<K>) => ConfirmResult<K>;
+  /** The keys: y yes, n no, ←/→ flip, ↑/↓ row, space toggle, enter submit, q cancel (the view hides row and toggle from its help when there are no toggles). */
+  static readonly keys: KeyTable<ConfirmAction>;
+  /**
+   * Draw the confirm: the question, the answer row (`[Yes]  No` or ` Yes  [No]`, the chosen answer in brackets so it
+   * shows without colour, and in the accent token), a {@link Toggle} row per toggle, and the key help.
+   *
+   * @remarks
+   * Single-shot, like `Select.View`: the options are read once at mount.
+   *
+   * @param props - the question, the starting answer, the toggles and where the result goes
+   */
+  static readonly View: <K extends string>(props: ConfirmViewProps<K>) => ReactElement;
+  /**
+   * A ready-made screen for `CliUi.run`: the confirm, resolving with the answer and the toggles.
+   *
+   * @param options - the question, the starting answer and the toggles
+   */
+  static readonly screen: <K extends string>(options: ConfirmScreenOptions<K>) => Screen<ConfirmResult<K>>;
+}
+/**
+ * Props of {@link DocView}.
+ *
+ * @public
+ */
+interface DocViewProps {
+  /** The document, or one block of it, which is drawn as a one-block document. */
+  readonly doc: Cli.Document | Cli.Block;
+  /**
+   * The render context. Omitted, it is built from the tree's theme (`useTheme`): its colour, its `paint` (token
+   * overrides included) and its glyphs, the width `useTerminalSize().columns`, a human audience, links off, the
+   * run's `displayPath` (the identity outside `CliRuntime.main`'s `env`), and `neutralizeWorkflowCommands` when the tree is under the GitHub Actions runner. Given,
+   * it replaces that context entirely, neutralizing included (set `neutralizeWorkflowCommands` on it when the runner
+   * reads the output), and the view needs no provider.
+   */
+  readonly ctx?: Cli.RenderContext;
+}
+/**
+ * The kit's document IR (`Doc`) drawn as Ink rows, laid out by the kit's own renderers, so a live view and a static
+ * report show a document the same way.
+ *
+ * @remarks
+ * The document is rendered with `Render.ansi` (`Render.plain` at colour `none`) at the width, and each line becomes
+ * one Ink `Text` row cut with `wrap: "truncate-end"`, so Ink never re-wraps what the renderer laid out. Everything the
+ * static renderers do holds: a collapsible is drawn open, an annotation is skipped, text from data is sanitised.
+ *
+ * Without a `ctx` the view takes its theme from the tree (a screen, a live view, or a `UiProvider`) and its width from
+ * `useTerminalSize`, so it follows a resize; for an agent the theme is colourless, so the view is escape-free. Links
+ * are off. The layout is memoised on the document's identity and the context: re-render with the same document, as a
+ * live view's tick does, and the renderer does not run again; build a new document only when it changes.
+ *
+ * @param props - the document, and optionally the render context
+ *
+ * @public
+ */
+export declare const DocView: (props: DocViewProps) => ReactElement;
+/**
+ * Props of {@link KeyHelp}.
+ *
+ * @public
+ */
+interface KeyHelpProps {
+  /** The tables to describe, in order. */
+  readonly tables: ReadonlyArray<KeyTable<unknown>>;
+  /** Whether to end with the root keys (`esc cancel`); `true` by default. */
+  readonly root?: boolean;
+}
+/**
+ * A one-line footer naming every visible binding of the given tables, then the root keys:
+ * `↑/↓ move · space toggle · enter continue · esc cancel`.
+ *
+ * @remarks
+ * Drawn from the same tables that dispatch the keys, so the help cannot name a key the screen ignores. Neighbouring
+ * rows with the same help share one entry (`↑/↓ move`). It stays one line, cut to the terminal width with the glyph
+ * set's ellipsis; when it must be cut, the widget's own keys give way and the root hint (`esc cancel`) stays whole at
+ * the end. Painted with the `muted` token; labels follow the screen's glyph set.
+ *
+ * @param props - the tables, and whether to append the root keys
+ *
+ * @public
+ */
+export declare const KeyHelp: (props: KeyHelpProps) => ReactElement;
+/**
+ * Where a viewport is: the selected item, the first item in view, how many items fit, and how many there are.
+ *
+ * @remarks
+ * Every number counts items, never section headers. The reducer keeps `0 <= cursor < count` (or both 0 when there
+ * are no items) and `offset <= cursor < offset + height`, and never lets the window run past the last item.
+ *
+ * @public
+ */
+interface ViewportState {
+  /** The selected item. */
+  readonly cursor: number;
+  /** The first item in view. */
+  readonly offset: number;
+  /** How many items the window holds. */
+  readonly height: number;
+  /** How many items there are. */
+  readonly count: number;
+}
+/**
+ * A row a viewport shows: a section header, or an item. Only items are selectable. An item's `key` is its React
+ * key in the view, so keys must be unique within one list: `Viewport.View` dies on a repeat.
+ *
+ * @public
+ */
+type ViewportRow = {
+  readonly _tag: "Header";
+  readonly label: string;
+} | {
+  readonly _tag: "Item";
+  readonly key: string;
+};
+/**
+ * A move through a viewport.
+ *
+ * @public
+ */
+type ViewportMove = "up" | "down" | "home" | "end" | "pageup" | "pagedown";
+/**
+ * Props of {@link Viewport.View}.
+ *
+ * @public
+ */
+interface ViewportViewProps {
+  /** The rows, headers and items, in order; the items are what `state` counts. */
+  readonly rows: ReadonlyArray<ViewportRow>;
+  /** Where the viewport is. */
+  readonly state: ViewportState;
+  /** Draws one row; `highlighted` is true for the selected item. Each row is clipped to one line. */
+  readonly renderRow: (row: ViewportRow, highlighted: boolean) => ReactElement;
+  /** Lines the rest of the screen uses (a title, a help line), taken off the terminal height; 0 by default. */
+  readonly reserved?: number;
+}
+/**
+ * A scrolling list: a pure reducer over a window of items, its key table, and a view that draws the window.
+ *
+ * @remarks
+ * The view never draws more lines than fit: its height is `min(state.height, terminal rows - 1 - reserved)`, and
+ * every row is clipped to one line of `columns - 1` cells, so a frame never fills the terminal and Ink never clears
+ * the screen and scrollback to redraw it. A section header stays visible: when the header of the first visible item
+ * has scrolled off, it is drawn again atop the slice.
+ *
+ * @public
+ */
+export declare class Viewport {
+  private constructor();
+  /**
+   * A viewport over `count` items, `height` of them in view, with `cursor` selected (clamped; 0 by default).
+   *
+   * @param count - how many items
+   * @param height - how many fit (at least 1)
+   * @param cursor - the item to select
+   */
+  static readonly init: (count: number, height: number, cursor?: number) => ViewportState;
+  /**
+   * Move the cursor, clamped at both ends with no wrap, keeping it in view. A page is the window height.
+   *
+   * @param state - where the viewport is
+   * @param move - the move
+   */
+  static readonly step: (state: ViewportState, move: ViewportMove) => ViewportState;
+  /**
+   * Change the window height, keeping the cursor where it is and in view.
+   *
+   * @param state - where the viewport is
+   * @param height - the new height (at least 1)
+   */
+  static readonly resize: (state: ViewportState, height: number) => ViewportState;
+  /** The keys: ↑/↓ move, pgup/pgdn page, home top, end bottom. */
+  static readonly keys: KeyTable<ViewportMove>;
+  /**
+   * Draw the window: the visible rows, each clipped to one line. A repeated item key is a defect: the view throws, so
+   * the screen dies with the reason.
+   *
+   * @param props - the rows, the state, how to draw a row, and the lines reserved for the rest of the screen
+   */
+  static readonly View: (props: ViewportViewProps) => ReactElement;
+}
+/**
+ * One item of a {@link MultiSelect} section.
+ *
+ * @public
+ */
+interface MultiSelectItem<A> {
+  /** Identifies the item within its section. */
+  readonly key: string;
+  /** What the row shows. */
+  readonly label: string;
+  /** What selecting it returns. */
+  readonly value: A;
+  /** A line shown, muted, beneath the list while this item is highlighted. */
+  readonly detail?: string;
+  /** Whether it starts selected. */
+  readonly selected?: boolean;
+}
+/**
+ * A titled group of items; the title is a header the cursor never stops on.
+ *
+ * @public
+ */
+interface MultiSelectSection<A> {
+  /** The header. */
+  readonly title: string;
+  /** The items, in order. */
+  readonly items: ReadonlyArray<MultiSelectItem<A>>;
+}
+/**
+ * Where a {@link MultiSelect} is: its sections, which items are selected, the viewport over the items, and whether
+ * it was submitted.
+ *
+ * @remarks
+ * Items are numbered across sections in order, section by section; `chosen` holds those numbers.
+ *
+ * @public
+ */
+interface MultiSelectState<A> {
+  /** The sections. */
+  readonly sections: ReadonlyArray<MultiSelectSection<A>>;
+  /** The selected items, by their number across all sections. */
+  readonly chosen: ReadonlySet<number>;
+  /** The highlighted item and the window over the list; it counts items only, never headers. */
+  readonly viewport: ViewportState;
+  /** Whether enter was pressed. */
+  readonly submitted: boolean;
+}
+/**
+ * What a key does in a {@link MultiSelect}.
+ *
+ * @public
+ */
+type MultiSelectAction = ViewportMove | "toggle" | "toggleSection" | "submit" | "cancel";
+/**
+ * Options for {@link MultiSelect.init}.
+ *
+ * @public
+ */
+interface MultiSelectInitOptions {
+  /** How many rows the list shows at most; the terminal height also limits it. 10 by default. */
+  readonly height?: number;
+}
+/**
+ * Options for {@link MultiSelect.screen}.
+ *
+ * @public
+ */
+interface MultiSelectScreenOptions<A> {
+  /** The question, shown above the list. */
+  readonly message: string;
+  /** The sections. */
+  readonly sections: ReadonlyArray<MultiSelectSection<A>>;
+  /** How many rows the list shows at most. */
+  readonly height?: number;
+}
+/**
+ * Props of {@link MultiSelect.View}.
+ *
+ * @public
+ */
+interface MultiSelectViewProps<A> extends MultiSelectScreenOptions<A> {
+  /** Receives the selected values, in section then item order, when enter is pressed. */
+  readonly onSubmit: (values: ReadonlyArray<A>) => void;
+}
+/**
+ * Several choices from sectioned lists: a pure reducer, its key table, a view and a ready-made screen.
+ *
+ * Item keys must be unique across all sections; `init` throws, and `screen` dies, on a repeat.
+ *
+ * @remarks
+ * The cursor moves over items only; section titles are headers drawn by the viewport, which keeps a scrolled-off
+ * header visible. Submitting with nothing selected resolves an empty list, which is a result, not a cancel.
+ *
+ * @example
+ * ```ts
+ * import { CliUi, MultiSelect } from "@effected/cli-kit/ui"
+ * import { Effect } from "effect"
+ *
+ * const pickFeatures = Effect.gen(function* () {
+ * 	const features = yield* CliUi.run(
+ * 		MultiSelect.screen({
+ * 			message: "Which features?",
+ * 			sections: [
+ * 				{
+ * 					title: "Tooling",
+ * 					items: [
+ * 						{ key: "lint", label: "Linting", value: "lint", selected: true },
+ * 						{ key: "test", label: "Tests", value: "test" },
+ * 					],
+ * 				},
+ * 			],
+ * 		}),
+ * 	)
+ * 	return features
+ * })
+ * ```
+ *
+ * @public
+ */
+export declare class MultiSelect {
+  private constructor();
+  /**
+   * A multi-select over `sections`, each item starting as its own `selected` flag says, on the first item.
+   *
+   * @param sections - the sections
+   * @param options - the list height
+   */
+  static readonly init: <A>(sections: ReadonlyArray<MultiSelectSection<A>>, options?: MultiSelectInitOptions) => MultiSelectState<A>;
+  /**
+   * Apply an action: a viewport move over the items; `"toggle"` flips the highlighted item; `"toggleSection"`
+   * selects every item of the highlighted item's section while any is unselected, and clears them all otherwise;
+   * `"submit"` marks it submitted; `"cancel"` changes nothing here, because ending the screen is the view's job.
+   *
+   * @param state - where the multi-select is
+   * @param action - the action
+   */
+  static readonly step: <A>(state: MultiSelectState<A>, action: MultiSelectAction) => MultiSelectState<A>;
+  /**
+   * The selected values, in section order and then item order, however they were toggled.
+   *
+   * @param state - where the multi-select is
+   */
+  static readonly selected: <A>(state: MultiSelectState<A>) => ReadonlyArray<A>;
+  /** The keys: ↑/↓ move (page, home and end too), space toggle, a toggle section, enter continue, q cancel. */
+  static readonly keys: KeyTable<MultiSelectAction>;
+  /**
+   * Draw the multi-select: the message, the sections (each item a check glyph, `◉`/`◯` or `[x]`/`[ ]` under ASCII,
+   * then its label cut to the width; the highlighted one in the accent token with the arrow glyph), the highlighted
+   * item's detail, and the key help. Enter calls `onSubmit` with the selected values; `q` cancels with `"escape"`.
+   *
+   * @remarks
+   * Single-shot, like `Select.View`: the sections are read once at mount.
+   *
+   * @param props - the message, the sections, and where the selection goes
+   */
+  static readonly View: <A>(props: MultiSelectViewProps<A>) => ReactElement;
+  /**
+   * A ready-made screen for `CliUi.run`: the multi-select, resolving with the selected values (`[]` when none are).
+   *
+   * @param options - the message, the sections and the list height
+   */
+  static readonly screen: <A>(options: MultiSelectScreenOptions<A>) => Screen<ReadonlyArray<A>>;
+}
+/**
+ * One choice of a {@link Select}.
+ *
+ * @public
+ */
+interface SelectChoice<A> {
+  /** What the row shows. */
+  readonly label: string;
+  /** What choosing it returns. */
+  readonly value: A;
+  /** A line shown, muted, beneath the list while this choice is highlighted. */
+  readonly detail?: string;
+  /** Shown muted and never highlighted: moves skip it. */
+  readonly disabled?: boolean;
+}
+/**
+ * Where a {@link Select} is: its choices, the viewport over them, and whether one was submitted.
+ *
+ * @public
+ */
+interface SelectState<A> {
+  /** The choices. */
+  readonly choices: ReadonlyArray<SelectChoice<A>>;
+  /** The highlighted choice and the window over the list. */
+  readonly viewport: ViewportState;
+  /** Whether the highlighted choice was submitted. */
+  readonly submitted: boolean;
+}
+/**
+ * What a key does in a {@link Select}: a viewport move, submit, or cancel.
+ *
+ * @public
+ */
+type SelectAction = ViewportMove | "submit" | "cancel";
+/**
+ * Options for {@link Select.init}.
+ *
+ * @public
+ */
+interface SelectInitOptions {
+  /**
+   * The choice to start on: the first enabled one at or after it, or the nearest enabled one before it when none
+   * follows. 0 by default.
+   */
+  readonly initial?: number;
+  /** How many rows the list shows at most; the terminal height also limits it. 10 by default. */
+  readonly height?: number;
+}
+/**
+ * Props of {@link Select.View}.
+ *
+ * @public
+ */
+interface SelectViewProps<A> {
+  /** The question, shown above the list. */
+  readonly message: string;
+  /** The choices. */
+  readonly choices: ReadonlyArray<SelectChoice<A>>;
+  /** The choice to start on. */
+  readonly initial?: number;
+  /** How many rows the list shows at most. */
+  readonly height?: number;
+  /** Receives the value chosen with enter. */
+  readonly onSubmit: (value: A) => void;
+}
+/**
+ * Options for {@link Select.screen}.
+ *
+ * @public
+ */
+interface SelectScreenOptions<A> {
+  /** The question, shown above the list. */
+  readonly message: string;
+  /** The choices. */
+  readonly choices: ReadonlyArray<SelectChoice<A>>;
+  /** The choice to start on. */
+  readonly initial?: number;
+  /** How many rows the list shows at most. */
+  readonly height?: number;
+}
+/**
+ * A single choice from a list: a pure reducer, its key table, a view, and a ready-made screen.
+ *
+ * @remarks
+ * A select with no enabled choice is a programming error: `init` throws, and `screen` dies, saying so.
+ *
+ * @example
+ * ```ts
+ * import { CliUi, Select } from "@effected/cli-kit/ui"
+ * import { Effect } from "effect"
+ *
+ * const pickTarget = Effect.gen(function* () {
+ * 	const target = yield* CliUi.run(
+ * 		Select.screen({
+ * 			message: "Deploy to which environment?",
+ * 			choices: [
+ * 				{ label: "staging", value: "staging" },
+ * 				{ label: "production", value: "production", detail: "Needs approval" },
+ * 			],
+ * 		}),
+ * 	)
+ * 	return target
+ * })
+ * ```
+ *
+ * @public
+ */
+export declare class Select {
+  private constructor();
+  /**
+   * A select over `choices`, on the first enabled choice at or after `initial` (the nearest enabled one before it
+   * when none follows).
+   *
+   * @param choices - the choices
+   * @param options - the starting choice and the list height
+   */
+  static readonly init: <A>(choices: ReadonlyArray<SelectChoice<A>>, options?: SelectInitOptions) => SelectState<A>;
+  /**
+   * Apply an action: a move lands on the nearest enabled choice, never on a disabled one and never past either
+   * end; `"submit"` marks the highlighted choice chosen (a disabled one never is); `"cancel"` changes nothing here,
+   * because ending the screen is the view's job.
+   *
+   * @param state - where the select is
+   * @param action - the action
+   */
+  static readonly step: <A>(state: SelectState<A>, action: SelectAction) => SelectState<A>;
+  /**
+   * The submitted value, or `None` before a submit.
+   *
+   * @param state - where the select is
+   */
+  static readonly chosen: <A>(state: SelectState<A>) => Option.Option<A>;
+  /** The keys: the viewport's moves, enter choose, q cancel. */
+  static readonly keys: KeyTable<SelectAction>;
+  /**
+   * 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.
+   *
+   * @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.
+   *
+   * @param props - the message, the choices, and where the chosen value goes
+   */
+  static readonly View: <A>(props: SelectViewProps<A>) => ReactElement;
+  /**
+   * A ready-made screen for `CliUi.run`: the select, resolving with the chosen value.
+   *
+   * @param options - the message, the choices, the starting choice and the list height
+   */
+  static readonly screen: <A>(options: SelectScreenOptions<A>) => Screen<A>;
+}
+/**
+ * What a key does to a {@link Tabs} row: move to the previous or next tab (wrapping), or jump to one by index.
+ *
+ * @public
+ */
+type TabsAction = "prev" | "next" | {
+  readonly jump: number;
+};
+/**
+ * One tab.
+ *
+ * @public
+ */
+interface Tab<N extends string> {
+  /** Identifies the tab; `onChange` and `value` speak in names. */
+  readonly name: N;
+  /** What the tab shows. */
+  readonly label: string;
+}
+/**
+ * Props of {@link Tabs.View}.
+ *
+ * @public
+ */
+interface TabsProps<N extends string> {
+  /** The tabs, in order. */
+  readonly tabs: ReadonlyArray<Tab<N>>;
+  /** The active tab, when the caller controls it: keys then only ask, through `onChange`. */
+  readonly value?: N;
+  /** The starting tab when uncontrolled; the first tab by default. */
+  readonly defaultValue?: N;
+  /** Called with the starting tab once on mount, then with every tab a key asks for. */
+  readonly onChange?: (name: N, index: number) => void;
+  /**
+   * Whether the tabs read keys; `true` by default. Unfocused, every tab is muted (the active one still underlined)
+   * and keys are ignored.
+   */
+  readonly isFocused?: boolean;
+  /** Number each tab, `1. Label`; `false` by default. */
+  readonly showIndex?: boolean;
+  /** Between tabs in a row; ` │ ` by default (` | ` under ASCII glyphs). */
+  readonly separator?: string;
+  /** A row (`←`/`→`) or a column (`↑`/`↓`) of tabs; a row by default. */
+  readonly direction?: "row" | "column";
+}
+/**
+ * A row (or column) of tabs, for a consumer's own screen.
+ *
+ * @remarks
+ * Not a screen: render `Tabs.View` inside a consumer's own screen. Its keys come from one `useKeys`, so there is a
+ * single input reader. Tab and Shift-Tab cycle whenever the tabs are focused, and plain digits jump, so a screen that
+ * hosts Tabs beside another widget reading Tab, arrows or digits (a `TextInput`, say) must decide who has the keys:
+ * pass `isFocused: false` to the Tabs while the other widget is being typed into. When unfocused, Tabs reads no key
+ * and is drawn muted.
+ *
+ * @public
+ */
+export declare class Tabs {
+  private constructor();
+  /**
+   * The tab an action lands on: `"prev"` and `"next"` wrap at both ends; `{ jump }` moves to that index and does
+   * nothing when it is out of range.
+   *
+   * @param index - the active tab
+   * @param count - how many tabs there are
+   * @param action - the action
+   */
+  static readonly step: (index: number, count: number, action: TabsAction) => number;
+  /** The keys of a row: `←`/`→` and Tab/Shift-Tab switch, plain digits 1–9 jump, 0 is the tenth tab. */
+  static readonly keys: KeyTable<TabsAction>;
+  /** The keys of a column: `↑`/`↓` in place of `←`/`→`. */
+  static readonly columnKeys: KeyTable<TabsAction>;
+  /**
+   * Draw the tabs: the active one in the accent token, bold and underlined; the others plain; every tab muted while
+   * unfocused. At colour `"none"`, where all of that vanishes, the active tab is bracketed, `[Alpha]`, and the others
+   * padded a space each side. A row wider than the terminal shows the tabs that fit around the active one, with the
+   * glyph set's ellipsis at a cut edge, so it never wraps.
+   *
+   * @remarks
+   * Controlled when `value` is given: a key calls `onChange` and the active tab moves only when `value` does.
+   * Uncontrolled otherwise, starting at `defaultValue` or the first tab. Either way `onChange` fires once on mount
+   * with the starting tab.
+   *
+   * @param props - the tabs and how they behave
+   */
+  static readonly View: <N extends string>(props: TabsProps<N>) => ReactElement;
+}
+/**
+ * Where a {@link TextInput} is: its value, the cursor within it, and whether enter was pressed.
+ *
+ * @public
+ */
+interface TextInputState {
+  /** The text. */
+  readonly value: string;
+  /**
+   * 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. */
+  readonly submitted: boolean;
+}
+/**
+ * Options for {@link TextInput.init}.
+ *
+ * @public
+ */
+interface TextInputInitOptions {
+  /** The starting text; the cursor starts after it. */
+  readonly initial?: string;
+}
+/**
+ * Options for {@link TextInput.screen}.
+ *
+ * @public
+ */
+interface TextInputScreenOptions {
+  /** The question, shown above the input. */
+  readonly message: string;
+  /** The starting text. */
+  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; 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}.
+ *
+ * @public
+ */
+interface TextInputViewProps extends TextInputScreenOptions {
+  /** Receives the value when enter is pressed and it validates. */
+  readonly onSubmit: (value: string) => void;
+}
+/**
+ * One line of text: a pure reducer, a view and a ready-made screen.
+ *
+ * @remarks
+ * Every typed character is text, `q` included: the input binds no letter, so Esc and Ctrl-C are the screen's root
+ * keys and still cancel with `"escape"` and `"interrupt"`.
+ *
+ * @example
+ * ```ts
+ * import { CliUi, TextInput } from "@effected/cli-kit/ui"
+ * import { Effect } from "effect"
+ *
+ * const askName = Effect.gen(function* () {
+ * 	const name = yield* CliUi.run(
+ * 		TextInput.screen({
+ * 			message: "Package name?",
+ * 			placeholder: "my-package",
+ * 			validate: (value) => (value.trim() === "" ? "A name is required" : undefined),
+ * 		}),
+ * 	)
+ * 	return name
+ * })
+ * ```
+ *
+ * @public
+ */
+export declare class TextInput {
+  private constructor();
+  /**
+   * An input holding `initial`, the cursor after it.
+   *
+   * @param options - the starting text
+   */
+  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 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
+   */
+  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), 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
+   * Text read in one go (a fast typist) is typed as it reads: printable runs are inserted whole, a return submits
+   * what came before it (anything after it is dropped), a backspace byte deletes, a line feed becomes a space, and a
+   * tab or other control character is dropped. A bracketed paste is inserted as text, its line breaks as spaces, and
+   * never submits.
+   *
+   * @param props - the message, the starting text, the placeholder, the validator and where the value goes
+   */
+  static readonly View: (props: TextInputViewProps) => ReactElement;
+  /**
+   * A ready-made screen for `CliUi.run`: the input, resolving with the submitted text.
+   *
+   * @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>;
+}
+/**
+ * Props of {@link Toggle.View}.
+ *
+ * @public
+ */
+interface ToggleViewProps {
+  /** What the toggle controls. */
+  readonly label: string;
+  /** Whether it is on. */
+  readonly value: boolean;
+  /** Whether the row is the highlighted one. */
+  readonly highlighted: boolean;
+}
+/**
+ * An on/off row: a check glyph and a label.
+ *
+ * @public
+ */
+export declare class Toggle {
+  private constructor();
+  /**
+   * Draw a toggle row: `◉` on or `◯` off (`[x]` and `[ ]` under ASCII glyphs), then the label, cut to the width with
+   * the glyph set's ellipsis. A highlighted row starts with the arrow glyph and is painted with the accent token.
+   *
+   * @param props - the label, the value and whether the row is highlighted
+   */
+  static readonly View: (props: ToggleViewProps) => ReactElement;
+}
+/**
+ * The streams a screen mounts on: Node streams, because Ink's stream contract is Node's.
+ *
+ * @remarks
+ * `stdin` must offer `isTTY`, `setRawMode`, `ref` and `unref`, and emit `readable`; `stdout` and `stderr` offer
+ * `columns`, `rows`, `isTTY` and `write`, and emit `resize`.
+ *
+ * The members are typed with Node's own stream types (`NodeJS.ReadStream`, `NodeJS.WriteStream`), as Ink's are, so a
+ * TypeScript consumer of `./ui` needs `@types/node`, beside the optional peer `@types/react` for its React types.
+ *
+ * @public
+ */
+interface UiStreamsShape {
+  /** The input a screen reads keys from. */
+  readonly stdin: NodeJS.ReadStream;
+  /** The output a screen draws on. */
+  readonly stdout: NodeJS.WriteStream;
+  /** The error output, which Ink also binds. */
+  readonly stderr: NodeJS.WriteStream;
+}
+declare const UiStreams_base: Context.Reference<UiStreamsShape>;
+/**
+ * The streams a screen mounts on, the process's own standard streams by default.
+ *
+ * @remarks
+ * A `Context.Reference`, so it never appears in `R`: the default reads the process streams when first used, never
+ * at import, and a test provides in-memory streams with `Effect.provideService(UiStreams, streams)`. `./ui` binds
+ * Node's process streams.
+ *
+ * @public
+ */
+export declare class UiStreams extends UiStreams_base {}
+/**
+ * The styling props of an Ink `Text` that a `Style` (from `@effected/cli-kit`) maps to.
+ *
+ * @public
+ */
+interface InkTextProps {
+  /** The foreground: a colour name or a `#rrggbb` hex. */
+  readonly color?: string;
+  /** Bold. */
+  readonly bold?: boolean;
+  /** Dim. */
+  readonly dimColor?: boolean;
+  /** Italic. */
+  readonly italic?: boolean;
+  /** Underline. */
+  readonly underline?: boolean;
+}
+/**
+ * Props of {@link Styled}.
+ *
+ * @public
+ */
+interface StyledProps {
+  /** A theme token, or an explicit style. */
+  readonly token: Cli.TokenName | Cli.Style;
+  /** The text. */
+  readonly children?: ReactNode;
+}
+/**
+ * The usable size of the terminal.
+ *
+ * @public
+ */
+interface TerminalSize {
+  /** The width, less one column, so a full-width line never wraps the cursor. */
+  readonly columns: number;
+  /** The height, less one row, so a full-height frame never scrolls. */
+  readonly rows: number;
+}
+/**
+ * The Ink `Text` props for `style` at `color`.
+ *
+ * @remarks
+ * At `"none"` it gives no styling props at all, not even bold or dim, so a frame is escape-free by construction;
+ * Ink's colour level held at 0 is the backstop. A flag set to `false` adds no prop.
+ *
+ * Omit `color` in an Ink tree the kit did not mount, which has no colour level of its own to pass: every prop is
+ * emitted, as at any level but `"none"`, and Ink's own chalk gates what reaches the terminal.
+ *
+ * @param style - the resolved style
+ * @param color - the stream's colour level; omitted, every prop is emitted for Ink's chalk to gate
+ *
+ * @public
+ */
+export declare const inkProps: (style: Cli.Style, color?: ColorLevel) => InkTextProps;
+/**
+ * The theme of the stream the mounted screen draws on.
+ *
+ * @remarks
+ * A React hook: call it from a component rendered inside a `CliUi.run` screen or a `UiProvider`.
+ *
+ * @public
+ */
+export declare const useTheme: () => Cli.StreamTheme;
+/**
+ * The glyph set of the mounted screen, so a component draws Unicode or ASCII glyphs to match the rest of the output.
+ *
+ * @remarks
+ * A React hook: call it from a component rendered inside a `CliUi.run` screen or a `UiProvider`.
+ *
+ * @public
+ */
+export declare const useGlyphs: () => Cli.GlyphSet;
+/**
+ * The Ink `Text` props for `token`, resolved through the mounted screen's theme.
+ *
+ * @remarks
+ * The route a component takes to honour the theme: it sees a consumer's token overrides and `CliUiTest.styled`'s
+ * marker palette, and gives no styling props at colour `none`. `inkProps(Token.resolve(token))` resolves against the
+ * default palette and ignores the mounted theme, so under `CliUiTest.styled` it renders a raw colour where this
+ * renders the token.
+ *
+ * A React hook: call it from a component rendered inside a `CliUi.run` screen or a `UiProvider`.
+ *
+ * @param token - a theme token, or an explicit style
+ *
+ * @public
+ */
+export declare const useStyle: (token: Cli.TokenName | Cli.Style) => InkTextProps;
+/**
+ * Text painted with a theme token or style, through the mounted screen's theme.
+ *
+ * @remarks
+ * Its children are drawn as given. The kit's widgets sanitise every string they draw from data (escapes removed,
+ * line breaks folded) before handing it here; text a consumer passes to `Styled`, or to Ink's own `Text`, is the
+ * consumer's to sanitise, with `Fmt.sanitize`. Ink keeps the escape sequences it is handed, so text from data drawn
+ * unsanitised can paint colour at colour `none` or plant a hyperlink, and a line break in it adds a row the screen's
+ * height budget did not count.
+ *
+ * @param props - the token or style, and the text
+ *
+ * @public
+ */
+export declare const Styled: (props: StyledProps) => ReactElement;
+/**
+ * The usable terminal size: the stdout Ink draws on, less one column and one row, re-read on every render and when
+ * the terminal resizes; or, under a `UiProvider` given a `size`, that size less one column and one row.
+ *
+ * @remarks
+ * A width or height the stream does not report, or reports as 0 (a pty that `script` opens says `0 0`), is unknown and
+ * reads as 80 columns by 24 rows, so a screen never lays itself out at width 0. This is not Ink's own fallback, which
+ * first asks the process's terminal (`terminal-size`: the tty, `COLUMNS`, `tput`) and only then uses 80x24; the kit
+ * reads no `process` here. On a 0x0 pty with `COLUMNS=50`, Ink lays out at 50 while these rows are cut at 79.
+ *
+ * The override exists for Ink's `renderToString`, whose `useStdout` is the process's own stdout whatever width it
+ * lays out at; without it, the kit's widgets would cut their rows to the wrong width there.
+ *
+ * Never feed `columns` into a `Box`'s `width`. On a resize Ink re-lays out the tree it already has and repaints
+ * before React re-renders with the new size, so a width taken from this hook is one paint stale. After a shrink,
+ * that stale, wider frame wraps in the narrower terminal and leaves a copy stranded above the live one. For a
+ * one-column margin use `marginRight: 1`, which Ink recomputes within its own resize. Text cut to `columns` lags the
+ * same paint, so give a long row Ink's `wrap: "truncate-end"` too: on a shrink Ink then clips it rather than letting
+ * the terminal wrap it.
+ *
+ * Every component following one stdout shares a single `resize` listener on it, so a screen of many rows (a
+ * `Viewport` of `DocView`s) holds one listener, not one per row.
+ *
+ * A React hook: call it from a component rendered inside an Ink tree; it needs no screen, but reads a `UiProvider`'s
+ * size when there is one.
+ *
+ * @public
+ */
+export declare const useTerminalSize: () => TerminalSize;
+export type { Binding, CliUiFallbackOptions, CliUiPromptOptions, CliUiRunOptions, ConfirmAction, ConfirmInitOptions, ConfirmResult, ConfirmScreenOptions, ConfirmState, ConfirmToggle, ConfirmViewProps, DetachedLive, DetachedLiveOptions, DocViewProps, InkTextProps, KeyHelpProps, KeyHelpRow, KeyName, LiveHandle, LiveOptions, MultiSelectAction, MultiSelectInitOptions, MultiSelectItem, MultiSelectScreenOptions, MultiSelectSection, MultiSelectState, MultiSelectViewProps, RouteStreamOptions, RoutedStream, Screen, ScreenControl, SelectAction, SelectChoice, SelectInitOptions, SelectScreenOptions, SelectState, SelectViewProps, StyledProps, Tab, TabsAction, TabsProps, TerminalSize, TextInputInitOptions, TextInputScreenOptions, TextInputState, TextInputViewProps, ToggleViewProps, UiContextValue, UiProviderProps, UiStreamsShape, UseKeysOptions, ViewportMove, ViewportRow, ViewportState, ViewportViewProps };
+//# sourceMappingURL=ui.d.ts.map