@lingxi-ai-cn/dsh-tui-runtime 0.1.0-rc.8

package/lib/types/resume.d.ts

@@ -0,0 +1,66 @@
+/** Pure session-resume candidate projection and picker helpers for the native TUI. */
+import { type SessionIdType as SessionId, type SessionRecord } from './host.ts';
+/** One detached row shown by the native TUI Session picker. */
+export interface TuiResumeCandidate {
+    /** Live-preferred Session record observed during the picker scan. */
+    record: SessionRecord;
+    /** Folded durable title or the local untitled fallback. */
+    title: string;
+    /** Best metadata-only activity timestamp available to the picker. */
+    updatedAt: number;
+    /** Whether this row belongs to the current Agent's workspace. */
+    currentWorkspace: boolean;
+    /** Display label for the row's own workspace. */
+    workspaceLabel: string;
+    /** Why the row cannot be resumed by this process-wide TUI composition. */
+    disabledReason?: string;
+}
+/** Current workspace scope selected in the native TUI Session picker. */
+export type TuiResumeScope = 'workspace' | 'all';
+/** Controller-owned asynchronous state for one Session picker generation. */
+export interface TuiResumeDialogSnapshot {
+    /** Monotonic identity used to reset picker-local search and selection. */
+    generation: number;
+    /** Current scan or resume operation phase. */
+    phase: 'loading' | 'ready' | 'resuming';
+    /** Current Agent workspace used by the default picker scope. */
+    currentWorkspaceLabel: string;
+    /** Sorted rows after the scan settles; absent while loading. */
+    candidates?: readonly TuiResumeCandidate[];
+    /** Candidate currently being resumed. */
+    resumingId?: SessionId;
+    /** Latest activation failure; the ready picker remains open for retry. */
+    error?: string;
+}
+/**
+ * Summarize one logical Session for the process-wide TUI composition.
+ * @param record - live-preferred Session record from `ctx.sessionQuery`.
+ * @param title - folded durable title, when one exists.
+ * @param updatedAt - live last-event time or persisted artifact mtime.
+ * @param currentId - Session currently owned by the TUI.
+ * @param currentCwd - current Session workspace used by the default scope.
+ * @returns a detached picker row with compatibility status.
+ */
+export declare function summarizeTuiResumeCandidate(record: SessionRecord, title: string | undefined, updatedAt: number | undefined, currentId: SessionId, currentCwd: string | undefined): TuiResumeCandidate;
+/**
+ * Sort resume rows newest-first with a stable Session-id tie break.
+ * @param candidates - detached picker rows.
+ * @returns a new sorted array.
+ */
+export declare function sortTuiResumeCandidates(candidates: readonly TuiResumeCandidate[]): TuiResumeCandidate[];
+/**
+ * Apply workspace scope and normalized literal search to picker rows.
+ * @param candidates - complete sorted picker rows.
+ * @param scope - current-workspace or all-workspaces view.
+ * @param query - title, id, or visible workspace query.
+ * @returns matching rows without mutating the source array.
+ */
+export declare function filterTuiResumeCandidates(candidates: readonly TuiResumeCandidate[], scope: TuiResumeScope, query: string): TuiResumeCandidate[];
+/**
+ * Format one activity timestamp as a compact deterministic relative age.
+ * @param updatedAt - observed Unix epoch milliseconds.
+ * @param now - current Unix epoch milliseconds.
+ * @returns `now` or a compact minutes/hours/days/months/years age.
+ */
+export declare function formatTuiRelativeTime(updatedAt: number, now: number): string;
+//# sourceMappingURL=resume.d.ts.map

package/lib/types/rewind.d.ts

