Chat Messages: components 201-220

docs/components/201-chat-container.md

@@ -0,0 +1,43 @@
+# 201 ChatContainer 对话容器
+
+## 用途
+
+整页对话布局：左侧可选侧栏插槽，右侧为消息区与底部输入区。消息区就是 MessageList：新消息到来时自动滚到底部，用户向上翻看时停止跟随，并在底部显示回到最新按钮。
+
+## 最小示例
+
+```go
+mujica.ChatContainer(c, &chat, len(msgs), mujica.ChatContainerOptions{
+	List:  mujica.MessageListOptions{ID: func(i int) string { return msgs[i] }},
+	Input: func() { ui.Text(c, "Composer goes here") },
+}, func(i int) { ui.Text(c, msgs[i]) })
+```
+
+签名：`func ChatContainer(c *ui.Context, s *MessageListState, n int, opts ChatContainerOptions, row func(i int)) MessageListResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `s` | `*MessageListState` | 必填 | 消息区的位置与已读状态，由调用方持有。 |
+| `n / row` | `int / func(i int)` | 必填 | 消息数量与第 i 条消息的构建函数；只构建可见消息。 |
+| `List` | `MessageListOptions` | `ID` 必填 | 传给消息列表的选项，见 202。 |
+| `Input` | `func()` | nil | 输入区插槽，位于消息区下方，带上边线。 |
+| `Sidebar` | `func()` | nil | 侧栏插槽；nil 时不显示侧栏。 |
+| `SidebarWidth` | `float32` | 260 | 侧栏宽度 DIP；负数 panic。 |
+
+## 状态
+
+消息区跟随底部 / 用户上翻后停止跟随；离开底部时出现带未读数的回到最新按钮。
+
+## 事件
+
+返回的 `MessageListResult.Unread()` 给出离开底部后新到的消息数。
+
+## 键盘操作
+
+Tab 在侧栏、消息与输入区之间移动；消息区获得焦点后滚轮与 PageUp/PageDown（Linux、Windows）滚动。
+
+## 限制
+
+- 侧栏宽度固定，不提供拖动调整；需要时用 SplitPane（008）包裹。

docs/components/202-message-list.md

@@ -0,0 +1,42 @@
+# 202 MessageList 消息列表
+
+## 用途
+
+虚拟化的消息列表，基于 MyGo `ui.List`：只构建可见消息，以稳定消息 ID 保持位置；从底部开始并跟随新消息，用户上翻后停止跟随，并显示新消息提示；可按日期插入分隔。
+
+## 最小示例
+
+```go
+r := mujica.MessageList(c, &list, len(ids), mujica.MessageListOptions{
+	ID: func(i int) string { return ids[i] },
+}, func(i int) { ui.Text(c, "Message "+ids[i]) })
+fmt.Println("unread", r.Unread())
+```
+
+签名：`func MessageList(c *ui.Context, s *MessageListState, n int, opts MessageListOptions, row func(i int)) MessageListResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `ID` | `func(i int) string` | 必填 | 消息的稳定 ID；在上方插入旧消息时视野中的消息保持不动。ID 须唯一。 |
+| `Date` | `func(i int) time.Time` | nil | 设置后在每个新日期的第一条消息前显示“今天 / 昨天 / 日期”分隔。 |
+| `Label` | `func(i int) string` | nil | 消息的无障碍名称，也用于键入定位。 |
+| `n` | `int` | 必填 | 消息数；负数 panic。 |
+
+## 状态
+
+跟随底部；离开底部时底部居中出现 ScrollToBottomButton（含未读数）；点击后回到底部并清零。
+
+## 事件
+
+`Unread()`：离开底部后新增的消息数。`MessageListState.ScrollToEnd()` 与 `AtEnd()` 供调用方控制。
+
+## 键盘操作
+
+列表获得焦点后，滚轮、方向键与 PageUp/PageDown 滚动；回到最新按钮可用 Tab 聚焦，Enter 或 Space 触发。
+
+## 限制
+
+- 不检查 ID 是否重复（逐帧检查 10 万条代价过高）；重复 ID 会让两条消息共享状态。
+- 消息高度由 MyGo 在显示时测量，未显示消息按已测高度估算，长距离跳转时滚动条可能微调。

docs/components/203-message-bubble.md

