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

package/lib/types/host.d.ts

@@ -0,0 +1,210 @@
+/** Supported DeepSeek Harness imports and optional-host compatibility adapters. */
+import type { FileSystem, FsTarget } from '@deepseek-ai/dsh-fs';
+import type { CallId, ContentBlock as HostContentBlock, LlmRuntime } from '@deepseek-ai/dsh-llm';
+import type { ApprovalRequest as HostApprovalRequest } from '@deepseek-ai/dsh-user-approval';
+import type { SessionEvent, SessionId as HostSessionId } from '@deepseek-ai/dsh-session';
+import type { SubagentRunId, SubagentStopReason } from '@deepseek-ai/dsh-subagent';
+import { settingsNamespace as hostSettingsNamespace } from '@deepseek-ai/dsh-settings';
+/**
+ * Additive event shapes emitted by newer compatible Hosts. Official rc.8 can
+ * replay logs without them, while the TUI remains ready to project them when
+ * a Host provides the enhanced scheduler and delegation lifecycle.
+ */
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        'tool/execution-group': {
+            turn: number;
+            step: number;
+            group: number;
+            mode: 'parallel' | 'exclusive';
+            members: {
+                callId: CallId;
+                name: string;
+                arguments: string;
+            }[];
+            closed: boolean;
+        };
+        'subagent/delegation-start': {
+            runId: SubagentRunId;
+            callId: CallId;
+            childId: HostSessionId;
+            provider: string;
+            label?: string;
+            local: boolean;
+        };
+        'subagent/delegation-end': {
+            runId: SubagentRunId;
+            stopReason: SubagentStopReason;
+            lastAssistantMessage?: HostContentBlock[];
+        };
+    }
+}
+export type { Context } from '@deepseek-ai/cordis';
+export type { InvariantInstaller } from '@deepseek-ai/dsh-invariants';
+export { default as z } from '@deepseek-ai/schemastery';
+export { installModelSelection, } from '@deepseek-ai/dsh-agent';
+export type { Agent, AgentHandle, AgentStatus, ModelSelection, ModelSelectionRef, } from '@deepseek-ai/dsh-agent';
+export { resolveSessionPreset } from '@deepseek-ai/dsh-agent-presets';
+export type { CommandDescriptor, CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands';
+export { JobId } from '@deepseek-ai/dsh-jobs';
+export type { JobSnapshot, JobStatus } from '@deepseek-ai/dsh-jobs';
+export { createUserMessage, errorChain } from '@deepseek-ai/dsh-llm';
+export type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm';
+export { runNativeCommand } from '@deepseek-ai/dsh-native-command';
+export type { PermissionSelect } from '@deepseek-ai/dsh-permission-presets';
+export { isAppendSurfaceEvent, } from '@deepseek-ai/dsh-session/surface';
+export { SESSION_FORMAT_VERSION, SessionId, } from '@deepseek-ai/dsh-session';
+export type { SessionEvent, SessionId as SessionIdType, TodoItem } from '@deepseek-ai/dsh-session';
+export type { SessionProjectionCache } from '@deepseek-ai/dsh-session-projection-cache';
+export type { SessionRecord } from '@deepseek-ai/dsh-session-query';
+export { installSettingsSection } from '@deepseek-ai/dsh-settings';
+/** Validate one TUI-owned settings namespace through the supported Host API. */
+export declare const settingsNamespace: typeof hostSettingsNamespace;
+export type { SubagentDescendantListEntry, SubagentRunEndInfo, SubagentRunInfo, SubagentTimingProjection, } from '@deepseek-ai/dsh-subagent';
+export type { ContextPressureProjection } from '@deepseek-ai/dsh-token-meter';
+export type { ToolCallView, ToolDefinition, ToolResultView } from '@deepseek-ai/dsh-tools';
+export { UserQuestionError } from '@deepseek-ai/dsh-user-questions';
+export type { AskUserQuestionAnswer, AskUserQuestionAnswerItem, AskUserQuestionItem, AskUserQuestionRequest, } from '@deepseek-ai/dsh-user-questions';
+export type { ApprovalOutcome } from '@deepseek-ai/dsh-user-approval';
+/** Why a fresh TUI Agent exists; older supported Hosts ignore this additive field. */
+export type AgentCreateSource = 'startup' | 'clear' | 'compact' | 'rewind';
+/** Bounded path-completion result available on newer Hosts. */
+export interface FsPathCompletionResult {
+    /** Stable workspace-relative matches. */
+    readonly entries: readonly {
+        readonly path: string;
+        readonly type: 'file' | 'directory';
+    }[];
+    /** Whether a provider bound truncated the result. */
+    readonly truncated: boolean;
+}
+/** One optional provider-owned authentication prompt. */
+export type LlmAuthenticationPrompt = {
+    readonly signal?: AbortSignal;
+} & ({
+    readonly type: 'text' | 'secret' | 'manual-code';
+    readonly message: string;
+    readonly placeholder?: string;
+} | {
+    readonly type: 'select';
+    readonly message: string;
+    readonly options: readonly {
+        readonly id: string;
+        readonly label: string;
+        readonly description?: string;
+    }[];
+});
+/** One optional provider-owned authentication progress event. */
+export type LlmAuthenticationEvent = {
+    readonly type: 'info' | 'progress';
+    readonly message: string;
+} | {
+    readonly type: 'auth-url';
+    readonly url: string;
+    readonly instructions?: string;
+} | {
+    readonly type: 'device-code';
+    readonly userCode: string;
+    readonly verificationUri: string;
+    readonly intervalSeconds?: number;
+    readonly expiresInSeconds?: number;
+};
+/** Callbacks borrowed by an optional provider-owned authentication flow. */
+export interface LlmAuthenticationInteraction {
+    readonly signal?: AbortSignal;
+    prompt(prompt: LlmAuthenticationPrompt): Promise<string>;
+    notify(event: LlmAuthenticationEvent): void;
+}
+/** Non-secret authentication state projected by a newer Host. */
+export interface LlmAuthenticationInfo {
+    readonly configured: boolean;
+    readonly source?: string;
+    readonly methods: readonly {
+        readonly id: string;
+        readonly name: string;
+    }[];
+}
+/**
+ * Read provider authentication when the Host exposes that optional seam.
+ * Older Hosts treat registered routes as already configured and offer no login action.
+ * @param llm - active Host LLM runtime.
+ * @param provider - registered provider route.
+ * @returns provider authentication projection or the legacy configured fallback.
+ */
+export declare function hostAuthentication(llm: LlmRuntime, provider: string): Promise<LlmAuthenticationInfo>;
+/**
+ * Run an authentication method previously returned by {@link hostAuthentication}.
+ * @param llm - active Host LLM runtime.
+ * @param provider - registered provider route.
+ * @param method - provider-owned method id.
+ * @param interaction - borrowed TUI callbacks.
+ */
+export declare function hostLogin(llm: LlmRuntime, provider: string, method: string, interaction: LlmAuthenticationInteraction): Promise<void>;
+/**
+ * Complete workspace paths when the Host exposes bounded completion.
+ * Older Hosts return no suggestions while ordinary path submission remains available.
+ * @param fs - active Host filesystem service.
+ * @param root - resolved workspace root.
+ * @param query - workspace-relative query.
+ * @param options - complete traversal and result bounds.
+ * @returns bounded matches, or an empty legacy result.
+ */
+export declare function hostCompletePaths(fs: FileSystem, root: FsTarget, query: string, options: {
+    readonly maxDepth: number;
+    readonly maxItems: number;
+    readonly maxScannedEntries: number;
+    readonly signal?: AbortSignal;
+}): Promise<FsPathCompletionResult>;
+/** One provider-neutral approval presentation projected by newer Hosts. */
+export type ApprovalPresentation = {
+    readonly kind: 'terminal';
+    readonly command: string;
+    readonly cwd?: string;
+    readonly policy?: string;
+} | {
+    readonly kind: 'diff';
+    readonly files: readonly {
+        readonly path: string;
+        readonly additions: number;
+        readonly deletions: number;
+        readonly preview?: readonly string[];
+    }[];
+} | {
+    readonly kind: 'filesystem';
+    readonly path: string;
+    readonly operation: 'read' | 'write' | 'edit' | 'delete' | 'move' | 'other';
+    readonly workspaceRoot?: string;
+} | {
+    readonly kind: 'web';
+    readonly url: string;
+    readonly host: string;
+    readonly method?: string;
+    readonly purpose?: string;
+} | {
+    readonly kind: 'generic';
+    readonly toolName: string;
+    readonly args?: unknown;
+};
+/** Approval request accepted from either the legacy Host or its presentation-aware successor. */
+export type ApprovalRequest = HostApprovalRequest & {
+    readonly presentation?: ApprovalPresentation;
+};
+/** Why a Session event anchor cannot select a complete turn. */
+type SessionForkAnchorUnavailableReason = 'no-completed-turn' | 'anchored-turn-open';
+/** Result of selecting a complete, between-turn Session seed prefix. */
+export type SessionForkAnchorResolution = {
+    readonly kind: 'selected';
+    readonly boundarySeq: number;
+    readonly seedLength: number;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: SessionForkAnchorUnavailableReason;
+};
+/**
+ * Map a human event anchor to the complete turn prefix retained by a rewind.
+ * @param events - contiguous durable Session log.
+ * @param atSeq - optional event sequence inside the turn to retain.
+ * @returns safe seed boundary or why no completed turn is available.
+ */
+export declare function resolveSessionForkAnchor(events: readonly SessionEvent[], atSeq?: number): SessionForkAnchorResolution;
+//# sourceMappingURL=host.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `@lingxi-ai-cn/dsh-tui-runtime` — one full-screen terminal frontend over an owned,
+ * in-process Agent and its durable Session log.
+ */
+import { z, type Context } from './host.ts';
+export declare const name = "tui";
+export declare const inject: string[];
+/** TUI application configuration resolved from its startup provider. */
+export interface Config {
+    /** Persisted TUI Session to resume; absent creates a new Session. */
+    resume?: string;
+    /** Maximum Session rows mounted in the resume picker. */
+    maxResumeOptions?: number;
+    /** Maximum concurrent metadata reads in one resume scan. */
+    resumeScanConcurrency?: number;
+}
+export declare const Config: z<Config>;
+/** Mount one TUI application lifecycle. */
+export declare function apply(ctx: Context, config: Config): void;
+export type { TranscriptCompactionNode, TranscriptNode, TranscriptTextNode, TranscriptTodoNode, TranscriptToolGroupNode, TranscriptToolNode, } from './transcript.ts';
+export { foldTranscript, TuiTranscriptProjectionCache } from './transcript.ts';
+export { TuiTranscriptDetailCache, tuiTranscriptDetailText } from './detail.ts';
+export { createComposerState, deleteComposerText, insertComposerPasteReference, insertComposerText, isLargeComposerPaste, layoutComposer, materializeComposerText, moveComposerCursor, redoComposerEdit, replaceComposerText, restoreTuiComposerDraft, toggleTuiComposerStash, traverseComposerHistory, tuiComposerDraft, undoComposerEdit, } from './composer.ts';
+export { DEFAULT_TUI_SETTINGS, resolveTuiTheme, TUI_SETTINGS_NAMESPACE, TUI_SETTINGS_SCHEMA, TUI_THEME_PREFERENCES, TuiThemeProvider, useTuiTheme, } from './theme.tsx';
+export type { TuiSemanticThemeTokens, TuiSettings, TuiTheme, TuiThemePreference, } from './theme.tsx';
+export type { TuiComposerDraft, TuiComposerEditHistory, TuiComposerEditKind, TuiComposerPasteReference, TuiComposerSnapshot, TuiComposerStashTransition, } from './composer.ts';
+export { cancelTuiHistorySearch, nextTuiHistorySearchMatch, startTuiHistorySearch, tuiHistorySearchResult, updateTuiHistorySearchQuery, } from './history-search.ts';
+export type { TuiHistorySearchResult, TuiHistorySearchState } from './history-search.ts';
+export { normalizeTuiTranscriptSearchText, resolveTuiTranscriptSearchHit, TuiTranscriptSearchIndex, tuiTranscriptSearchSegments, } from './transcript-search.ts';
+export type { TuiTranscriptSearchDocument, TuiTranscriptSearchHit, TuiTranscriptSearchSegment, } from './transcript-search.ts';
+export { moveTuiFooterSelection, tuiFooterItems, tuiFooterStatusLine, tuiSelectedFooterLine, visibleTuiFooterItems, } from './footer.ts';
+export type { TuiFooterItemDescriptor, TuiFooterItemId, TuiFooterSources, TuiFooterTranscriptPosition, } from './footer.ts';
+export { terminalMarkdownText } from './markdown.ts';
+export { terminalSafe } from './sanitize.ts';
+export { filterTuiResumeCandidates, formatTuiRelativeTime, sortTuiResumeCandidates, summarizeTuiResumeCandidate, } from './resume.ts';
+export type { TuiResumeCandidate, TuiResumeDialogSnapshot, TuiResumeScope, } from './resume.ts';
+export { resolveTuiSessionExportDirectory } from './session-export.ts';
+export type { TuiSessionExportDialogSnapshot, TuiSessionExportPhase } from './session-export.ts';
+export { tuiRewindCandidates } from './rewind.ts';
+export type { TuiRewindCandidate, TuiRewindDialogSnapshot } from './rewind.ts';
+export { acceptTuiSuggestion, commandSuggestionState, moveTuiSuggestion, pathSuggestionQuery, pathSuggestionState, visibleTuiSuggestions, } from './suggestion.ts';
+export type { TuiPathSuggestionQuery, TuiSuggestionAcceptance, TuiSuggestionItem, TuiSuggestionKind, TuiSuggestionState, TuiSuggestionStatus, } from './suggestion.ts';
+export { effectiveTuiInteractionDescriptors, matchTuiInteractionAction, resolveTuiInteractionContext, resolveTuiInteractionRegistry, TUI_INTERACTION_ACTION_IDS, TUI_INTERACTION_CONTEXT_PRIORITY, TUI_INTERACTION_REGISTRY, TUI_KEYBINDING_OVERRIDES_SCHEMA, tuiInteractionHelpLines, validateTuiKeybindingOverrides, } from './keybindings.ts';
+export type { TuiInteractionActionId, TuiInteractionBinding, TuiInteractionCapabilities, TuiInteractionContext, TuiInteractionDescriptor, TuiInteractionHelpLine, TuiInteractionModeState, TuiKeybindingOverrides, TuiKeypress, } from './keybindings.ts';
+export { formatTuiPluginHubRelativeTime, formatTuiPluginHubStars, tuiPluginHubCardHeight, tuiPluginHubCardLayout, tuiPluginHubDetailLines, tuiPluginHubInstalledRows, tuiPluginHubNextSort, tuiPluginHubCategoryLabel, tuiPluginHubNextCategory, tuiPluginHubPlanLines, tuiPluginHubRows, tuiPluginHubSortLabel, } from './plugin-hub.ts';
+export type { TuiPluginHubCard, TuiPluginHubCardLayout, TuiPluginHubDetailLine, TuiPluginHubDialogSnapshot, TuiPluginHubLineTone, TuiPluginHubRow, } from './plugin-hub.ts';
+export { InteractionStore, SessionEventStore } from './store.ts';
+export { TerminalSession } from './terminal-session.ts';
+export { applyTuiTerminalReply, DEFAULT_TUI_TERMINAL_CAPABILITIES, } from './terminal-session.ts';
+export type { TuiClipboardResult, TuiTerminalCapabilities, TuiTerminalColorDepth, TuiTerminalKeyboardProtocol, TuiTerminalNegotiationOptions, } from './terminal-session.ts';
+export { TuiAgentViewStateCache } from './agent-view.ts';
+export type { TuiAgentViewDescriptor } from './agent-view.ts';
+export { EMPTY_TUI_WORK_SNAPSHOT, projectTuiWork } from './work.ts';
+export type { TuiObservedSubagentRun, TuiWorkAgentSnapshot, TuiWorkItemState, TuiWorkItemView, TuiWorkProjectionInput, TuiWorkSnapshot, TuiWorkSummary, } from './work.ts';
+export { formatTuiWorkElapsed, formatTuiWorkOwner } from './work-panel.tsx';
+export { previousTranscriptPageAnchor, selectTranscriptPage, selectTranscriptWindow, terminalWrappedLines, TuiTranscriptScrollController, TuiTranscriptViewportIndex, } from './viewport.ts';
+export type { TuiTranscriptViewportAnchor, TuiTranscriptViewportStats, TuiTranscriptVirtualWindow, } from './viewport.ts';
+export { TuiTerminalInputDecoder } from './terminal-input.ts';
+export type { TuiTerminalInputEvent, TuiTerminalInputWait, } from './terminal-input.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,6 @@
+/** Package-owned invariant companion for `@lingxi-ai-cn/dsh-tui-runtime`. */
+import type { Context } from './host.ts';
+export declare const name = "tui-invariant";
+export declare const inject: string[];
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/keybindings.d.ts

@@ -0,0 +1,165 @@
+/** Native-TUI interaction actions, contexts, defaults, and settings overrides. */
+import { z } from './host.ts';
+/** Input ownership contexts supported by the native TUI. */
+export type TuiInteractionContext = 'Global' | 'Composer' | 'Suggestion' | 'HistorySearch' | 'TranscriptSearch' | 'Transcript' | 'Detail' | 'PluginHub' | 'Dialog' | 'Work' | 'Footer' | 'Approval';
+/** Stable action identifiers consumed by input dispatch and help rendering. */
+export type TuiInteractionActionId = 'app.interrupt' | 'view.root' | 'composer.submit' | 'composer.newline' | 'composer.historyPrevious' | 'composer.historyNext' | 'composer.historySearch' | 'composer.transcriptSearch' | 'composer.stash' | 'composer.undo' | 'composer.redo' | 'composer.openModels' | 'composer.openResume' | 'composer.openFooter' | 'composer.cancel' | 'composer.transcriptPreviousPage' | 'composer.transcriptNextPage' | 'composer.transcriptOldest' | 'composer.transcriptLatest' | 'suggestion.previous' | 'suggestion.next' | 'suggestion.accept' | 'suggestion.dismiss' | 'historySearch.next' | 'historySearch.accept' | 'historySearch.cancel' | 'transcriptSearch.next' | 'transcriptSearch.previous' | 'transcriptSearch.accept' | 'transcriptSearch.cancel' | 'transcript.open' | 'transcript.previous' | 'transcript.next' | 'transcript.inspect' | 'transcript.copy' | 'transcript.close' | 'detail.previousPage' | 'detail.nextPage' | 'detail.copy' | 'detail.close' | 'pluginHub.close' | 'pluginHub.previous' | 'pluginHub.next' | 'pluginHub.previousPage' | 'pluginHub.nextPage' | 'pluginHub.accept' | 'pluginHub.toggleView' | 'pluginHub.search' | 'pluginHub.refresh' | 'pluginHub.sort' | 'pluginHub.category' | 'dialog.previous' | 'dialog.next' | 'dialog.accept' | 'dialog.cancel' | 'dialog.previousPage' | 'dialog.nextPage' | 'work.previous' | 'work.next' | 'work.cancel' | 'work.inspect' | 'work.close' | 'footer.previous' | 'footer.next' | 'footer.activate' | 'footer.close' | 'approval.previous' | 'approval.next' | 'approval.previousPage' | 'approval.nextPage' | 'approval.allowOnce' | 'approval.reject' | 'help.open';
+/** One normalized key or command gesture attached to an interaction action. */
+export interface TuiInteractionBinding {
+    /** Stable lowercase sequence used by input matching. */
+    readonly sequence: string;
+    /** User-facing sequence that preserves familiar key spelling. */
+    readonly label: string;
+    /** Whether input dispatch or the command registry owns the gesture. */
+    readonly kind: 'key' | 'command';
+}
+/** One immutable action shown by the interaction help panel. */
+export interface TuiInteractionDescriptor {
+    /** Stable package-owned action identifier. */
+    readonly id: TuiInteractionActionId;
+    /** Input context that owns the action. */
+    readonly context: TuiInteractionContext;
+    /** Concise user-facing action name. */
+    readonly description: string;
+    /** Key and command gestures in this built-in or resolved descriptor. */
+    readonly bindings: readonly TuiInteractionBinding[];
+    /** Optional runtime capability required before help exposes the action. */
+    readonly requires?: 'modelPicker' | 'resumePicker' | 'approval' | 'childView';
+}
+/** Ink key flags used by the pure keybinding matcher. */
+export interface TuiKeypress {
+    /** Ctrl modifier. */
+    readonly ctrl?: boolean;
+    /** Shift modifier. */
+    readonly shift?: boolean;
+    /** Alt/Meta modifier. */
+    readonly meta?: boolean;
+    /** Return key. */
+    readonly return?: boolean;
+    /** Escape key. */
+    readonly escape?: boolean;
+    /** Tab key. */
+    readonly tab?: boolean;
+    /** Up arrow. */
+    readonly upArrow?: boolean;
+    /** Down arrow. */
+    readonly downArrow?: boolean;
+    /** Left arrow. */
+    readonly leftArrow?: boolean;
+    /** Right arrow. */
+    readonly rightArrow?: boolean;
+    /** Page Up key. */
+    readonly pageUp?: boolean;
+    /** Page Down key. */
+    readonly pageDown?: boolean;
+    /** Home key. */
+    readonly home?: boolean;
+    /** End key. */
+    readonly end?: boolean;
+    /** Backspace key. */
+    readonly backspace?: boolean;
+    /** Forward Delete key. */
+    readonly delete?: boolean;
+    /** Bracketed-paste payload rather than a shortcut key. */
+    readonly paste?: boolean;
+    /** Super or Command modifier reported by an enhanced keyboard protocol. */
+    readonly super?: boolean;
+    /** Hyper modifier reported by an enhanced keyboard protocol. */
+    readonly hyper?: boolean;
+}
+/** Runtime facts that select the one non-global input owner. */
+export interface TuiInteractionModeState {
+    /** Approval currently owns input. */
+    readonly approval: boolean;
+    /** Help or structured-question dialog currently owns input. */
+    readonly dialog: boolean;
+    /** Background-work panel currently owns input. */
+    readonly work: boolean;
+    /** A bounded transcript detail is open. */
+    readonly detail: boolean;
+    /** The read-only Plugin Hub panel owns input. */
+    readonly pluginHub?: boolean;
+    /** Transcript browse mode is active. */
+    readonly transcript: boolean;
+    /** Complete-transcript search is active. */
+    readonly transcriptSearch: boolean;
+    /** Submitted-history search is active. */
+    readonly historySearch: boolean;
+    /** A suggestion query is active. */
+    readonly suggestion: boolean;
+    /** Actionable footer navigation is active. */
+    readonly footer: boolean;
+}
+/** Capabilities used to remove unavailable actions from interaction help. */
+export interface TuiInteractionCapabilities {
+    /** The effective command registry provides the model picker. */
+    readonly modelPicker: boolean;
+    /** The effective command registry provides the Session picker. */
+    readonly resumePicker: boolean;
+    /** The TUI composition provides approval interaction. */
+    readonly approval: boolean;
+    /** A child Agent transcript is the active view. */
+    readonly childView: boolean;
+}
+/** One preformatted physical row in the bounded interaction help panel. */
+export interface TuiInteractionHelpLine {
+    /** Stable React key. */
+    readonly key: string;
+    /** One terminal row of help text. */
+    readonly text: string;
+    /** Visual role used by the renderer. */
+    readonly kind: 'heading' | 'binding' | 'description';
+}
+/** Fixed input-priority order; Global escape actions are checked before the active modal context. */
+export declare const TUI_INTERACTION_CONTEXT_PRIORITY: readonly TuiInteractionContext[];
+/** Built-in bindings used by dispatch and help when settings do not override an action. */
+export declare const TUI_INTERACTION_REGISTRY: readonly TuiInteractionDescriptor[];
+/** Per-action key replacements; command gestures remain attached to their action. */
+export type TuiKeybindingOverrides = Readonly<Partial<Record<TuiInteractionActionId, readonly string[]>>>;
+/** Stable action ids accepted as keys in {@link TuiKeybindingOverrides}. */
+export declare const TUI_INTERACTION_ACTION_IDS: readonly TuiInteractionActionId[];
+/** Schema for canonical lowercase key sequences keyed by known action id. */
+export declare const TUI_KEYBINDING_OVERRIDES_SCHEMA: z<TuiKeybindingOverrides>;
+/**
+ * Reject ambiguous or unsafe effective bindings that the structural schema cannot express.
+ * @param overrides - schema-validated per-action key replacements.
+ * @throws when one action repeats a key, two actions in one context share a key, or Ctrl+C could be removed.
+ */
+export declare function validateTuiKeybindingOverrides(overrides: TuiKeybindingOverrides): void;
+/**
+ * Replace configured key gestures while retaining command gestures and descriptor metadata.
+ * @param overrides - schema-validated per-action key replacements.
+ * @returns one deeply immutable registry consumed by both dispatch and help.
+ * @throws when the effective registry is ambiguous or removes the Ctrl+C safety path.
+ */
+export declare function resolveTuiInteractionRegistry(overrides: TuiKeybindingOverrides): readonly TuiInteractionDescriptor[];
+/**
+ * Resolve the highest-priority non-global input owner.
+ * @param state - active local and modal modes.
+ * @returns the one context allowed to consume ordinary input.
+ */
+export declare function resolveTuiInteractionContext(state: TuiInteractionModeState): Exclude<TuiInteractionContext, 'Global'>;
+/**
+ * Match an Ink key event against one effective registry for one context.
+ * @param context - current input owner.
+ * @param input - Ink input text or terminal control sequence.
+ * @param keypress - Ink key flags.
+ * @param registry - effective bindings; defaults to the built-in registry.
+ * @returns the matching action id, or `undefined` for ordinary text and unbound keys.
+ */
+export declare function matchTuiInteractionAction(context: TuiInteractionContext, input: string, keypress: TuiKeypress, registry?: readonly TuiInteractionDescriptor[]): TuiInteractionActionId | undefined;
+/**
+ * Filter interaction help to actions supported by the current composition.
+ * @param capabilities - effective model-picker, Session-picker, and approval availability.
+ * @param registry - effective bindings; defaults to the built-in registry.
+ * @returns immutable descriptors in stable context and registry order.
+ */
+export declare function effectiveTuiInteractionDescriptors(capabilities: TuiInteractionCapabilities, registry?: readonly TuiInteractionDescriptor[]): readonly TuiInteractionDescriptor[];
+/**
+ * Project effective descriptors into fixed physical rows for a bounded panel.
+ * @param descriptors - effective immutable action descriptors.
+ * @param columns - available panel columns.
+ * @returns stable heading, binding, and description rows.
+ */
+export declare function tuiInteractionHelpLines(descriptors: readonly TuiInteractionDescriptor[], columns: number): readonly TuiInteractionHelpLine[];
+//# sourceMappingURL=keybindings.d.ts.map

package/lib/types/markdown.d.ts

@@ -0,0 +1,9 @@
+/** Host-only GFM projection for readable terminal text. */
+/**
+ * Remove Markdown presentation syntax while retaining readable block structure.
+ * @param markdown - untrusted GFM source.
+ * @param width - available terminal cells used for narrow table projection.
+ * @returns terminal-safe text with readable block structure and no raw HTML or resource targets.
+ */
+export declare function terminalMarkdownText(markdown: string, width?: number): string;
+//# sourceMappingURL=markdown.d.ts.map

package/lib/types/open-url.d.ts

@@ -0,0 +1,9 @@
+/** Cross-platform default-browser hand-off without invoking a shell. */
+/**
+ * Open one HTTP(S) URL with the operating system's default browser.
+ * @param value - provider-issued authentication URL.
+ * @param signal - authentication lifetime.
+ * @returns fulfillment after the native launcher accepts the URL.
+ */
+export declare function openExternalUrl(value: string, signal: AbortSignal): Promise<void>;
+//# sourceMappingURL=open-url.d.ts.map

package/lib/types/plugin-hub.d.ts

@@ -0,0 +1,158 @@
+/** Pure Plugin Hub panel state and bounded text projections for the native TUI. */
+import type { InstalledPluginSnapshot, PluginCatalogSort, PluginChangePlan, PluginCategory, PluginDetail, PluginHubProgress, PluginHubStatus, PluginSearchPage, PluginVerification } from '@lingxi-ai-cn/dsh-plugin-hub';
+import type { InputCursorTarget } from './terminal-session.ts';
+/** Plugin Hub panel snapshot across remote discovery and local profile lifecycle views. */
+export interface TuiPluginHubDialogSnapshot {
+    readonly generation: number;
+    /** False when profile changes must be performed by the external DSH CLI. */
+    readonly profileMutations?: boolean | undefined;
+    readonly phase: 'loading' | 'browse' | 'detail-loading' | 'detail' | 'planning' | 'confirm' | 'staging' | 'handoff' | 'error';
+    readonly view: 'discover' | 'installed';
+    readonly initialQuery: string;
+    readonly sort: PluginCatalogSort;
+    readonly category?: PluginCategory | undefined;
+    readonly page?: PluginSearchPage | undefined;
+    readonly installed?: InstalledPluginSnapshot | undefined;
+    readonly detail?: PluginDetail | undefined;
+    readonly plan?: PluginChangePlan | undefined;
+    readonly status?: PluginHubStatus | undefined;
+    readonly progress?: PluginHubProgress | undefined;
+    readonly loadingMore?: boolean | undefined;
+    readonly error?: string | undefined;
+}
+/**
+ * Format one provider-neutral catalog ordering for the TUI status line.
+ * @param sort - catalog ordering to label.
+ * @returns human-readable ordering label.
+ */
+export declare function tuiPluginHubSortLabel(sort: PluginCatalogSort): string;
+/**
+ * Advance the catalog ordering without exposing provider cursor internals.
+ * @param sort - current catalog ordering.
+ * @returns next ordering in the stable TUI cycle.
+ */
+export declare function tuiPluginHubNextSort(sort: PluginCatalogSort): PluginCatalogSort;
+/**
+ * Format the selected Registry-owned category for the TUI status line.
+ * @param category - selected Registry category, or undefined for all categories.
+ * @returns user-facing category label.
+ */
+export declare function tuiPluginHubCategoryLabel(category: PluginCategory | undefined): string;
+/**
+ * Advance the category filter, returning null to clear it after the final category.
+ * @param category - current category, or undefined for all categories.
+ * @returns next category, or null when the filter should be cleared.
+ */
+export declare function tuiPluginHubNextCategory(category: PluginCategory | undefined): PluginCategory | null;
+/**
+ * Project catalog freshness without hiding a stale search fallback behind a failed status request.
+ * @param snapshot - current controller-owned panel state.
+ * @returns sanitized one-line catalog status.
+ */
+export declare function tuiPluginHubCatalogLine(snapshot: TuiPluginHubDialogSnapshot): string;
+/** One sanitized structured Plugin Hub card projected for Ink. */
+export interface TuiPluginHubCard {
+    readonly id: string;
+    readonly kind: 'catalog' | 'installed';
+    readonly displayName: string;
+    readonly packageName: string;
+    readonly summary: string;
+    readonly version?: string | undefined;
+    readonly categories: readonly string[];
+    readonly categorySource?: string | undefined;
+    readonly packageKind?: string | undefined;
+    readonly kindSource?: string | undefined;
+    readonly primaryLanguage?: string | undefined;
+    readonly surfaces: readonly string[];
+    readonly stars?: number | undefined;
+    readonly updatedAt?: string | undefined;
+    readonly installable: boolean;
+    readonly verificationLevel: PluginVerification['level'];
+    readonly selected: boolean;
+}
+/** Backward-compatible export name for the structured card. */
+export type TuiPluginHubRow = TuiPluginHubCard;
+/** Responsive strings consumed by the Ink card renderer. */
+export interface TuiPluginHubCardLayout {
+    readonly height: 2 | 3;
+    readonly displayName: string;
+    readonly badges: string;
+    readonly summary: string;
+    readonly metadata?: string | undefined;
+    readonly physicalLines: readonly string[];
+}
+/** Semantic tone used by one bounded Plugin Hub detail physical line. */
+export type TuiPluginHubLineTone = 'default' | 'muted' | 'accent' | 'success' | 'warning' | 'error';
+/** One physical line projected from a semantic Plugin Hub detail or confirmation entry. */
+export interface TuiPluginHubDetailLine {
+    readonly kind: 'title' | 'summary' | 'section' | 'field' | 'warning' | 'body' | 'blank';
+    readonly tone: TuiPluginHubLineTone;
+    readonly text: string;
+}
+/**
+ * Resolve the fixed physical height shared by catalog windowing and rendering.
+ * @param columns - active terminal columns.
+ * @returns three rows for wide terminals and two rows otherwise.
+ */
+export declare function tuiPluginHubCardHeight(columns: number): 2 | 3;
+/**
+ * Format a finite non-negative Star count for compact catalog display.
+ * @param stars - Registry Star count.
+ * @returns compact count, or undefined for unusable input.
+ */
+export declare function formatTuiPluginHubStars(stars: number | undefined): string | undefined;
+/**
+ * Format catalog activity relative to a fixed caller clock.
+ * @param value - Registry timestamp.
+ * @param now - comparison clock in milliseconds.
+ * @returns bounded relative label, or undefined for invalid/future values.
+ */
+export declare function formatTuiPluginHubRelativeTime(value: string | undefined, now?: number): string | undefined;
+/**
+ * Resolve the real terminal cursor cell for the fixed-height Discover query editor.
+ * @param query - append-only process-local search query.
+ * @param columns - active terminal columns.
+ * @returns one-based terminal cell after the visible query suffix.
+ */
+export declare function tuiPluginHubQueryCursor(query: string, columns: number): InputCursorTarget;
+/**
+ * Project catalog rows without allowing third-party control sequences through.
+ * @param page - current provider page.
+ * @param selectedIndex - zero-based selected row.
+ * @param columns - available terminal columns.
+ * @returns immutable fixed-height rows.
+ */
+export declare function tuiPluginHubRows(page: PluginSearchPage | undefined, selectedIndex: number, columns: number): readonly TuiPluginHubRow[];
+/**
+ * Project active-profile installed truth into fixed-height terminal rows.
+ * @param snapshot - active profile manifest, lockfile, resolved package, bundle, and receipt truth.
+ * @param selectedIndex - zero-based selected package.
+ * @param columns - available terminal columns.
+ * @returns immutable installed rows.
+ */
+export declare function tuiPluginHubInstalledRows(snapshot: InstalledPluginSnapshot | undefined, selectedIndex: number, columns: number): readonly TuiPluginHubRow[];
+/**
+ * Resolve bounded card strings for one terminal width.
+ * @param card - sanitized structured card.
+ * @param columns - active terminal columns.
+ * @param now - fixed activity clock used by deterministic callers.
+ * @returns fixed-height strings and renderer fields.
+ */
+export declare function tuiPluginHubCardLayout(card: TuiPluginHubCard, columns: number, now?: number): TuiPluginHubCardLayout;
+/**
+ * Project one exact trusted mutation plan into bounded confirmation lines.
+ * @param plan - detached plan produced from active-profile truth and a verified descriptor.
+ * @param detail - optional catalog detail retained only for advisory and verification display.
+ * @param columns - available terminal columns.
+ * @returns sanitized confirmation lines.
+ */
+export declare function tuiPluginHubPlanLines(plan: PluginChangePlan | undefined, detail: PluginDetail | undefined, columns: number): readonly TuiPluginHubDetailLine[];
+/**
+ * Project one detail page into bounded sanitized terminal lines.
+ * @param detail - current provider detail.
+ * @param columns - available terminal columns.
+ * @param now - fixed comparison clock for relative activity labels.
+ * @returns bounded sanitized physical lines.
+ */
+export declare function tuiPluginHubDetailLines(detail: PluginDetail | undefined, columns: number, now?: number): readonly TuiPluginHubDetailLine[];
+//# sourceMappingURL=plugin-hub.d.ts.map