@@ -0,0 +1,37 @@
+/** Pure human-boundary projection for native TUI Session rewind. */
+import { type SessionEvent, type SessionIdType as SessionId } from './host.ts';
+/** One completed human turn that can seed a rewound child Session. */
+export interface TuiRewindCandidate {
+    /** Append-origin human `user/message` seq used as the fork anchor. */
+    readonly eventSeq: number;
+    /** Sanitized prompt text shown in the selector and confirmation. */
+    readonly promptText: string;
+    /** Durable source events retained in the child seed. */
+    readonly retainedEventCount: number;
+    /** Later durable source events that remain only in the parent. */
+    readonly hiddenEventCount: number;
+}
+/** Controller-owned selection or Agent-preparation state for one rewind request. */
+export interface TuiRewindDialogSnapshot {
+    /** Monotonic identity for one dialog activation. */
+    readonly generation: number;
+    /** Command-audit settlement, selection, or child preparation phase. */
+    readonly phase: 'opening' | 'browsing' | 'rewinding';
+    /** Parent Session that remains active until replacement commits. */
+    readonly currentSessionId: SessionId;
+    /** Newest-first completed human boundaries, present after audit settlement. */
+    readonly candidates?: readonly TuiRewindCandidate[];
+    /** Candidate currently preparing a child Agent. */
+    readonly rewindingSeq?: number;
+    /** Latest preparation or switch failure while selection remains open. */
+    readonly error?: string;
+}
+/**
+ * Project every safe append-origin human boundary from a durable Session log.
+ * Open turns and model-only replacements are excluded; results are newest first.
+ *
+ * @param events - Complete current Session log after the rewind command audit settles.
+ * @returns Detached candidates with retained and parent-only event counts.
+ */
+export declare function tuiRewindCandidates(events: readonly SessionEvent[]): TuiRewindCandidate[];
+//# sourceMappingURL=rewind.d.ts.map

package/lib/types/sanitize.d.ts

@@ -0,0 +1,9 @@
+/** Terminal-safe text normalization. The renderer alone may emit controls. */
+/**
+ * Remove terminal control characters from untrusted model, tool, path, and error text.
+ * Newline and tab remain ordinary layout input; ESC and every other C0/C1 code become visible replacement glyphs.
+ * @param value - untrusted text.
+ * @returns text that cannot open an ANSI/OSC control sequence.
+ */
+export declare function terminalSafe(value: string): string;
+//# sourceMappingURL=sanitize.d.ts.map

package/lib/types/session-export.d.ts

@@ -0,0 +1,29 @@
+/** TUI-local state and path resolution for native Session archive export. */
+import type { SessionIdType as SessionId } from './host.ts';
+/** Lifecycle shown by the native Session export dialog. */
+export type TuiSessionExportPhase = 'opening' | 'selecting' | 'exporting';
+/** Process-local Session export dialog state; no field enters the Session log. */
+export interface TuiSessionExportDialogSnapshot {
+    /** Monotonic identity preventing stale export settlement from changing a newer dialog. */
+    readonly generation: number;
+    /** Current dialog operation phase. */
+    readonly phase: TuiSessionExportPhase;
+    /** Exact Session selected before the command lifecycle settled. */
+    readonly sessionId: SessionId;
+    /** Absolute workspace used to resolve a relative directory entry. */
+    readonly workspaceLabel: string;
+    /** Resolved absolute destination while bytes are being written. */
+    readonly destination?: string;
+    /** Whether durable descendant artifacts are included while writing. */
+    readonly includeDescendants?: boolean;
+    /** Safe failure text retained while the operator edits the destination. */
+    readonly error?: string;
+}
+/**
+ * Resolve terminal directory input against the Session workspace.
+ * @param workspace - absolute Session working directory.
+ * @param input - absolute or workspace-relative operator input; blank selects the workspace.
+ * @returns an absolute directory path for the host export service to validate.
+ */
+export declare function resolveTuiSessionExportDirectory(workspace: string, input: string): string;
+//# sourceMappingURL=session-export.d.ts.map

package/lib/types/session-lifecycle.d.ts