@@ -0,0 +1,41 @@
+# 203 MessageBubble 消息气泡
+
+## 用途
+
+按角色框住一条消息：用户靠右、Selection 底色；助手靠左、Surface 底与细边；系统居中、灰色小字；错误带 Danger 边框与警示图标。头像与名称为插槽，宽度可限制。
+
+## 最小示例
+
+```go
+mujica.MessageBubble(c, mujica.MessageAssistant, mujica.MessageBubbleOptions{Name: "Herald"}, func() {
+	ui.Text(c, "The ball begins at nine.")
+})
+```
+
+签名：`func MessageBubble(c *ui.Context, role MessageRole, opts MessageBubbleOptions, content func()) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `role` | `MessageRole` | 必填 | `MessageUser`、`MessageAssistant`、`MessageSystem`、`MessageError`。 |
+| `Name` | `string` | "" | 显示在气泡上方的名称。 |
+| `Avatar` | `func()` | nil | 头像插槽，用户在右侧、其他角色在左侧；系统消息不显示。 |
+| `MaxWidth` | `float32` | 560 | 气泡最大宽度 DIP；负数 panic。 |
+| `content` | `func()` | 必填 | 气泡内容，如 MarkdownView 或 StreamingText。 |
+
+## 状态
+
+四种角色外观；错误角色同时使用图标、边框与文字，不只依赖颜色。
+
+## 事件
+
+无；交互由内容与 MessageActions 提供。
+
+## 键盘操作
+
+气泡本身不获取焦点；内容中的链接、按钮按 Tab 顺序访问。辅助技术读到“角色，名称”分组。
+
+## 限制
+
+- 气泡不自带操作栏；把 MessageActions 放在 content 中或气泡下方。

docs/components/204-message-header.md

@@ -0,0 +1,37 @@
+# 204 MessageHeader 消息头
+
+## 用途
+
+在消息上方显示模型名、时间与状态（发送中、生成中、已发送、失败），状态同时用图标和文字表达。
+
+## 最小示例
+
+```go
+mujica.MessageHeader(c, mujica.MessageHeaderOptions{Model: "herald-2", Time: time.Now(), Status: mujica.MessageSent})
+```
+
+签名：`func MessageHeader(c *ui.Context, opts MessageHeaderOptions) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Model` | `string` | "" | 模型名，加粗；空则不显示。 |
+| `Time` | `time.Time` | 零值 | 时间，按 `15:04` 显示；零值不显示。 |
+| `Status` | `MessageStatus` | `MessageNoStatus` | `MessageSending`、`MessageStreaming`、`MessageSent`、`MessageFailed`；未知值 panic。 |
+
+## 状态
+
+生成中显示菱形加载标记（减少动画时静止）；失败用 Danger 色并带警示图标。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点。
+
+## 限制
+
+- 时间格式固定为 24 小时制时分，日期由 MessageList 的日期分隔显示。

docs/components/205-streaming-text.md

@@ -0,0 +1,38 @@
+# 205 StreamingText 流式文本
+
+## 用途
+
+显示随流式输出不断增长的文本。可平滑出字（按速率逐字显示），可显示流式光标；减少动画时直接显示全部文本。文本被替换为不以旧文本开头的内容时，从共同前缀继续。
+
+## 最小示例
+
+```go
+mujica.StreamingText(c, reply, mujica.StreamingTextOptions{Streaming: true, Smooth: true})
+```
+
+签名：`func StreamingText(c *ui.Context, text string, opts StreamingTextOptions) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `text` | `string` | 必填 | 当前收到的全部文本。 |
+| `Streaming` | `bool` | false | 在文本末尾显示 AccentText 色的静态光标 ▍。 |
+| `Smooth` | `bool` | false | 新到的文本按 Rate 逐字显示；关闭时立即显示。 |
+| `Rate` | `float64` | 80 | 平滑出字速度，字符/秒；负数 panic。 |
+
+## 状态
+
+出字中 / 完成；减少动画时始终为完成。光标不闪烁，避免装饰性循环。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点。辅助技术读到的名称始终是完整文本。
+
+## 限制
+
+- 只渲染纯文本；Markdown 内容请交给 MarkdownView（206），它的增量解析同样适合流式输出。

docs/components/206-markdown-view.md

