@fishwithcat/dsh-tui-app 0.0.0-stage → 0.2.2-alpha.2

package/lib/startup.js

@@ -0,0 +1,54 @@
+import { Command } from "commander";
+import { parseCmdline } from "@deepseek-ai/dsh-cmdline";
+//#region lib/types/startup.js
+/**
+* The terminal app's command-line provider: it parses the `dsh --profile tui`
+* flag family (`--resume`, `--provider`, `--model`, `--watch`) and its `--help` text, then
+* publishes the values as {@link TUI_STARTUP_SERVICE}. The TUI row injects that
+* service, so a help or usage invocation — which publishes nothing — mounts no
+* terminal UI.
+* @module @deepseek-ai/dsh-tui-app/startup
+*/
+/** Stable Cordis plugin name. */
+const name = "tui-startup";
+/** Services required before the flags can be resolved. */
+const inject = ["cmdlineArgs"];
+/** Service provided by this plugin and injected by the TUI row. */
+const TUI_STARTUP_SERVICE = "tuiStartup";
+/**
+* This app's command: its flags, its description, and its help text.
+* @returns a fresh program, so one process can parse more than once (tests).
+*/
+function tuiCommand() {
+	return new Command().name("dsh --profile tui").description("Open the interactive terminal UI: one Agent, one session, driven in this process.").helpOption("-h, --help", "show this help").option("--resume <session-id>", "resume a stored session instead of starting a new one").option("--provider <provider>", "provider route for this session (requires --model)").option("--model <model>", "model id for this session (requires --provider)").option("--watch <session-id>", "view a local subagent session read-only; cannot be combined with --resume, --provider, or --model").addHelpText("after", `
+Examples:
+  dsh                                        open the TUI in the current directory
+  dsh --profile tui --resume <session-id>    continue a stored session
+  dsh watch <session-id>                     watch a local subagent read-only
+  dsh --provider deepseek-official --model deepseek-v4-flash
+`);
+}
+/**
+* Parse and publish the TUI invocation as an ordinary Cordis service. A partial
+* route is a usage error, so on rejection (and on `--help`) nothing is provided
+* and the TUI row stays pending.
+* @param ctx - plugin context carrying the command line.
+*/
+function apply(ctx) {
+	const program = tuiCommand();
+	program.action(() => {
+		const options = program.opts();
+		if (options.provider === void 0 !== (options.model === void 0)) program.error("error: --provider and --model must be given together");
+		if (options.watch === "") program.error("error: --watch needs a session id");
+		if (options.watch !== void 0 && (options.resume !== void 0 || options.provider !== void 0 || options.model !== void 0)) program.error("error: --watch cannot be combined with --resume, --provider, or --model");
+		ctx.provide(TUI_STARTUP_SERVICE, {
+			...options.resume === void 0 ? {} : { resume: options.resume },
+			...options.provider === void 0 ? {} : { provider: options.provider },
+			...options.model === void 0 ? {} : { model: options.model },
+			...options.watch === void 0 ? {} : { watch: options.watch }
+		});
+	});
+	parseCmdline(ctx, program);
+}
+//#endregion
+export { TUI_STARTUP_SERVICE, apply, inject, name };

package/lib/types/ansi.d.ts

