@x-otto/tui 0.0.1-alpha.2 → 0.0.1-alpha.20

package/README.md

@@ -1,16 +1,16 @@
 # @x-otto/tui
 
-## 模块定位
+## Module Purpose
 
-终端 UI 应用层：基于 React + Ink 的组件树，提供流式 Markdown 渲染、权限弹窗、输入栈、消息流等完整的终端交互体验。对接 npm `ink` v7 渲染引擎与 `@x-otto/keybindings` 按键系统。
+The terminal UI application layer: a React + Ink component tree that provides streaming Markdown rendering, permission dialogs, input stack, message flow, and the full terminal interaction experience. Built on the npm `ink` v7 rendering engine, with keybinding, theme, and fuzzy-search systems living in-package (`src/keybindings`, `src/theme`, `src/search`).
 
-## 安装
+## Installation
 
 ```bash
 pnpm add @x-otto/tui
 ```
 
-## 快速开始
+## Quick Start
 
 ```ts
 import { startTui } from '@x-otto/tui'
@@ -18,125 +18,128 @@ import { startTui } from '@x-otto/tui'
 const tui = await startTui({
   stdin: process.stdin,
   stdout: process.stdout,
-  onMessage: async (msg) => { /* 发送到 agent */ },
+  onSubmit: (text) => { /* send to agent */ },
 })
 
-tui.pushMessage({ role: 'assistant', content: 'Hello! I am otto.' })
-tui.showToast('Task completed')
+tui.messages.pushMessage({ role: 'assistant', content: 'Hello! I am otto.' })
+tui.info.showToast('Task completed', 'Done')
 
-await tui.dispose()
+tui.lifecycle.stop()
 ```
 
-## 核心功能
+## Core Features
 
-| 模块            | 功能                                                    |
+| Module            | Function                                                    |
 | --------------- | ------------------------------------------------------- |
-| Store           | 应用状态管理（zustand 驱动，useAppState / createStore） |
-| Input           | 输入栈：Cursor 模型 + InputBuffer + History + Typeahead |
-| Messages        | 消息流：StreamState + QueryGuard + Collapse + Diff      |
-| Dialogs         | 对话框仲裁：权限队列 + Select 状态机 + 弹窗组件         |
-| Components      | 通用组件：App / Welcome / StatusBar / Spinner / Button / DataList |
-| Term            | 终端原语：BracketedPaste / OSC 8/52 / SyncFrame         |
-| Theme           | 调色板 + 图标字符 + Spinner 帧 + 主题预设注册表        |
-| i18n            | 国际化（i18next + react-i18next，中/英文）              |
-| startTui        | 生产入口：从 stdin/WebSocket 启动 TUI 主循环            |
-| printMessages   | 非交互 print 模式（向后兼容）                           |
-
-## 输入栈
-
-| 组件               | 功能                          |
+| Store           | Application state management (zustand-driven, useAppState / makeStore) |
+| Input           | Input stack: Cursor model + InputBuffer + History + Typeahead |
+| Messages        | Message flow: stream commit/coalesce + QueryGuard + Collapse + Diff |
+| Dialogs         | Dialog arbitration: routed permission dialogs + Select state machine + dialog components |
+| Components      | Common components: App / Welcome / StatusBar / Spinner / Button / DataList |
+| Term            | Terminal primitives: BracketedPaste / OSC 8/52 / SyncFrame |
+| Theme           | Color palette + icon glyphs + spinner frames + theme preset registry |
+| i18n            | Internationalization (i18next + react-i18next, zh/en)              |
+| startTui        | Production entry point: launches the TUI main loop from stdin/WebSocket |
+| printMessages   | Non-interactive print mode (backward compatibility)                          |
+
+## Input Stack
+
+| Component          | Function                          |
 | ------------------ | ----------------------------- |
-| BaseTextInput      | 基础文本输入（光标/编辑/粘贴）|
-| PromptInput        | 主提示输入框                  |
-| PromptInputFooter  | 输入框底部状态栏              |
-| HistorySearchInput | 历史搜索输入                  |
-| QueuedCommands     | 排队命令显示                  |
+| TextInput          | Text input (cursor/edit/paste) |
+| PromptInput        | Main prompt input box                  |
+| QueuedCommands     | Queued command display             |
 
-## 消息渲染
+## Message Rendering
 
-| 组件               | 功能                          |
+| Component          | Function                          |
 | ------------------ | ----------------------------- |
-| Message            | 消息容器（角色/折叠/分支）    |
-| Markdown           | Markdown 静态渲染             |
-| StreamingMarkdown  | Markdown 流式渲染（防闪）     |
-| StructuredDiff     | 结构化 diff 渲染              |
-| HighlightedCode    | 语法高亮代码块                |
-| ToolUseLoader      | 工具调用加载动画              |
-| REPLRegion         | REPL 消息区域容器             |
+| Message            | Message container (role/collapse/branch)    |
+| REPLRegion         | REPL message region container             |
+| renderMessageLines | Line-based message rendering (streaming-aware) |
+| renderMarkdownToLines | Markdown → ANSI line rendering       |
+| preloadHighlighter / highlightBlock | Syntax-highlighted code blocks |
 