@@ -0,0 +1,39 @@
+# 206 MarkdownView Markdown 视图
+
+## 用途
+
+渲染 Markdown 子集：标题、段落、粗体、斜体、删除线、行内代码、有序与无序列表（含缩进层级）、引用、链接、围栏代码块（交给 CodeBlock）、表格（交给 TableBlock）与分隔线（菱形饰线）。解析器在 `internal/markdown.go`，按块增量解析：新文本只是在旧文本后追加时，只重新解析最后一块，已完成的块保持不变。
+
+## 最小示例
+
+```go
+if url, ok := mujica.MarkdownView(c, "# Decree\n\nSee **the guide** at [the court](https://example.com).").Link(); ok {
+	fmt.Println("open", url)
+}
+```
+
+签名：`func MarkdownView(c *ui.Context, src string) MarkdownResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `src` | `string` | 必填 | Markdown 源文本；流式输出时每帧传入增长后的全文即可。 |
+
+## 状态
+
+围栏未闭合的代码块按已收到的内容显示；未闭合的强调标记按字面显示，闭合后再加样式。
+
+## 事件
+
+`Link()` 返回本帧被点击或用 Enter 激活的链接地址；打开链接由调用方决定。
+
+## 键盘操作
+
+链接可用 Tab 聚焦，Enter 激活；代码块与表格的按钮按 Tab 顺序访问。
+
+## 限制
+
+- 只支持上述子集：不支持 HTML、图片、脚注、任务列表、Setext 标题、链接引用定义，列表项内不支持多段落。
+- 表格单元格按纯文本显示，不解析行内样式。
+- 源文本被整体替换（不是在末尾追加）时重新解析全部块。

docs/components/207-code-block.md

@@ -0,0 +1,39 @@
+# 207 CodeBlock 代码块
+
+## 用途
+
+显示代码：语言标签、可选行号、基础语法着色（`internal.Highlight`，支持 go、javascript、typescript、python、json、shell、sql），复制、折叠与自动换行切换。
+
+## 最小示例
+
+```go
+mujica.CodeBlock(c, "func bow() {}", mujica.CodeBlockOptions{Language: "go", LineNumbers: true})
+```
+
+签名：`func CodeBlock(c *ui.Context, code string, opts CodeBlockOptions) CopyResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Language` | `string` | ""（显示“文本”） | 着色语言；未知语言按纯文本显示。 |
+| `LineNumbers` | `bool` | false | 显示右对齐的行号。 |
+| `Wrap` | `bool` | false | 自动换行的初始状态；关闭时横向滚动。 |
+| `Collapsed` | `bool` | false | 折叠的初始状态。 |
+
+## 状态
+
+换行开关以 Selection 底色加边框表示开启；复制后按钮在 2 秒内显示对勾“已复制”；折叠时只显示标题栏，展开按钮写明行数。关键字、字符串、数字、类型使用不同颜色，注释同时使用斜体。
+
+## 事件
+
+`Copied()`：本帧把代码写入了剪贴板。
+
+## 键盘操作
+
+Tab 依次到换行开关、复制、折叠按钮；Space 或 Enter 触发。
+
+## 限制
+
+- 着色是逐行的词法着色，不做语法分析；块注释可跨行。
+- 不做虚拟化，适合消息中的代码片段，不适合上万行文件。

docs/components/208-table-block.md

@@ -0,0 +1,39 @@
+# 208 TableBlock 表格块
+
+## 用途
+
+在消息中显示小型表格：表头加粗，列按内容宽度排列并铺满消息宽度，过宽时横向滚动；可复制为 TSV。
+
+## 最小示例
+
+```go
+if mujica.TableBlock(c, []string{"Guest", "Seat"}, [][]string{{"Marie", "1"}}, mujica.TableBlockOptions{}).Copied() {
+	fmt.Println("copied as TSV")
+}
+```
+
+签名：`func TableBlock(c *ui.Context, header []string, rows [][]string, opts TableBlockOptions) CopyResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `header` | `[]string` | 必填 | 表头；为空 panic。 |
+| `rows` | `[][]string` | nil | 数据行；每行列数必须与表头相同，否则 panic。 |
+| `Align` | `[]ui.Align` | 全部 `ui.Start` | 各列对齐：`ui.Start`、`ui.Center`、`ui.End`；多于列数 panic。 |
+
+## 状态
+
+复制后按钮 2 秒内显示对勾。
+
+## 事件
+
+`Copied()`：本帧写入了 TSV（制表符分列、换行分行；单元格内的制表符与换行替换为空格）。
+
+## 键盘操作
+
+Tab 到复制按钮，Enter 或 Space 复制。
+
+## 限制
+
+- 不排序、不选择；需要这些功能请使用 DataTable（069 起）。