@@ -0,0 +1,20 @@
+/** TUI-local state for replacing the active Agent with a fresh Session. */
+import type { SessionIdType as SessionId } from './host.ts';
+/** User command that requests a fresh TUI Session. */
+export type TuiFreshSessionCommand = 'clear' | 'new';
+/** Controller-owned confirmation or creation state for one fresh Session request. */
+export interface TuiFreshSessionDialogSnapshot {
+    /** Monotonic identity for one dialog activation. */
+    readonly generation: number;
+    /** Command spelling that opened the dialog. */
+    readonly command: TuiFreshSessionCommand;
+    /** Whether the user is deciding or fresh Agent preparation is active. */
+    readonly phase: 'confirming' | 'creating';
+    /** Session that remains active until replacement commits. */
+    readonly currentSessionId: SessionId;
+    /** Workspace copied into the fresh Session. */
+    readonly workspaceLabel: string;
+    /** Latest preparation or switch failure while confirmation remains open. */
+    readonly error?: string;
+}
+//# sourceMappingURL=session-lifecycle.d.ts.map

package/lib/types/startup-logo.d.ts

@@ -0,0 +1,45 @@
+/** Electric startup mark data, terminal color fallback, and Ink rendering. */
+import React from 'react';
+import { type TuiTheme } from './theme.tsx';
+/** Display-cell width of the full Electric startup mark. */
+export declare const TUI_ELECTRIC_STARTUP_LOGO_WIDTH = 60;
+/** Row count of the full Electric startup mark. */
+export declare const TUI_ELECTRIC_STARTUP_LOGO_HEIGHT = 9;
+/** Terminal text rows for the full Electric startup mark without color escapes. */
+export declare const TUI_ELECTRIC_STARTUP_LOGO_ROWS: readonly string[];
+/** Startup mark selected for the available terminal geometry. */
+export type TuiStartupLogoVariant = 'electric' | 'compact';
+/**
+ * Resolve one Electric mark cell color for the active terminal theme.
+ * @param theme - resolved TUI theme and negotiated color precision.
+ * @param column - zero-based 30-cell logo column.
+ * @param row - zero-based logo row.
+ * @returns a true/extended-color value, ANSI theme accent, or no style for blank, invalid, or colorless cells.
+ */
+export declare function tuiElectricStartupLogoCellColor(theme: Pick<TuiTheme, 'colorDepth' | 'tokens'>, column: number, row: number): string | undefined;
+/**
+ * Select the full mark only when both dimensions preserve the complete centered startup workspace.
+ * @param stdout - terminal dimensions used by the active Ink frame.
+ * @param composerRows - mounted editor rows inside the bordered composer.
+ * @param supplementalRows - suggestion rows mounted between the mark and composer.
+ * @returns the full Electric or compact mark variant.
+ */
+export declare function resolveTuiStartupLogoVariant(stdout: Readonly<{
+    rows: number;
+    columns: number;
+}>, composerRows: number, supplementalRows?: number): TuiStartupLogoVariant;
+/**
+ * Return the physical row count of one startup mark variant.
+ * @param variant - selected startup mark.
+ * @returns its fixed terminal row count.
+ */
+export declare function tuiStartupLogoHeight(variant: TuiStartupLogoVariant): number;
+/**
+ * Render the selected startup mark through Ink and the negotiated TUI theme.
+ * @param props - selected startup mark variant.
+ * @returns fixed-dimension Ink text rows for that variant.
+ */
+export declare const TuiStartupLogo: React.MemoExoticComponent<({ variant }: {
+    readonly variant: TuiStartupLogoVariant;
+}) => React.ReactElement>;
+//# sourceMappingURL=startup-logo.d.ts.map

package/lib/types/store.d.ts