-## 目录概览
+## Directory Overview
 
 ```
 src/
-  types.ts           # TUI 本地类型桩（不依赖 @x-otto/ai）
-  theme.ts           # THEME / PALETTE / FIGURES / SPINNER_FRAMES
-  startTui.tsx       # 生产入口
-  print-messages.ts   # print 模式
-  compat.ts          # 向后兼容（旧 API shim）
-  index.ts           # barrel 导出
-  store/             # 应用状态管理
-  term/              # 终端原语（paste/keys/OSC）
-  input/             # 输入栈（Cursor/Buffer/History/Typeahead）
-  messages/          # 消息流（Stream/QueryGuard/Collapse/Diff）
-  dialogs/           # 对话框（Permission/Select/Arbiter）
-  components/        # 通用组件（App/Welcome/StatusBar/Spinner）
-tests/               # 20 个测试文件
+  types.ts             # TUI-local type stubs (no dependency on @x-otto/ai)
+  theme.ts             # THEME / PALETTE / FIGURES / SPINNER_FRAMES
+  main.ts              # production entry point (startTui)
+  compat.ts            # backward-compatibility (legacy API shim)
+  index.ts             # barrel export
+  stores/              # application state (zustand: message/stream/task/context/...)
+  term/                # terminal primitives (paste/keys/OSC/sync/scrollback)
+  input/               # input stack (Cursor/Buffer/History/Typeahead)
+  messages/            # message flow (commit/QueryGuard/Collapse/Diff)
+  dialogs/             # dialogs (Permission/Select/Confirm/Alert/...)
+  components/          # common components (App/Welcome/StatusBar/Spinner)
+  panes/               # side panes (Context/Task/Subagents/Sigil/Schedule/...)
+  router/ + routes/    # router-driven views & modal routes (FocusBus/Router/Tabable)
+  overlays/            # overlay components
+  status-bar/          # status bar widgets (provider usage badge, background tasks)
+  keybindings/         # keybinding parsing & overrides
+  history/             # shell history parsing (zsh/bash/fish)
+  search/              # fuzzy search
+  sigil/               # #/@ sigil input completion
+  bootstrap/           # TuiHandle/TuiOptions types + session data-source bridges
+  app/                 # App shell assembly (input/dialog/panel/status regions)
+tests/               # 385 test files
 ```
 
-## 公开导出
+## Public Exports
 
 ```ts
-// 状态管理
-export { createStore, useAppState }
+// State management
+export { useAppState, makeStore }
 export type { Store }
 
-// 终端原语
+// Terminal primitives
 export { BracketedPasteHandler, parseExtendedKey }
 export { osc8Hyperlink, osc8FilePath, osc52Write, beginSyncFrame, endSyncFrame, withSyncFrame }
 export { insertHistory, preWrapLine, displayWidth, guardScrollbackStdout }
 
-// 输入栈
+// Input stack
 export { Cursor, MeasuredText, stringWidth }
 export { createInputBuffer, createInputHistory, createPasteStore }
 export { createCommandRegistry, getCommandSuggestions, applySlashCompletion }
-export { TextInput, PromptInput, QueuedCommands, HistorySearchInput }
+export { TextInput, PromptInput, QueuedCommands }
 export type { InputBuffer, BufferEntry }
 
-// 消息流
-export { createStreamState, reduceStreamEvent, reduceStreamEvents }
+// Message flow
+export { safeCommitBoundary, initStreamCommit, streamCommitStep, makeCoalescer }
 export { createQueryGuard, collapseMessages, toggleCollapse, expandCollapsed }
-export { Markdown, Message, REPLRegion, StructuredDiff, ToolUseLoader, StreamingMarkdown }
+export { Message, REPLRegion }
+export { renderMessageLines, renderMarkdownToLines, preloadHighlighter, highlightBlock }
 export { registerPluginRenderers, clearPluginRenderers }
 
-// 对话框
-export { createDialogArbiter, createPermissionQueue, createSelectState }
+// Dialogs
+export { createSelectState }
 export { Select, PermissionDialogDialog, BashPermissionDialog, ConfirmDialog, AlertDialog, PromptDialog, MemoryDialog }
 
-// 组件
+// Components
 export { App, Home, Spinner, Button, DataList }
 export type { ButtonProps, ButtonVariant, ButtonColor, DataListProps }
 
-// 主题
+// Theme
 export { THEME, PALETTE, STATUS, FIGURES, SPACING, LAYOUT, DIALOG_BORDER, PANEL_BORDER }
 export { ThemeRegistry, createBuiltinThemeRegistry }
 export type { ThemePreset, ThemePresetInput, ThemePresetSelection, ThemeAppearance }
 
-// 搜索
+// Search
 export { rankCandidates, rankNamedItems, rankLabeledItems, createIncrementalSearcher }
 
-// Inspect
-export { createInspectorStore, InspectorPane, buildEventTree, buildToolList }
-
 // i18n
 export { detectLanguage, t, i18next, initI18n }
 export type { Lang, LangMode }
 
-// 入口
+// Entry points
 export { startTui }
 export { printMessages }
 ```
 
-## 开发命令
+## Development Commands
 
 ```bash
 pnpm --filter @x-otto/tui build
@@ -145,6 +148,6 @@ pnpm --filter @x-otto/tui test
 pnpm --filter @x-otto/tui clean
 ```
 
-## 关联包
+## Related Packages
 
-`@x-otto/keybindings`
+`@x-otto/interchange`, `@x-otto/session-contract`, `@x-otto/shared`, `@x-otto/env`