@@ -0,0 +1,109 @@
+/**
+ * ANSI styling for the terminal surface and the pi-tui theme objects its
+ * components require. Colour is opt-out through the conventional environment
+ * switches, the palette follows the terminal background (dark by default, or
+ * the light variant when the deployment selects one), and a disabled theme
+ * returns text unchanged so rendering, width calculation, and tests stay
+ * colour-independent.
+ * @module @deepseek-ai/dsh-tui-app/ansi
+ */
+import type { EditorTheme, MarkdownTheme, SelectListTheme } from '@earendil-works/pi-tui';
+import type { TuiColorScheme } from './config.ts';
+/** One style: text in, styled text out, no state. */
+export type Styler = (text: string) => string;
+/** Semantic styles the transcript, status bar, and prompts share. */
+export interface TuiTheme {
+    /** Human prompt role marker and its continuation rule. */
+    user: Styler;
+    /** Assistant message body. */
+    assistant: Styler;
+    /** Assistant message role marker and its continuation rule. */
+    assistantRule: Styler;
+    /** Provider reasoning text, shown while it streams. */
+    reasoning: Styler;
+    /** Tool-call heading. */
+    tool: Styler;
+    /** Successful tool outcome. */
+    toolOk: Styler;
+    /** Failed tool outcome. */
+    toolError: Styler;
+    /** Tool result body: the output a Tool returned. */
+    toolResult: Styler;
+    /** Neutral app notice. */
+    notice: Styler;
+    /** Failure notice. */
+    error: Styler;
+    /** Approaching a budget the user still has room to act on. */
+    warning: Styler;
+    /** Emphasis on a value or label. */
+    accent: Styler;
+    /** Rules, separators, and other low-signal chrome. */
+    border: Styler;
+    /** De-emphasized supporting text. */
+    dim: Styler;
+    /** Bold text. */
+    bold: Styler;
+    /** Italic text, the markdown emphasis face. */
+    italic: Styler;
+    /** Added line of a file diff. */
+    diffAdd: Styler;
+    /** Removed line of a file diff. */
+    diffDel: Styler;
+    /** Unchanged context line of a file diff. */
+    diffContext: Styler;
+    /** Diff chrome: a file header or a hunk boundary. */
+    diffMeta: Styler;
+}
+/** The palette a run resolves to. */
+export type TuiPalette = 'dark' | 'light';
+/** Construction facts for {@link createTheme}. */
+export interface ThemeOptions {
+    /** Whether ANSI styles are emitted. */
+    enabled: boolean;
+    /** Palette the terminal background calls for. */
+    palette: TuiPalette;
+}
+/**
+ * Decide whether to emit ANSI styles for one output stream.
+ * @param environment - the process environment (`NO_COLOR`, `FORCE_COLOR`, `TERM`).
+ * @param isTty - whether that stream is a terminal.
+ * @returns true when styled output is appropriate.
+ */
+export declare function supportsColor(environment: NodeJS.ProcessEnv, isTty: boolean): boolean;
+/**
+ * Resolve the palette a run uses.
+ *
+ * `auto` reads `COLORFGBG`, the background signal xterm-family terminals
+ * export as `foreground;background`; a background index of 7 or 15 selects the
+ * light palette. An absent or unparseable value stays dark, because the dark
+ * palette is the one every terminal can render legibly.
+ * @param mode - the deployment's selection.
+ * @param environment - the process environment.
+ * @returns the palette to render with.
+ */
+export declare function resolveColorScheme(mode: TuiColorScheme, environment: NodeJS.ProcessEnv): TuiPalette;
+/**
+ * Build the surface theme.
+ * @param options - whether styles are emitted and which palette to use.
+ * @returns every semantic style the surface uses.
+ */
+export declare function createTheme(options: ThemeOptions): TuiTheme;
+/**
+ * Build the pi-tui select-list theme used by pickers and menus.
+ * @param theme - the surface theme.
+ * @returns the component's theme object.
+ */
+export declare function selectListTheme(theme: TuiTheme): SelectListTheme;
+/**
+ * Build the pi-tui composer theme.
+ * @param theme - the surface theme.
+ * @returns the component's theme object.
+ */
+export declare function editorTheme(theme: TuiTheme): EditorTheme;
+/**
+ * Build the pi-tui markdown theme used for assistant message bodies.
+ * @param theme - the surface theme.
+ * @returns the component's theme object.
+ */
+export declare function markdownTheme(theme: TuiTheme): MarkdownTheme;
+//# sourceMappingURL=ansi.d.ts.map

package/lib/types/app.d.ts

