@x-otto/tui 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,150 @@
+# @x-otto/tui
+
+## 模块定位
+
+终端 UI 应用层：基于 React + Ink 的组件树，提供流式 Markdown 渲染、权限弹窗、输入栈、消息流等完整的终端交互体验。对接 npm `ink` v7 渲染引擎与 `@x-otto/keybindings` 按键系统。
+
+## 安装
+
+```bash
+pnpm add @x-otto/tui
+```
+
+## 快速开始
+
+```ts
+import { startTui } from '@x-otto/tui'
+
+const tui = await startTui({
+  stdin: process.stdin,
+  stdout: process.stdout,
+  onMessage: async (msg) => { /* 发送到 agent */ },
+})
+
+tui.pushMessage({ role: 'assistant', content: 'Hello! I am otto.' })
+tui.showToast('Task completed')
+
+await tui.dispose()
+```
+
+## 核心功能
+
+| 模块            | 功能                                                    |
+| --------------- | ------------------------------------------------------- |
+| 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 模式（向后兼容）                           |
+
+## 输入栈
+
+| 组件               | 功能                          |
+| ------------------ | ----------------------------- |
+| BaseTextInput      | 基础文本输入（光标/编辑/粘贴）|
+| PromptInput        | 主提示输入框                  |
+| PromptInputFooter  | 输入框底部状态栏              |
+| HistorySearchInput | 历史搜索输入                  |
+| QueuedCommands     | 排队命令显示                  |
+
+## 消息渲染
+
+| 组件               | 功能                          |
+| ------------------ | ----------------------------- |
+| Message            | 消息容器（角色/折叠/分支）    |
+| Markdown           | Markdown 静态渲染             |
+| StreamingMarkdown  | Markdown 流式渲染（防闪）     |
+| StructuredDiff     | 结构化 diff 渲染              |
+| HighlightedCode    | 语法高亮代码块                |
+| ToolUseLoader      | 工具调用加载动画              |
+| REPLRegion         | REPL 消息区域容器             |
+
+## 目录概览
+
+```
+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 个测试文件
+```
+
+## 公开导出
+
+```ts
+// 状态管理
+export { createStore, useAppState }
+export type { Store }
+
+// 终端原语
+export { BracketedPasteHandler, parseExtendedKey }
+export { osc8Hyperlink, osc8FilePath, osc52Write, beginSyncFrame, endSyncFrame, withSyncFrame }
+export { insertHistory, preWrapLine, displayWidth, guardScrollbackStdout }
+
+// 输入栈
+export { Cursor, MeasuredText, stringWidth }
+export { createInputBuffer, createInputHistory, createPasteStore }
+export { createCommandRegistry, getCommandSuggestions, applySlashCompletion }
+export { TextInput, PromptInput, QueuedCommands, HistorySearchInput }
+export type { InputBuffer, BufferEntry }
+
+// 消息流
+export { createStreamState, reduceStreamEvent, reduceStreamEvents }
+export { createQueryGuard, collapseMessages, toggleCollapse, expandCollapsed }
+export { Markdown, Message, REPLRegion, StructuredDiff, ToolUseLoader, StreamingMarkdown }
+export { registerPluginRenderers, clearPluginRenderers }
+
+// 对话框
+export { createDialogArbiter, createPermissionQueue, createSelectState }
+export { Select, PermissionDialogDialog, BashPermissionDialog, ConfirmDialog, AlertDialog, PromptDialog, MemoryDialog }
+
+// 组件
+export { App, Home, Spinner, Button, DataList }
+export type { ButtonProps, ButtonVariant, ButtonColor, DataListProps }
+
+// 主题
+export { THEME, PALETTE, STATUS, FIGURES, SPACING, LAYOUT, DIALOG_BORDER, PANEL_BORDER }
+export { ThemeRegistry, createBuiltinThemeRegistry }
+export type { ThemePreset, ThemePresetInput, ThemePresetSelection, ThemeAppearance }
+
+// 搜索
+export { rankCandidates, rankNamedItems, rankLabeledItems, createIncrementalSearcher }
+
+// Inspect
+export { createInspectorStore, InspectorPane, buildEventTree, buildToolList }
+
+// i18n
+export { detectLanguage, t, i18next, initI18n }
+export type { Lang, LangMode }
+
+// 入口
+export { startTui }
+export { printMessages }
+```
+
+## 开发命令
+
+```bash
+pnpm --filter @x-otto/tui build
+pnpm --filter @x-otto/tui typecheck
+pnpm --filter @x-otto/tui test
+pnpm --filter @x-otto/tui clean
+```
+
+## 关联包
+
+`@x-otto/keybindings`