@@ -0,0 +1,88 @@
+/** Small external stores shared by the controller and Ink component tree. */
+import { type AgentStatus, type ApprovalOutcome, type ApprovalRequest, type AskUserQuestionAnswer, type AskUserQuestionRequest, type SessionEvent } from './host.ts';
+type Listener = () => void;
+/** Observable immutable value with stable snapshots for `useSyncExternalStore`. */
+export declare class ValueStore<T> {
+    private value;
+    private readonly listeners;
+    constructor(value: T);
+    /** Read the current immutable value for `useSyncExternalStore`. */
+    getSnapshot: () => T;
+    /**
+     * Subscribe to value changes.
+     * @param listener - callback invoked after a changed value commits.
+     * @returns disposer for this subscription.
+     */
+    subscribe: (listener: Listener) => (() => void);
+    /**
+     * Commit one value and notify subscribers when its identity changed.
+     * @param value - next immutable snapshot.
+     */
+    set(value: T): void;
+}
+/** Append-only observable Session-event snapshot. */
+export declare class SessionEventStore extends ValueStore<readonly SessionEvent[]> {
+    constructor(events: readonly SessionEvent[]);
+    /**
+     * Append one committed Session event to the observable snapshot.
+     * @param event - exact post-commit event.
+     */
+    append(event: SessionEvent): void;
+}
+/** Live Agent status projection. */
+export declare class AgentStatusStore extends ValueStore<AgentStatus> {
+}
+/** Public view of the approval currently owning terminal input. */
+interface PendingApproval {
+    /** Interaction discriminant. */
+    kind: 'approval';
+    /** Borrowed approval request. */
+    request: ApprovalRequest;
+}
+/** Public view of the structured question currently owning terminal input. */
+export interface PendingQuestion {
+    /** Interaction discriminant. */
+    kind: 'question';
+    /** Borrowed structured-question request. */
+    request: AskUserQuestionRequest;
+}
+/** The one FIFO interaction visible to the component tree, or no takeover. */
+export type TuiPendingInteraction = PendingApproval | PendingQuestion;
+/** FIFO owner for approvals and structured user questions. */
+export declare class InteractionStore extends ValueStore<TuiPendingInteraction | undefined> {
+    private readonly queue;
+    private disposed;
+    constructor();
+    /**
+     * Queue one approval wait.
+     * @param request - exact scoped approval request.
+     * @returns its fail-closed outcome after user action, abort, or teardown.
+     */
+    askApproval(request: ApprovalRequest): Promise<ApprovalOutcome>;
+    /**
+     * Queue one structured human-question wait.
+     * @param request - validated request from `ctx.userQuestions`.
+     * @returns structured answers after every question is completed.
+     */
+    askQuestion(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>;
+    /**
+     * Settle the current approval with a user-selectable outcome.
+     * @param outcome - allow once or reject.
+     */
+    answerApproval(outcome: Extract<ApprovalOutcome, 'allowed-once' | 'rejected'>): void;
+    /**
+     * Settle the current question with validated UI encoding.
+     * @param answer - structured answer set.
+     */
+    answerQuestion(answer: AskUserQuestionAnswer): void;
+    /** Reject or abort the interaction currently owning input. */
+    cancelCurrent(): void;
+    /** Fail closed and settle every queued interaction exactly once. */
+    dispose(): void;
+    private enqueue;
+    private settle;
+    private remove;
+    private publish;
+}
+export {};
+//# sourceMappingURL=store.d.ts.map

package/lib/types/suggestion.d.ts

@@ -0,0 +1,99 @@
+/** Pure completion state shared by command and workspace-path suggestions. */
+import type { CommandDescriptor, FsPathCompletionResult } from './host.ts';
+/** Origin of one TUI completion candidate. */
+export type TuiSuggestionKind = 'command' | 'path';
+/** Resolution state for a bounded TUI completion query. */
+export type TuiSuggestionStatus = 'ready' | 'loading' | 'empty' | 'truncated';
+/** One insertable item supplied by a TUI completion source. */
+export interface TuiSuggestionItem {
+    /** Stable identity within the source. */
+    id: string;
+    /** Text that replaces the active query range when accepted. */
+    insertText: string;
+    /** Primary text displayed in the completion list. */
+    label: string;
+    /** Concise explanation displayed beside the label. */
+    description: string;
+    /** Optional secondary information such as an argument hint. */
+    detail?: string | undefined;
+    /** Source that produced this item. */
+    source: TuiSuggestionKind;
+}
+/** Complete local state for one active TUI completion query. */
+export interface TuiSuggestionState {
+    /** Source that owns the active query. */
+    kind: TuiSuggestionKind;
+    /** Inclusive UTF-16 offset replaced on acceptance. */
+    queryStart: number;
+    /** Exclusive UTF-16 offset replaced on acceptance. */
+    queryEnd: number;
+    /** Selected item index in the complete result. */
+    selectedIndex: number;
+    /** First item mounted by the bounded list renderer. */
+    visibleStart: number;
+    /** Complete bounded result supplied by the source. */
+    items: readonly TuiSuggestionItem[];
+    /** Query resolution state shown when candidates are unavailable or incomplete. */
+    status: TuiSuggestionStatus;
+}
+/** Text and insertion point produced by accepting a completion. */
+export interface TuiSuggestionAcceptance {
+    /** Complete editor text after replacement. */
+    text: string;
+    /** UTF-16 insertion offset after the inserted text. */
+    cursor: number;
+}
+/** Range and workspace-relative query for the `@` token under the cursor. */
+export interface TuiPathSuggestionQuery {
+    /** Inclusive UTF-16 offset of the `@` marker. */
+    queryStart: number;
+    /** Exclusive UTF-16 offset of the complete token. */
+    queryEnd: number;
+    /** Query text after the `@` marker. */
+    query: string;
+}
+/**
+ * Resolve slash-command candidates for a command-only draft.
+ * @param text - complete composer text.
+ * @param cursor - active UTF-16 insertion offset.
+ * @param commands - effective Agent-scoped command descriptors.
+ * @returns active suggestion state, or `undefined` outside a command query.
+ */
+export declare function commandSuggestionState(text: string, cursor: number, commands: readonly CommandDescriptor[]): TuiSuggestionState | undefined;
+/**
+ * Find an `@token` only when the token begins at the draft or after whitespace.
+ * @param text - complete composer text.
+ * @param cursor - active UTF-16 insertion offset.
+ * @returns the token range and workspace-relative query, or `undefined` outside one.
+ */
+export declare function pathSuggestionQuery(text: string, cursor: number): TuiPathSuggestionQuery | undefined;
+/**
+ * Convert one bounded filesystem result into the shared TUI suggestion state.
+ * @param query - active `@token` range and workspace-relative query.
+ * @param result - provider result, or `undefined` while the query is loading.
+ * @returns path suggestion state with directory/file-specific insertion text.
+ */
+export declare function pathSuggestionState(query: TuiPathSuggestionQuery, result: FsPathCompletionResult | undefined): TuiSuggestionState;
+/**
+ * Move the selected candidate while keeping it inside the mounted item window.
+ * @param state - active suggestion state.
+ * @param direction - selection direction.
+ * @param visibleLimit - maximum mounted candidate rows.
+ * @returns state with a clamped selection and window.
+ */
+export declare function moveTuiSuggestion(state: TuiSuggestionState, direction: 'previous' | 'next', visibleLimit: number): TuiSuggestionState;
+/**
+ * Replace the active query with its selected candidate.
+ * @param text - complete composer text.
+ * @param state - active suggestion state.
+ * @returns updated text and cursor, or `undefined` when no item is selectable.
+ */
+export declare function acceptTuiSuggestion(text: string, state: TuiSuggestionState): TuiSuggestionAcceptance | undefined;
+/**
+ * Return only the candidate rows mounted by the current suggestion window.
+ * @param state - active suggestion state.
+ * @param visibleLimit - maximum mounted candidate rows.
+ * @returns the visible item slice.
+ */
+export declare function visibleTuiSuggestions(state: TuiSuggestionState, visibleLimit: number): readonly TuiSuggestionItem[];
+//# sourceMappingURL=suggestion.d.ts.map

package/lib/types/terminal-input.d.ts

@@ -0,0 +1,69 @@
+/** Incremental terminal protocol decoding for native TUI input dispatch. */
+import type { TuiKeypress } from './keybindings.ts';
+/** One normalized event emitted by the native terminal input decoder. */
+export type TuiTerminalInputEvent = {
+    readonly kind: 'input';
+    /** Committed text, or the printable identity of a modified key. */
+    readonly input: string;
+    /** Normalized key flags independent of a terminal keyboard protocol. */
+    readonly key: TuiKeypress;
+    /** Whether an oversized bracketed paste was bounded before dispatch. */
+    readonly truncated?: boolean;
+} | {
+    readonly kind: 'mouse';
+    /** SGR button and modifier bit field. */
+    readonly button: number;
+    /** One-based terminal column. */
+    readonly column: number;
+    /** One-based terminal row. */
+    readonly row: number;
+    /** Whether the report ends a press rather than starting or moving one. */
+    readonly release: boolean;
+} | {
+    readonly kind: 'focus';
+    /** Whether the terminal reports that it gained focus. */
+    readonly focused: boolean;
+} | {
+    readonly kind: 'reply';
+    /** Complete terminal capability or status reply, retained for negotiation. */
+    readonly sequence: string;
+};
+/** Why a decoder is retaining an incomplete terminal sequence. */
+export type TuiTerminalInputWait = 'escape' | 'sequence' | 'paste';
+/**
+ * Incrementally tokenize raw terminal input without relying on transport chunk boundaries.
+ *
+ * Complete unknown control sequences are discarded. Incomplete sequences remain bounded
+ * until {@link flush} applies the caller's escape timeout.
+ */
+export declare class TuiTerminalInputDecoder {
+    private utf8;
+    private pending;
+    private paste;
+    private pasteBytes;
+    private pasteTruncated;
+    /** The kind of timeout required for the currently retained input, if any. */
+    get waiting(): TuiTerminalInputWait | undefined;
+    /**
+     * Decode one raw terminal chunk.
+     * @param data - UTF-8 input from Ink's raw input emitter or a terminal stream.
+     * @returns complete normalized events in byte-stream order.
+     */
+    push(data: string | Buffer): readonly TuiTerminalInputEvent[];
+    /**
+     * Settle input retained past the escape or incomplete-sequence timeout.
+     * @returns a standalone Escape or bounded paste event; other fragments are discarded.
+     */
+    flush(): readonly TuiTerminalInputEvent[];
+    /** Discard retained sequence and paste state during input-owner teardown. */
+    reset(): void;
+    private drain;
+    private appendPaste;
+}
+/**
+ * Own raw-mode input for one Ink component and dispatch decoder events.
+ * @param handler - current normalized input consumer.
+ * @param initialEvents - events buffered before the Ink input emitter mounted.
+ */
+export declare function useTuiTerminalInput(handler: (event: TuiTerminalInputEvent) => void, initialEvents?: readonly TuiTerminalInputEvent[]): void;
+//# sourceMappingURL=terminal-input.d.ts.map

package/lib/types/terminal-session.d.ts

@@ -0,0 +1,129 @@
+/** Exclusive owner of terminal capability probing, alternate-screen mutation, and restoration. */
+import { type TuiTerminalInputEvent } from './terminal-input.ts';
+/** Process-stream capability set borrowed by one terminal transaction. */
+export interface TuiStreams {
+    /** Interactive key input. */
+    stdin: NodeJS.ReadStream;
+    /** Full-screen renderer output. */
+    stdout: NodeJS.WriteStream;
+    /** Startup and fatal error output. */
+    stderr: NodeJS.WriteStream;
+}
+/** One-based terminal cell where IME preedit text must begin. */
+export interface InputCursorTarget {
+    /** One-based terminal row. */
+    row: number;
+    /** One-based terminal column. */
+    column: number;
+}
+/** Terminal color precision used by semantic renderers. */
+export type TuiTerminalColorDepth = 'none' | 'ansi16' | 'ansi256' | 'truecolor';
+/** Keyboard protocol that the terminal agreed to receive. */
+export type TuiTerminalKeyboardProtocol = 'legacy' | 'kitty';
+/** Capabilities observed or conservatively inferred for one terminal session. */
+export interface TuiTerminalCapabilities {
+    /** Color precision reported by the output stream or `NO_COLOR`. */
+    readonly colorDepth: TuiTerminalColorDepth;
+    /** Enhanced keyboard protocol enabled for this transaction. */
+    readonly keyboardProtocol: TuiTerminalKeyboardProtocol;
+    /** Whether SGR mouse reports may be enabled. */
+    readonly mouse: 'none' | 'sgr';
+    /** Whether focus-in/out reports may be enabled. */
+    readonly focus: boolean;
+    /** Whether bracketed paste may be enabled. */
+    readonly bracketedPaste: boolean;
+    /** Whether OSC terminal strings were accepted during probing. */
+    readonly osc: boolean;
+    /** Whether synchronized output was explicitly confirmed. */
+    readonly synchronizedOutput: boolean;
+    /** Whether the process is inside a verified tmux or SSH environment. */
+    readonly outer: Readonly<{
+        tmux: boolean;
+        ssh: boolean;
+    }>;
+}
+/** Options for the bounded terminal capability probe. */
+export interface TuiTerminalNegotiationOptions {
+    /** Probe deadline in milliseconds; defaults to a short non-blocking window. */
+    readonly timeoutMs?: number;
+    /** Cancellation signal for startup or teardown. */
+    readonly signal?: AbortSignal;
+    /** Environment used only to identify outer transport context. */
+    readonly environment?: NodeJS.ProcessEnv;
+}
+/** Result of one bounded terminal clipboard write. */
+export type TuiClipboardResult = {
+    readonly ok: true;
+    readonly method: 'osc52' | 'tmux-buffer';
+} | {
+    readonly ok: false;
+    readonly reason: 'inactive' | 'unsupported' | 'too-large' | 'write-failed';
+    readonly message: string;
+};
+/** Capabilities used by the compatibility `enter()` call in isolated tests. */
+export declare const DEFAULT_TUI_TERMINAL_CAPABILITIES: TuiTerminalCapabilities;
+/** Full-screen transaction. Ink owns raw mode; this owner restores outer terminal modes. */
+export declare class TerminalSession {
+    readonly streams: TuiStreams;
+    private active;
+    private rawModeHeld;
+    private cursorTarget;
+    private activeModes;
+    private negotiation;
+    private cancelNegotiation;
+    private capabilitiesSnapshot;
+    private bufferedInput;
+    /** Ink-facing output that restores the real terminal cursor after each full-screen render. */
+    readonly rendererOutput: NodeJS.WriteStream;
+    constructor(streams: TuiStreams);
+    /**
+     * Move the real terminal cursor to the active input insertion cell after rendering.
+     * @param target - one-based cell, or `undefined` while no text editor owns input.
+     */
+    setInputCursor(target: InputCursorTarget | undefined): void;
+    /**
+     * Validate the terminal before emitting any control sequence.
+     * @throws when stdin or stdout is not an interactive TTY.
+     */
+    assertInteractive(): void;
+    /**
+     * Probe terminal capabilities without blocking startup beyond a short deadline.
+     * @param options - timeout, cancellation, and outer transport context.
+     * @returns the disposable capability snapshot for this terminal transaction.
+     */
+    negotiate(options?: TuiTerminalNegotiationOptions): Promise<TuiTerminalCapabilities>;
+    /**
+     * Take ordinary input that arrived while terminal replies were being probed.
+     * @returns input events in the original byte-stream order.
+     */
+    takeBufferedInput(): readonly TuiTerminalInputEvent[];
+    /**
+     * Copy bounded text through the negotiated OSC 52 path.
+     * tmux receives the same sequence as buffer integration and decides whether
+     * its configured `set-clipboard` policy also forwards it to the outer terminal.
+     * @param text - complete text selected by a non-secret TUI surface.
+     * @returns the observed local write outcome; terminals do not acknowledge clipboard mutation.
+     */
+    copyToClipboard(text: string): TuiClipboardResult;
+    /**
+     * Enter the alternate screen exactly once after TTY validation.
+     * @param capabilities - negotiated capabilities controlling enabled terminal modes.
+     */
+    enter(capabilities?: TuiTerminalCapabilities): void;
+    /** Restore every terminal mode this application may have enabled, idempotently. */
+    restore(): void;
+    private capabilitiesForEntry;
+    private performNegotiation;
+    private cursorSequence;
+    private createRendererOutput;
+}
+/**
+ * Fold one decoder reply into a capability snapshot.
+ * @param current - current session snapshot.
+ * @param sequence - complete terminal reply consumed by the decoder.
+ * @returns a new immutable snapshot.
+ */
+export declare function applyTuiTerminalReply(current: TuiTerminalCapabilities, sequence: string): TuiTerminalCapabilities;
+/** Process streams used in production; tests replace this object. */
+export declare const terminalInternals: TuiStreams;
+//# sourceMappingURL=terminal-session.d.ts.map