@@ -0,0 +1,480 @@
+/**
+ * The interactive terminal application: builds the pi-tui surface, owns the one
+ * session it drives, routes composer input to local commands, the command
+ * registry, or the Agent, and restores the terminal on exit.
+ * @module @deepseek-ai/dsh-tui-app/app
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SelectItem, Terminal } from '@earendil-works/pi-tui';
+import { copyClipboardText } from './clipboard.ts';
+import type { ClipboardImage } from './clipboard.ts';
+import type { Config } from './config.ts';
+import type { InteractionHost, InteractionTitle, PromptOutcome } from './interactions.ts';
+import type { TuiStartupValues } from './startup.ts';
+/** Process-facing effects the app needs; tests substitute them. */
+export declare const internals: {
+    /** Build the terminal the TUI drives. */
+    createTerminal: () => Terminal;
+    /** Whether this invocation has an interactive terminal. */
+    isInteractive: () => boolean;
+    /** Read one image from the system clipboard, or undefined when it holds none. */
+    readClipboardImage: () => Promise<ClipboardImage | undefined>;
+    /** Copy selected text through the host clipboard or terminal. */
+    copyClipboardText: typeof copyClipboardText;
+    /** Route console writes away from the terminal the app owns; returns the restore function. */
+    captureConsole: (sink: (text: string) => void) => () => void;
+    /** Sink for boot failures and the exit resume hint, neither of which the terminal surface can show. */
+    stderr: {
+        write(chunk: string): unknown;
+    };
+};
+/** Everything one TUI invocation needs from its launcher. */
+export interface TuiAppOptions {
+    /** The plugin context the tree mounted. */
+    ctx: Context;
+    /** Validated app settings. */
+    config: Config;
+    /** Working directory the session starts in. */
+    cwd: string;
+    /** Parsed invocation values, read from the startup provider. */
+    invocation: TuiStartupValues;
+    /** Request bounded process exit with `code`. */
+    exit(code: number): void;
+}
+/** The interactive application. */
+export declare class TuiApp implements InteractionHost {
+    private readonly options;
+    private readonly tui;
+    private readonly viewport;
+    private readonly theme;
+    private readonly transcript;
+    private readonly transcriptView;
+    private readonly statusBar;
+    /** Local `!` commands; owns the single foreground execution and its row. */
+    private readonly shell;
+    /** Local subagent watch service; owns the HTTP listener and runtime records. */
+    private readonly watch;
+    private readonly editor;
+    private readonly composer;
+    private readonly disposers;
+    /** Subscriptions to the current session; `/new` and `/resume` replace them wholesale. */
+    private readonly sessionDisposers;
+    private session;
+    private leaving;
+    private stopped;
+    private promptActive;
+    private promptChain;
+    /** Repaints a prompt whose heading changes while it is open, such as a timed countdown. */
+    private promptTick;
+    /** Clipboard images the composer holds, by the marker number the draft shows. */
+    private readonly pendingImages;
+    /** Clipboard reads in flight; the footer reports their wait until the last one settles. */
+    private pasteReads;
+    /** Whether this host's terminal claims Ctrl+V, so image paste belongs on Alt+V. */
+    private readonly altPaste;
+    /** Providers the deployment registered; more than one qualifies the footer's model label. */
+    private readonly providerCount;
+    /** Whether the mounted compaction engine schedules its own work. */
+    private readonly autoCompaction;
+    /** Whether a compaction transaction is in flight; the footer reports its wait. */
+    private compacting;
+    /** Restores the console methods; a no-op until the renderer installs its capture. */
+    private restoreConsole;
+    /** Footer measurement cached against the session and log position it was read at. */
+    private measurementCache;
+    /** Footer subagent counts cached against the session and log position they were read at. */
+    private constructor();
+    /**
+     * Boot one interactive TUI over the composed tree.
+     * @param options - the launcher's context, settings, invocation, and exit request.
+     * @returns the running application.
+     * @throws when the invocation has no interactive terminal.
+     */
+    static boot(options: TuiAppOptions): Promise<TuiApp>;
+    /**
+     * Build the surface, subscribe to the session, and start the terminal UI.
+     */
+    mount(): Promise<void>;
+    /**
+     * Stop the application, drain the session, and request process exit.
+     * @param code - the process exit code.
+     */
+    stop(code: number): Promise<void>;
+    /** The Agent this surface answers for. */
+    private get agent();
+    /**
+     * Subscribe to the session's durable events, live stream, and status, and
+     * fold the stored history a resumed session already holds.
+     * @param session - the session to observe.
+     */
+    private attach;
+    /**
+     * Fold one live event into the transcript and the footer's facts.
+     *
+     * A manual compaction runs outside the turn lifecycle, so the Agent's status
+     * stays `idle` and these durable markers are the only account of the wait.
+     * @param event - the event appended to this surface's session.
+     */
+    private applyEvent;
+    /** Install the global key bindings; the viewport owns scrolling keys. */
+    private registerKeys;
+    /**
+     * Flip plan mode for this session's Agent.
+     *
+     * The service commits the change immediately between turns and holds it until
+     * the next accepted in-turn pre-step while a turn is open, so the notice
+     * distinguishes the two.
+     */
+    private togglePlanMode;
+    /**
+     * Abort the running turn, interrupt the session's live subagents, and report
+     * the interruption.
+     *
+     * The Agent's lifecycle status stays `running` until the turn settles, so the
+     * notice is the immediate acknowledgement that the interrupt landed. The
+     * notice names subagents too whenever delegated work was in flight, whether
+     * or not the Agent itself was working.
+     */
+    private interrupt;
+    /**
+     * Route one composer submission.
+     *
+     * A `!` line runs locally, a `\!` line reaches the Agent with the backslash
+     * removed, a line citing held images becomes a prompt carrying them, and
+     * every other line runs a command or reaches the Agent as text. A refused
+     * line leaves the composer and its held images untouched.
+     * @param text - the submitted text.
+     */
+    private submit;
+    /**
+     * Why one submission cannot run now, or undefined when it may proceed.
+     *
+     * The local shell refuses a second command, and a prompt while it runs; a
+     * running turn refuses `!` but still accepts steering text. Commands stay
+     * available because they run in-process.
+     * @param value - the trimmed line.
+     * @param hasImages - whether the line cites held images.
+     * @returns the refusal to report, or undefined.
+     */
+    private refusal;
+    /**
+     * Whether the line names a command the composer dispatches instead of the Agent.
+     * @param value - the trimmed line.
+     * @returns whether the registry or the app owns the line.
+     */
+    private isCommandLine;
+    /**
+     * Run one composer line that carries no image: an app command, a registry
+     * command, or the Agent's next prompt.
+     * @param value - the trimmed line.
+     */
+    private runLine;
+    /**
+     * Hand one line to the Agent, steering while a turn runs.
+     * @param line - the model-visible prompt text.
+     */
+    private promptLine;
+    /**
+     * Attach one clipboard image to the composing draft.
+     *
+     * The bytes stay in memory until the submission citing the marker admits them
+     * to the durable attachment store, so a draft that never submits writes
+     * nothing. The read runs a platform program, so the footer reports the wait
+     * from the key press until the bytes arrive.
+     */
+    private pasteClipboardImage;
+    /**
+     * Admit one prompt's images and hand the Agent the text and durable references.
+     * @param text - the model-visible prompt text; empty for an image-only prompt.
+     * @param images - the prompt's images, in content order.
+     * @throws when the deployment stores no attachments, the routed model refuses images, or admission fails.
+     */
+    private sendImages;
+    /**
+     * Put a refused submission back into the composer without discarding what the
+     * user typed while its images were being admitted.
+     * @param text - the refused line, markers included.
+     * @param images - the images the line cites.
+     */
+    private restoreDraft;
+    /**
+     * Run one slash line: an app command, or a registry command against the Agent.
+     * @param name - the command name without the slash.
+     * @param input - the trailing input.
+     * @param line - the original line, forwarded to the registry unchanged.
+     */
+    private runCommand;
+    /** Invocation-derived session options. */
+    private sessionOptions;
+    /**
+     * Execute one registry command and render its settled result.
+     * @param name - the command name without the slash.
+     * @param line - the original line.
+     */
+    private registryCommand;
+    /** The `/help` body: app commands followed by registry commands. */
+    private helpText;
+    /** List stored sessions, newest first. */
+    private listSessions;
+    /**
+     * Fold the stored title of each listed session.
+     *
+     * The title is the client-visible label the other surfaces use: the leading
+     * words of the first eligible human message, a generated title, or an
+     * explicit rename. A failed read leaves that one row on its short id, and a
+     * deployment without the query service keeps the previous id-only list.
+     * @param ids - stored session ids to read.
+     * @returns title text by session id.
+     */
+    private sessionTitles;
+    /**
+     * Show the session's delegated children in a pinned panel.
+     *
+     * The panel reads live projections on every render, so the Agent keeps
+     * streaming and new children appear without writing a transcript row. A
+     * catalog read failure is shown in the panel instead of an empty list.
+     */
+    private subagentsCommand;
+    /**
+     * Resume a stored session named by input, or chosen from a picker.
+     * @param input - the trailing `/resume` input.
+     */
+    private resumeCommand;
+    /**
+     * Resume the stored session `id` over the live one.
+     *
+     * The typed and picker paths share this guard so neither reaches
+     * {@link replaceSession} without a backend or with the live session's own id:
+     * the live session already holds the state, and reopening the same id would
+     * conflict with the write claim its handle holds.
+     * @param id - the stored session id.
+     */
+    private resumeSession;
+    /**
+     * Show or switch the model route.
+     * @param input - the trailing `/model` input.
+     */
+    private modelCommand;
+    /**
+     * Apply a `provider/model` route.
+     * @param value - the route text.
+     */
+    private applyRoute;
+    /**
+     * Show or switch the reasoning effort of the routed model.
+     * @param input - the trailing `/effort` input.
+     */
+    private effortCommand;
+    /**
+     * Answer one question whose foreground window already closed.
+     *
+     * The timed call's own result recorded the timeout, so a late answer travels
+     * as a steered user message through the service, which also records the
+     * settlement in the session projection.
+     */
+    private questionsCommand;
+    /**
+     * Questions this session can still take an answer for.
+     * @returns the continued calls in ask order; empty when no projection registry is mounted.
+     */
+    private continuedQuestions;
+    /**
+     * Apply one reasoning effort to the route in force.
+     * @param effort - the selected effort, or undefined to send none and let the provider decide.
+     */
+    private applyEffort;
+    /**
+     * Swap the live session, rewiring events and clearing the transcript.
+     *
+     * The previous session is flushed and the replacement is opened before the
+     * previous one is retired, so a rejected flush or `open` leaves the running
+     * session, its subscriptions, and the transcript untouched. The replacement
+     * becomes current before the previous session is closed, so even a disposal
+     * failure leaves the app on a usable session.
+     * @param open - creates the replacement session.
+     */
+    private replaceSession;
+    /** Push the current facts into the footer and request a repaint. */
+    private refresh;
+    /**
+     * The directory the session currently works in. The model can change it
+     * during a turn, so this reads the working-directory service on every read
+     * and falls back to the launch directory when it is unmounted.
+     * @returns the absolute working directory.
+     */
+    private workingDirectory;
+    /**
+     * The footer's workspace label, abbreviated against the home directory.
+     * @returns the display path.
+     */
+    private workspaceLabel;
+    /**
+     * Whether plan mode is in force, or selected to apply from the next step.
+     *
+     * A queued selection changes without appending an event, so this reads the
+     * service on every refresh instead of caching against the log position.
+     * @returns the effective mode, or undefined when the deployment mounts no plan mode.
+     */
+    private planStatus;
+    /**
+     * Footer measurement for one session, read from the projection registry.
+     *
+     * The live Assistant stream repaints far more often than it appends session
+     * events, and a projection read folds every registered unit, so the whole
+     * measurement is cached against the Session and log position it was read at —
+     * keying on the Session too keeps a replaced session's figures out of the
+     * next one.
+     * @param session - the session whose footer facts are presented.
+     * @returns context occupancy and whole-log token figures for the frame.
+     */
+    private measurement;
+    /**
+     * The delegated-work counts the footer reports, read from the session's
+     * catalogs on the first frame after a log position or lifecycle edge that
+     * can move them. A deployment without the projection registry exposes no
+     * subagent catalog, so the footer omits the marker rather than failing a
+     * frame the way `/subagents` reports the gap.
+     * @param session - the session whose catalogs are walked.
+     * @returns the counts, or `undefined` while no child is recorded or the registry is absent.
+     */
+    private delegatedSubagents;
+    /**
+     * Refresh the delegated rows and repaint when the asynchronous read settles.
+     * The footer and panel read the session's cache, so this never blocks a frame.
+     */
+    private reloadSubagents;
+    /**
+     * The placeholder the empty composer shows: the keys valid in the current state.
+     * @param busy - whether the Agent or a live subagent descendant is working.
+     * @param planAvailable - whether the deployment mounts plan mode.
+     */
+    private hints;
+    /** Append one notice row and repaint. */
+    private notice;
+    /**
+     * Put one captured console write into the transcript.
+     *
+     * A console write carries no severity of its own: plugins that reserve stdout
+     * for protocol messages may report through `console.error`. A transcript row
+     * therefore stays an ordinary notice, keeping the tag that names its producer.
+     * @param text - the plain-text message.
+     */
+    private diagnostic;
+    /**
+     * Ask the user to choose one item through a modal list.
+     * @param title - the question shown above the list; a provider is re-evaluated on every repaint.
+     * @param items - the selectable items.
+     * @param signal - cancellation lifetime; aborting cancels the prompt.
+     * @param detail - markdown shown above the list; while it overflows, Up/Down
+     * and the wheel scroll it and Left/Right move the list selection. A detail
+     * gives the panel every row above the pinned footer instead of the picker's cap.
+     * @returns how the prompt settled: the chosen item, Escape's skip, or Ctrl+C's cancel.
+     */
+    choose(title: InteractionTitle, items: readonly SelectItem[], signal?: AbortSignal, detail?: string): Promise<PromptOutcome<SelectItem>>;
+    /**
+     * Ask the user to check any number of items through a modal list.
+     * @param title - the question shown above the list; a provider is re-evaluated on every repaint.
+     * @param items - the selectable items.
+     * @param signal - cancellation lifetime; aborting cancels the prompt.
+     * @param detail - markdown shown above the list; while it overflows, Up/Down
+     * and the wheel scroll it and Left/Right move the list selection.
+     * @returns how the prompt settled: the checked items in list order, Escape's
+     * skip, or Ctrl+C's cancel.
+     */
+    chooseMany(title: InteractionTitle, items: readonly SelectItem[], signal?: AbortSignal, detail?: string): Promise<PromptOutcome<SelectItem[]>>;
+    /**
+     * Open one modal list prompt and settle it through the caller's wiring.
+     *
+     * Both pickers share the panel budget, the selection a long detail moves with
+     * Left/Right, and the dismissal plumbing; they differ only in the control they
+     * build and the key that settles it, so those arrive as callbacks. Escape is
+     * the panel's own skip, so the wiring only supplies the control's two outcomes.
+     * @param title - the heading shown above the list.
+     * @param items - the selectable items, in display order.
+     * @param signal - cancellation lifetime; aborting cancels the prompt.
+     * @param detail - markdown shown above the list; absent shows the list alone.
+     * @param reservedRows - body rows the picker spends outside its options, such as a key hint.
+     * @param createList - builds the picker control for the computed visible count.
+     * @param wrapBody - wraps the picker with the detail viewport when a detail is present.
+     * @param wire - installs the caller's answer and cancel handlers.
+     * @returns how the prompt settled.
+     */
+    private pickList;
+    /**
+     * Ask the user for one line of text through a modal input.
+     * @param title - the question shown above the input; a provider is re-evaluated on every repaint.
+     * @param signal - cancellation lifetime; aborting cancels the prompt.
+     * @param detail - markdown shown above the input; Up/Down, PageUp/PageDown,
+     * and the wheel scroll it while it overflows. A detail gives the panel every
+     * row above the pinned footer instead of the picker's cap.
+     * @returns how the prompt settled: the entered text, Escape's skip, or Ctrl+C's cancel.
+     */
+    ask(title: InteractionTitle, signal?: AbortSignal, detail?: string): Promise<PromptOutcome<string>>;
+    /**
+     * Serialize modal prompts: only one may own the keyboard at a time.
+     * @param run - the prompt to run when its turn arrives.
+     * @returns the prompt's result.
+     */
+    private enqueuePrompt;
+    /**
+     * Show one modal over the transcript.
+     *
+     * The alternate-screen layout pins the composer and the footer, so the panel
+     * is anchored directly above them and reads as the transcript's next lines;
+     * the inline layout has no fixed footer position, so the panel is centered.
+     * @param title - the heading, a provider re-evaluated on every repaint, or
+     * undefined when the body supplies its own first line.
+     * @param body - the component that owns input while the modal is up.
+     * @param detailed - whether the body carries scrollable detail, which lets the
+     * panel take every row above the pinned footer instead of the picker's cap.
+     * @returns the overlay handle and the panel that draws the heading.
+     */
+    private showPrompt;
+    /**
+     * Rows one prompt panel may occupy above the pinned footer.
+     * @param detailed - whether the panel carries scrollable detail, which may
+     * take every row above the footer rather than the picker's cap.
+     * @returns the panel's row budget.
+     */
+    private promptRows;
+    /**
+     * Rows one prompt's heading takes from its panel budget.
+     * @param title - the heading to measure.
+     * @returns the heading's rows at the current viewport width.
+     */
+    private headingRows;
+    /**
+     * Close one modal and give the keyboard back to the composer.
+     * @param handle - the overlay handle returned by {@link showPrompt}.
+     */
+    private dismissPrompt;
+    /** Point the watch service at the session tree this surface now owns. */
+    private activateWatch;
+    /** Restore the terminal exactly once. */
+    private teardown;
+}
+/**
+ * Whether this host's terminals claim Ctrl+V for their own paste.
+ *
+ * Windows consoles and WSL distribute Ctrl+V to the terminal's paste, so the
+ * surface binds image paste to Alt+V there.
+ * @param platform - the platform the surface runs on.
+ * @param env - the process environment.
+ * @returns whether the alternate paste key governs this host.
+ */
+export declare function reservesCtrlV(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): boolean;
+/**
+ * Decode a mouse-wheel input sequence into the lines it scrolls.
+ *
+ * The alternate-screen renderer handles a wheel over its own scroll views; a
+ * focused prompt makes it defer the rest, so the surface needs its own reading
+ * of the two wheel encodings it accepts. The SGR form is `CSI < button ; column
+ * ; row M`; the legacy form is `CSI M` followed by button, column, and row
+ * bytes offset by 32. A wheel reports bit 6, a direction of 0 or 1, and bit 3
+ * for the Alt modifier.
+ * @param data - raw terminal input.
+ * @returns the signed scroll distance, negative upward, or undefined when the
+ * input is not a wheel event.
+ */
+export declare function wheelScroll(data: string): number | undefined;
+//# sourceMappingURL=app.d.ts.map