docs/components/209-image-grid.md

@@ -0,0 +1,40 @@
+# 209 ImageGrid 图片网格
+
+## 用途
+
+在消息中排列 1 至 9 张图片：1 张大图，2 与 4 张两列，其余三列。点击已加载的图片打开 ImageViewer；加载中与失败状态复用 Image 组件，失败时可重试。
+
+## 最小示例
+
+```go
+if i, ok := mujica.ImageGrid(c, []mujica.GridImage{{Source: pic, Alt: "Portrait"}}).Retried(); ok {
+	fmt.Println("reload", i)
+}
+```
+
+签名：`func ImageGrid(c *ui.Context, images []GridImage) ImageGridResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `images` | `[]GridImage` | 必填 | 1 至 9 张，否则 panic。 |
+| `Source` | `ui.ImageSource` | nil | 已加载的位图或 SVG。 |
+| `Alt` | `string` | "" | 替代说明，也是按钮名称与查看器标题。 |
+| `Loading / Err` | `bool / error` | false / nil | 调用方的加载中与失败状态。 |
+
+## 状态
+
+已加载、加载中（菱形加载标记）、失败（重试按钮）；只有已加载的图片可点击。
+
+## 事件
+
+`Retried()` 返回本帧点击了重试的图片下标。查看器在组件内部打开与关闭。
+
+## 键盘操作
+
+Tab 聚焦图片，Enter 或 Space 打开查看器；查看器内的键盘操作见 ImageViewer。
+
+## 限制
+
+- 查看器只包含已加载的图片，序号按已加载图片计算。

docs/components/210-file-message.md

@@ -0,0 +1,40 @@
+# 210 FileMessage 文件消息
+
+## 用途
+
+显示消息中的文件：按类型的图标、文件名、大小，以及打开与下载回调。
+
+## 最小示例
+
+```go
+r := mujica.FileMessage(c, mujica.FileMessageOptions{Name: "treaty.pdf", Size: 2621440})
+if r.Downloaded() {
+	fmt.Println("save treaty.pdf")
+}
+```
+
+签名：`func FileMessage(c *ui.Context, opts FileMessageOptions) FileMessageResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Name` | `string` | 必填 | 文件名；为空 panic。 |
+| `Size` | `int64` | 0 | 字节数，按 B、KB、MB、GB 显示（1024 进制）；负数 panic。 |
+| `Type` | `string` | "" | MIME 类型；为空时按扩展名选择图标。 |
+
+## 状态
+
+悬停时文件区域加深；禁用时两个操作都不响应。
+
+## 事件
+
+`Opened()`：点击或在文件区按 Enter。`Downloaded()`：点击下载按钮。
+
+## 键盘操作
+
+Tab 依次到文件区与下载按钮，Enter 或 Space 触发。
+
+## 限制
+
+- 组件不读取文件、不下载：打开与下载由调用方完成。

docs/components/211-audio-message.md

@@ -0,0 +1,41 @@
+# 211 AudioMessage 语音消息
+
+## 用途
+
+语音条：播放/暂停按钮、波形、播放进度与时长。播放由调用方驱动：组件只报告播放切换与跳转请求，调用方更新 Position 与 Playing。波形基于 MyGo `ui.SliderBase`，可拖动与键盘跳转。
+
+## 最小示例
+
+```go
+r := mujica.AudioMessage(c, mujica.AudioMessageOptions{Duration: time.Minute, Position: pos})
+if d, ok := r.Seek(); ok {
+	pos = d
+}
+```
+
+签名：`func AudioMessage(c *ui.Context, opts AudioMessageOptions) AudioMessageResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Duration` | `time.Duration` | 必填 | 时长，必须大于 0。 |
+| `Position` | `time.Duration` | 0 | 当前进度，0 到 Duration 之间，否则 panic。 |
+| `Playing` | `bool` | false | 按钮显示暂停（播放中）或播放。 |
+| `Waveform` | `[]float32` | nil | 0 到 1 的响度采样，按宽度重采样为竖条；为空画平线；越界 panic。 |
+
+## 状态
+
+已播放的竖条为 AccentText，未播放为半透明 TextMuted，当前位置另有一条竖线，进度不只靠颜色表达；右侧显示 `m:ss / m:ss`。
+
+## 事件
+
+`Toggled()`：按下播放或暂停。`Seek()`：点击、拖动或按键请求的新位置。
+
+## 键盘操作
+
+Tab 到播放按钮（Enter 或 Space）与波形；波形上 Left/Right（Up/Down）按时长的 1% 移动，Home、End 到开头与结尾。
+
+## 限制
+
+- 不解码音频、不生成波形：采样由调用方提供。

docs/components/212-link-preview-card.md

@@ -0,0 +1,42 @@
+# 212 LinkPreviewCard 链接预览卡片
+
+## 用途
+
+显示链接的站点、标题、描述与缩略图；元数据由调用方获取。整张卡片是一个按钮，悬停显示完整地址。
+
+## 最小示例
+
+```go
+p := mujica.LinkPreview{URL: "https://example.com", Title: "The Palace", Site: "example.com"}
+if mujica.LinkPreviewCard(c, p).Clicked() {
+	fmt.Println("open", p.URL)
+}
+```
+
+签名：`func LinkPreviewCard(c *ui.Context, p LinkPreview) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `URL` | `string` | 必填 | 链接地址，作为悬停提示。 |
+| `Title` | `string` | 必填 | 标题，最多两行，AccentText 色。 |
+| `Description` | `string` | "" | 描述，最多两行。 |
+| `Site` | `string` | URL | 站点名；为空时显示 URL。 |
+| `Thumbnail` | `ui.ImageSource` | nil | 缩略图，64×64 裁切显示。 |
+
+## 状态
+
+悬停时底色加深；聚焦时显示焦点环。
+
+## 事件
+
+`Clicked()`：点击或 Enter、Space；打开链接由调用方完成。
+
+## 键盘操作
+
+Tab 聚焦，Enter 或 Space 触发。
+
+## 限制
+
+- 组件不联网：标题、描述与缩略图都由调用方提供。

docs/components/213-quote-reply.md

@@ -0,0 +1,38 @@
+# 213 QuoteReply 引用回复
+
+## 用途
+
+显示被引用消息的作者与单行摘要（多余空白折叠，过长省略）；点击跳转到原消息。
+
+## 最小示例
+
+```go
+if mujica.QuoteReply(c, "Marie", "Let them eat cake.").Clicked() {
+	fmt.Println("jump to the quoted message")
+}
+```
+
+签名：`func QuoteReply(c *ui.Context, author, excerpt string) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `author` | `string` | 必填 | 原消息作者；为空 panic。 |
+| `excerpt` | `string` | "" | 原消息摘要；换行与连续空白合并为一个空格。 |
+
+## 状态
+
+左侧 3 DIP AccentText 竖线标明引用；悬停时底色变为 Selection。
+
+## 事件
+
+`Clicked()`：点击或 Enter、Space；跳转由调用方完成（如 MessageList 的 ScrollTo）。
+
+## 键盘操作
+
+Tab 聚焦，Enter 或 Space 触发。辅助技术读到“回复 作者：摘要”。
+
+## 限制
+
+- 只显示一行摘要，不渲染原消息的格式。

docs/components/214-message-actions.md

@@ -0,0 +1,38 @@
+# 214 MessageActions 消息操作
+
+## 用途
+
+消息下方的操作工具栏：复制、重新生成、编辑、赞、踩、朗读、分享，按角色显示：用户消息为复制、编辑；助手消息为复制、重新生成、赞、踩、朗读、分享；系统消息为复制；错误消息为复制、重新生成。
+
+## 最小示例
+
+```go
+if a, ok := mujica.MessageActions(c, mujica.MessageAssistant, mujica.MessageActionsOptions{Feedback: &rating}).Action(); ok {
+	fmt.Println("action", a)
+}
+```
+
+签名：`func MessageActions(c *ui.Context, role MessageRole, opts MessageActionsOptions) MessageActionsResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `role` | `MessageRole` | 必填 | 决定显示哪些操作。 |
+| `Feedback` | `*MessageFeedback` | nil | 赞踩状态；nil 时不显示赞与踩。再次点击已选的赞或踩会取消。 |
+
+## 状态
+
+赞或踩选中时为按下状态：Selection 底色、AccentText 边框与图标；辅助技术读到切换按钮的按下状态。
+
+## 事件
+
+`Action()` 返回本帧的操作：`ActionCopy`、`ActionRegenerate`、`ActionEdit`、`ActionLike`、`ActionDislike`、`ActionSpeak`、`ActionShare`。复制、朗读与分享由调用方执行。
+
+## 键盘操作
+
+整个工具栏是一个 Tab 停靠点，Left/Right 在操作间移动，Home、End 到首末；Enter 或 Space 触发。
+
+## 限制
+
+- 不内置复制内容与朗读：调用方收到操作后自行处理。

docs/components/215-message-editor.md

@@ -0,0 +1,38 @@
+# 215 MessageEditor 消息编辑器
+
+## 用途
+
+编辑已发送的消息：多行文本框加取消与保存。保存时调用方据草稿产生新分支（配合 BranchNavigator）。
+
+## 最小示例
+
+```go
+if mujica.MessageEditor(c, &draft, mujica.MessageEditorOptions{Original: "Hello"}).Saved() {
+	fmt.Println("new branch from", draft)
+}
+```
+
+签名：`func MessageEditor(c *ui.Context, draft *string, opts MessageEditorOptions) MessageEditorResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `draft` | `*string` | 必填 | 正在编辑的文本。 |
+| `Original` | `string` | "" | 原文；草稿与原文相同或只有空白时不能保存。 |
+
+## 状态
+
+保存按钮在内容无效时禁用；文本框保留输入法、撤销与剪贴板行为。
+
+## 事件
+
+`Saved()`：点击保存或 Cmd/Ctrl+Enter。`Canceled()`：点击取消或在文本框中按 Escape。
+
+## 键盘操作
+
+Cmd/Ctrl+Enter 保存，Escape 取消；Tab 依次到文本框、取消、保存。
+
+## 限制
+
+- 不保存历史：分支与原文由调用方保存。

docs/components/216-branch-navigator.md

@@ -0,0 +1,38 @@
+# 216 BranchNavigator 分支切换
+
+## 用途
+
+在一条消息的多个分支间切换，显示“< 2 / 3 >”。
+
+## 最小示例
+
+```go
+if mujica.BranchNavigator(c, &branch, 3).Changed() {
+	fmt.Println("show branch", branch)
+}
+```
+
+签名：`func BranchNavigator(c *ui.Context, index *int, count int) ChoiceResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `index` | `*int` | 必填 | 当前分支，0 起；不在 0 到 count−1 之间时 panic。 |
+| `count` | `int` | 必填 | 分支数，至少 1。 |
+
+## 状态
+
+首末分支时对应箭头禁用；切换时向辅助技术播报“第 n 个分支，共 m 个”。
+
+## 事件
+
+`Changed()`：分支改变。
+
+## 键盘操作
+
+整个控件是一个 Tab 停靠点：Left/Right 切换，Home、End 到第一个与最后一个；箭头按钮只响应指针。
+
+## 限制
+
+- 箭头按钮不进入 Tab 序列，避免到达首末分支时焦点停在禁用按钮上。

docs/components/217-error-message.md

@@ -0,0 +1,40 @@
+# 217 ErrorMessage 错误消息
+
+## 用途
+
+显示失败的回复：标题、原始错误文本（等宽、可选择复制，不改写、不截断）与重试按钮；限流时显示倒计时，倒计时结束前不能重试。
+
+## 最小示例
+
+```go
+opts := mujica.ErrorMessageOptions{RetryAt: time.Now().Add(30 * time.Second)}
+if mujica.ErrorMessage(c, "429 Too Many Requests", opts).Retried() {
+	fmt.Println("send again")
+}
+```
+
+签名：`func ErrorMessage(c *ui.Context, text string, opts ErrorMessageOptions) ErrorMessageResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `text` | `string` | 必填 | 原始错误文本，原样显示；为空 panic。 |
+| `Title` | `string` | “出错了” | 概括失败原因。 |
+| `RetryAt` | `time.Time` | 零值 | 限流解除时间；之前重试按钮禁用并显示“n 秒后重试”与“已限流”。 |
+
+## 状态
+
+可重试 / 限流倒计时；Danger 边框、图标与标题文字共同表示错误。倒计时只在秒数变化时重绘。
+
+## 事件
+
+`Retried()`：按下重试。
+
+## 键盘操作
+
+Tab 到错误文本（可用 Shift+方向键选择、Cmd/Ctrl+C 复制）与重试按钮。
+
+## 限制
+
+- 倒计时依据窗口时钟；调用方的 RetryAt 应来自服务端的 Retry-After。

docs/components/218-thinking-block.md

@@ -0,0 +1,40 @@
+# 218 ThinkingBlock 思考过程
+
+## 用途
+
+可折叠的思考过程：思考中显示加载标记与实时秒数，结束后显示“思考了 n 秒”。默认折叠或展开由调用方传入的 `*open` 初值决定。基于 Collapsible。
+
+## 最小示例
+
+```go
+mujica.ThinkingBlock(c, &open, mujica.ThinkingBlockOptions{Elapsed: 12 * time.Second}, func() {
+	ui.Text(c, "Weigh the guest list.")
+})
+```
+
+签名：`func ThinkingBlock(c *ui.Context, open *bool, opts ThinkingBlockOptions, content func()) ChoiceResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `open` | `*bool` | 必填 | 是否展开；其初值即默认状态。 |
+| `Thinking` | `bool` | false | 思考中：显示加载标记与从 Started 起的秒数。 |
+| `Started` | `time.Time` | 零值 | 思考开始时间；Thinking 时必填，否则 panic。 |
+| `Elapsed` | `time.Duration` | 0 | 思考结束后的总耗时；负数 panic。 |
+
+## 状态
+
+思考中 / 已完成；展开时内容带左侧细线、TextMuted 色。减少动画时加载标记静止，秒数仍每秒更新。
+
+## 事件
+
+`Changed()`：展开状态改变。
+
+## 键盘操作
+
+Tab 聚焦标题，Enter 或 Space 展开与折叠。
+
+## 限制
+
+- 思考中每秒重绘一次以更新秒数；折叠且完成后不再重绘。

docs/components/219-scroll-to-bottom-button.md

@@ -0,0 +1,40 @@
+# 219 ScrollToBottomButton 回到底部按钮
+
+## 用途
+
+离开底部时出现在容器底部居中的圆角按钮，带未读计数；点击回到底部。MessageList 已内置，也可单独用于其他滚动区域。
+
+## 最小示例
+
+```go
+ui.Box(c).Fill().Children(func() {
+	if mujica.ScrollToBottomButton(c, !list.AtEnd(), 3).Clicked() {
+		list.ScrollToEnd()
+	}
+})
+```
+
+签名：`func ScrollToBottomButton(c *ui.Context, away bool, unread int) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `away` | `bool` | 必填 | 是否已离开底部；false 时返回不可见的空元素，其 Clicked 为 false。 |
+| `unread` | `int` | 0 | 未读数，大于 0 时显示；负数 panic。 |
+
+## 状态
+
+出现时 160 毫秒淡入（减少动画时直接显示）；悬停时底色加深。
+
+## 事件
+
+`Clicked()`：点击或 Enter、Space；滚动由调用方完成。
+
+## 键盘操作
+
+Tab 聚焦，Enter 或 Space 触发。辅助技术读到“回到最新，n 条新消息”。
+
+## 限制
+
+- 按钮以绝对定位贴在父元素底部，父元素需要占满滚动区域。

docs/components/220-typing-indicator.md

@@ -0,0 +1,35 @@
+# 220 TypingIndicator 正在输入
+
+## 用途
+
+对方正在输入的提示：三个依次明暗变化的圆点；减少动画时改为静态文字“某某 正在输入…”。
+
+## 最小示例
+
+```go
+mujica.TypingIndicator(c, "Herald")
+```
+
+签名：`func TypingIndicator(c *ui.Context, name string) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `name` | `string` | 必填 | 正在输入的一方；为空 panic。 |
+
+## 状态
+
+动画 / 静态文字；状态角色，辅助技术读到“某某 正在输入…”。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点。
+
+## 限制
+
+- 动画只在显示时请求下一帧，移出界面后停止重绘。