wip chat sessions 2

docs/components/241-conversation-list.md

@@ -0,0 +1,56 @@
+# 241 ConversationList · 会话列表
+
+## 用途
+
+按“置顶、今天、昨天、7 天内、更早”分组显示历史会话，只构建可见行，适合十万条以上的会话历史。
+
+## 最小示例
+
+```go
+var state mujica.ConversationListState
+convs := []mujica.ChatConversation{
+	{ID: "1", Title: "Court etiquette", Updated: time.Now()},
+	{ID: "2", Title: "Royal letters", Updated: time.Now().AddDate(0, 0, -30), Pinned: true},
+}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.ConversationList(c, &state, convs, mujica.ConversationListOptions{Label: "History"}, nil).Changed() {
+		log.Println("open", state.Selected)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ConversationList(c *ui.Context, s *ConversationListState, items []ChatConversation, opts ConversationListOptions, row func(conv ChatConversation)) ConversationListView`。`row` 为 nil 时显示标题；传入时可放 `ConversationItem` 等自定义内容。
+
+`ChatConversation`：`ID`（唯一）、`Title`、`Updated`、`Pinned`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Now` | `time.Time` | 零值（窗口时钟） | 分组用的当前时间。 |
+| `Label` | `string` | "" | 列表的无障碍名称。 |
+| `Disabled` | `bool` | false | 禁用：不能选择，退出 Tab 序列。 |
+
+`ConversationListState.Selected` 为当前会话 ID，调用方可直接设置。
+
+## 状态
+
+分组标题（衬线小字、旧金色）、普通行、悬停、选中（Selection 底色 + 左侧菱形）、聚焦（列表焦点环）、禁用。
+
+## 事件
+
+`Changed()`：选中了另一会话，ID 在 `State.Selected`。`Submitted()`：在选中行上按 Enter 或双击。
+
+## 键盘操作
+
+- Tab：聚焦列表。
+- ↑/↓、Home、End：在会话间移动并选择，跳过分组标题；输入首字母定位。
+- Enter：打开当前会话。
+
+## 限制
+
+- 分组与排序只在 `items` 切片（首元素地址或长度）或当天日期变化时重算。原地修改切片元素后，请传入新切片以触发重新分组。
+- 选中行由 MyGo 列表报告选中状态；分组标题由 `ListState.Header` 标记，不可选中。
+- 自定义 `row` 中若含按钮（如 `ConversationItem`），点击由按钮处理，不会改变列表选择；请在按钮事件里设置 `State.Selected`。

docs/components/242-conversation-item.md

@@ -0,0 +1,50 @@
+# 242 ConversationItem · 会话条目
+
+## 用途
+
+一行会话：标题、时间、置顶标记，以及菜单中的重命名（行内编辑）、置顶、导出、删除。删除与导出只回调，由调用方执行。
+
+## 最小示例
+
+```go
+conv := mujica.ChatConversation{ID: "1", Title: "Court etiquette", Updated: time.Now()}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	v := mujica.ConversationItem(c, &conv, mujica.ConversationItemOptions{})
+	if v.Deleted {
+		log.Println("delete", conv.ID)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ConversationItem(c *ui.Context, conv *ChatConversation, opts ConversationItemOptions) ConversationItemView`。`conv` 不能为 nil，`ID` 不能为空。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Today` | `Date` | 零值（窗口时钟） | 决定时间显示为时刻、“昨天”或日期。 |
+| `Selected` | `bool` | false | 显示为当前会话。 |
+| `Disabled` | `bool` | false | 禁用全部操作。 |
+| `Draggable` | `bool` | false | 允许拖到 `ProjectList` 的项目上，携带 `ConversationDrag`。 |
+
+## 状态
+
+默认、悬停、选中（Selection 底色 + 酒红标题）、置顶（星形图标）、行内编辑（输入框酒红边框）、禁用。
+
+## 事件
+
+`ConversationItemView`：`Opened`（点击或 Enter）、`Renamed`（新标题已写入 `conv.Title`）、`PinToggled`、`Exported`、`Deleted`。
+
+## 键盘操作
+
+- Enter/Space：打开会话。
+- F2：行内重命名；输入框中 Enter 确认，Escape 取消；空白标题不会被接受。
+- Delete：请求删除。
+- 菜单按钮：Enter、Space 或 ↓ 打开，方向键移动，Escape 关闭。
+
+## 限制
+
+- 删除没有内置确认；需要确认时由调用方弹出 AlertDialog。
+- 菜单按钮不在条目的 Tab 位之外另设快捷键。

docs/components/243-conversation-search.md

@@ -0,0 +1,53 @@
+# 243 ConversationSearch · 会话搜索
+
+## 用途
+
+按标题与内容搜索会话。查询交给调用方异步执行，结果回传后高亮匹配文字。
+
+## 最小示例
+
+```go
+query := "seat"
+hits := []mujica.ConversationSearchHit{{ID: "1", Title: "Ballroom seating plan"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	v := mujica.ConversationSearch(c, &query, hits, mujica.ConversationSearchOptions{})
+	if v.QueryChanged {
+		log.Println("search", query)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ConversationSearch(c *ui.Context, query *string, hits []ConversationSearchHit, opts ConversationSearchOptions) ConversationSearchView`。
+
+`ConversationSearchHit`：`ID`、`Title`、`Snippet`（匹配的消息片段）。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Loading` | `bool` | false | 调用方正在搜索。 |
+| `Error` | `string` | "" | 搜索失败的说明，附重试按钮。 |
+| `Placeholder` | `string` | 内置“搜索” | 输入框占位。 |
+| `Label` | `string` | "" | 无障碍名称。 |
+| `Disabled` | `bool` | false | 禁用输入与选择。 |
+
+## 状态
+
+空查询、搜索中（旋转标记）、有结果（匹配处加粗、下划线、Selection 底）、无结果、失败（错误文字 + 重试）、禁用。
+
+## 事件
+
+`QueryChanged`：查询变化，调用方据此发起搜索，结果到达后传入新的 `hits` 并调用 `c.Invalidate()`。`Chosen`：点击或 Enter 打开的会话 ID。`Retry`：点击重试。
+
+## 键盘操作
+
+- 输入框中 ↓：进入结果列表。
+- 列表中 ↑/↓ 移动，Enter 打开。
+- Escape：清空查询（SearchInput 行为）。
+
+## 限制
+
+- 匹配高亮为不区分大小写的逐字符匹配，不做分词、拼音或模糊匹配；排序完全由调用方决定。
+- 结果行固定高度（标题一行、片段一行），片段超长时截断。

docs/components/244-project-list.md

@@ -0,0 +1,53 @@
+# 244 ProjectList · 项目列表
+
+## 用途
+
+按文件夹列出项目，展开项目可见其中的会话；把会话拖到项目上或用“移动”菜单即可改变归属。
+
+## 最小示例
+
+```go
+var state mujica.ProjectListState
+projects := []mujica.ChatProject{{ID: "p1", Name: "Coronation", Folder: "Court"}}
+convs := func(id string) []mujica.ChatConversation {
+	return []mujica.ChatConversation{{ID: "1", Title: "Menu"}}
+}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if v := mujica.ProjectList(c, &state, projects, convs, mujica.ProjectListOptions{}); v.Moved {
+		log.Println("move", v.MoveID, "to", v.MoveTo)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ProjectList(c *ui.Context, s *ProjectListState, projects []ChatProject, conversations func(projectID string) []ChatConversation, opts ProjectListOptions) ProjectListView`。
+
+`ChatProject`：`ID`、`Name`、`Folder`（文件夹名，空表示不在文件夹中）。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Label` | `string` | "" | 树的无障碍名称。 |
+| `Disabled` | `bool` | false | 禁用选择、展开与移动。 |
+
+## 状态
+
+文件夹（展开/收起）、项目行（悬停、选中：Selection 底 + 菱形）、拖入目标（角饰边框）、会话行（拖动时半透明）、禁用。
+
+## 事件
+
+`ProjectListView`：`Changed`（选中项目，ID 在 `State.Selected`）、`Opened`（打开的会话 ID）、`Moved` 与 `MoveID`/`MoveTo`（把会话移入项目，由调用方更新数据）。
+
+## 键盘操作
+
+- Tab：进入树；↑/↓ 在文件夹、项目、会话间移动。
+- 项目行上 →/← 展开/收起会话；Enter 选择项目。
+- 文件夹上 Enter/Space 展开或收起。
+- 会话行的菜单按钮：选择“移入项目”下的目标完成移动（拖放的键盘替代）。
+
+## 限制
+
+- 项目行通过 `Description` 读出“已展开/已收起”；MyGo 不向自定义元素公开 expanded 状态（ui/element.go:282），文件夹使用 `CollapsibleBase`，其展开状态可被辅助技术读到。
+- 列表未虚拟化，适合数百个项目以内。

docs/components/245-project-knowledge-panel.md

@@ -0,0 +1,47 @@
+# 245 ProjectKnowledgePanel · 项目知识面板
+
+## 用途
+
+列出项目知识文件，提供添加、移除，并显示 token 用量与容量提示。选择与读取文件由调用方完成。
+
+## 最小示例
+
+```go
+files := []mujica.KnowledgeFile{{ID: "1", Name: "etiquette.pdf", Tokens: 12000}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	v := mujica.ProjectKnowledgePanel(c, files, mujica.ProjectKnowledgePanelOptions{Capacity: 200000})
+	if v.Add {
+		log.Println("pick files")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ProjectKnowledgePanel(c *ui.Context, files []KnowledgeFile, opts ProjectKnowledgePanelOptions) ProjectKnowledgePanelView`。
+
+`KnowledgeFile`：`ID`、`Name`、`Tokens`（不能为负）。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Capacity` | `int` | 必填 | 知识容量（tokens），必须为正，否则 panic。 |
+| `Title` | `string` | 内置“项目知识” | 面板标题。 |
+| `Disabled` | `bool` | false | 禁用添加与移除。 |
+
+## 状态
+
+正常用量（酒红进度）、≥ 80%（警告色 + 三角图标 + “即将用满”）、超出容量（危险色 + 圆形警示图标 + “超出容量”）、空列表、禁用。
+
+## 事件
+
+`Add`：请调用方打开文件选择。`Removed`：要移除的文件 ID。
+
+## 键盘操作
+
+- Tab：添加按钮，再进入文件列表；↑/↓ 在移除按钮间移动；Enter/Space 移除。
+
+## 限制
+
+- token 数由调用方计算；面板只做求和与比例显示。

docs/components/246-welcome-screen.md

@@ -0,0 +1,46 @@
+# 246 WelcomeScreen · 欢迎页
+
+## 用途
+
+新会话的欢迎页：衬线问候、菱形分隔、副标题、能力卡片，以及放置起始提示的插槽。
+
+## 最小示例
+
+```go
+cards := []mujica.CapabilityCard{{Title: "Write", Examples: []string{"Draft a decree"}}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if v := mujica.WelcomeScreen(c, mujica.WelcomeScreenOptions{Greeting: "Good evening", Cards: cards}); v.Example != "" {
+		log.Println("ask", v.Example)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func WelcomeScreen(c *ui.Context, opts WelcomeScreenOptions) CapabilityCardsView`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Greeting` | `string` | 必填 | 问候语，空时 panic。 |
+| `Subtitle` | `string` | "" | 副标题。 |
+| `Cards` | `[]CapabilityCard` | nil | 能力卡片，最多三列。 |
+| `Prompts` | `func()` | nil | 起始提示插槽，例如 `SuggestionChips`。 |
+| `Disabled` | `bool` | false | 禁用卡片示例与插槽内容。 |
+
+## 状态
+
+默认、禁用（由 MyGo 置灰）。卡片与示例按钮的状态见 249 CapabilityCards。
+
+## 事件
+
+返回值的 `Example`：点击的示例提示。插槽内组件的事件由调用方自行读取。
+
+## 键盘操作
+
+- Tab 依次经过各卡片的示例与插槽内控件；卡片内 ↑/↓ 在示例间移动；Enter/Space 选择。
+
+## 限制
+
+- 问候语按纯文本显示，不解析 Markdown。

docs/components/247-suggestion-chips.md

@@ -0,0 +1,42 @@
+# 247 SuggestionChips · 建议标签
+
+## 用途
+
+起始提示或追问建议。点击可填入输入框，或配置为直接发送。
+
+## 最小示例
+
+```go
+input := ""
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.SuggestionChips(c, &input, []string{"Plan a ball", "Write a sonnet"}, mujica.SuggestionChipsOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func SuggestionChips(c *ui.Context, input *string, suggestions []string, opts SuggestionChipsOptions) SuggestionChipsView`。建议不能为空字符串。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Send` | `bool` | false | 点击即请求发送；默认把建议填入 `*input`。 |
+| `Label` | `string` | "" | 组名称，如“追问建议”。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+默认（右箭头）、发送模式（上箭头）、悬停、按下、聚焦、禁用。
+
+## 事件
+
+`Chosen`：点击的建议。`Sent` 为 true 时调用方应立即发送 `Chosen`；否则建议已写入 `*input`。
+
+## 键盘操作
+
+- Tab 进入组；←/→ 在建议间移动；Enter/Space 选择。
+
+## 限制
+
+- 建议换行排列；数量很多时请调用方截取。

docs/components/248-prompt-library.md

@@ -0,0 +1,49 @@
+# 248 PromptLibrary · 提示模板库
+
+## 用途
+
+按分类与搜索浏览提示模板，预览模板，填写 `{{变量}}` 后插入。
+
+## 最小示例
+
+```go
+var state mujica.PromptLibraryState
+templates := []mujica.PromptTemplate{{ID: "1", Category: "Letters", Title: "Invitation", Body: "Invite {{guest}}."}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if v := mujica.PromptLibrary(c, &state, templates, mujica.PromptLibraryOptions{}); v.Inserted != "" {
+		log.Println("insert", v.Inserted)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func PromptLibrary(c *ui.Context, s *PromptLibraryState, templates []PromptTemplate, opts PromptLibraryOptions) PromptLibraryView`。另有 `PromptLibraryVariables(body)` 与 `PromptLibraryFill(body, values)`。
+
+`PromptTemplate`：`ID`、`Category`、`Title`（ID 与 Title 必填）、`Body`（`{{name}}` 为变量，名称可含字母、数字、`_.-`）。
+
+`PromptLibraryState`：`Category`（空为全部）、`Query`、`Selected`、`Values`（变量值）。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Label` | `string` | "" | 无障碍名称。 |
+| `Disabled` | `bool` | false | 禁用全部操作。 |
+
+## 状态
+
+分类与模板行（选中：Selection 底 + 菱形）、无匹配、未选模板、预览（未填变量以 [名称] 标出，已填值酒红加粗）、插入按钮（变量未填全时禁用）、禁用。
+
+## 事件
+
+`Inserted`：变量已填好的模板正文，非空时由调用方插入输入框。
+
+## 键盘操作
+
+- Tab 依次进入分类列、搜索框、模板列、变量输入框、插入按钮；列内 ↑/↓ 移动；Enter/Space 选择。
+
+## 限制
+
+- 过滤只在模板切片、查询或分类变化时重算。
+- 变量为简单占位替换，不支持条件或循环。

docs/components/249-capability-cards.md

@@ -0,0 +1,45 @@
+# 249 CapabilityCards · 能力卡片
+
+## 用途
+
+用卡片说明助手能做什么，每张卡片附示例提示，点击示例交给调用方。
+
+## 最小示例
+
+```go
+cards := []mujica.CapabilityCard{{Title: "Plan", Icon: icons.Must("calendar"), Examples: []string{"Plan a ball"}}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if v := mujica.CapabilityCards(c, cards, mujica.CapabilityCardsOptions{}); v.Example != "" {
+		log.Println("ask", v.Example)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func CapabilityCards(c *ui.Context, cards []CapabilityCard, opts CapabilityCardsOptions) CapabilityCardsView`。
+
+`CapabilityCard`：`Title`（必填）、`Description`、`Icon`、`Examples`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Columns` | `int` | 0 → 3 | 每行卡片数；负数 panic。 |
+| `Disabled` | `bool` | false | 禁用示例按钮。 |
+
+## 状态
+
+卡片（衬线标题、酒红图标）、示例按钮（悬停、按下、聚焦）、禁用。
+
+## 事件
+
+`Example`：点击的示例文字。
+
+## 键盘操作
+
+- Tab 在各卡片示例组间移动；组内 ↑/↓；Enter/Space 选择。
+
+## 限制
+
+- 卡片等宽分栏，不随窗口宽度自动减少列数；窄窗口时请调用方传入较小的 `Columns`。

docs/components/250-feedback-form.md

@@ -0,0 +1,46 @@
+# 250 FeedbackForm · 反馈表单
+
+## 用途
+
+在点赞或点踩之后询问原因：原因标签多选与补充文字，然后提交或取消。
+
+## 最小示例
+
+```go
+var value mujica.FeedbackValue
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.FeedbackForm(c, &value, mujica.FeedbackFormOptions{Rating: mujica.FeedbackDown}).Submitted {
+		log.Println("reasons", value.Reasons)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func FeedbackForm(c *ui.Context, value *FeedbackValue, opts FeedbackFormOptions) FeedbackFormView`。`FeedbackValue`：`Reasons`、`Comment`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Rating` | `FeedbackRating` | `FeedbackUp` | 赞（`FeedbackUp`）或踩（`FeedbackDown`），决定标题与内置原因。 |
+| `Reasons` | `[]string` | nil（内置） | 替换内置原因。 |
+| `Submitting` | `bool` | false | 调用方正在提交：提交按钮显示加载，表单不可编辑。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+原因标签（按下：Selection 底 + 下划条）、文字框、提交中、禁用。
+
+## 事件
+
+`Submitted`：提交；`Cancelled`：取消或 Escape。
+
+## 键盘操作
+
+- Tab 依次经过原因组、文字框、取消、提交；原因组内 ←/→；Space 切换原因。
+- Escape：取消。
+
+## 限制
+
+- 表单不发送任何数据；提交由调用方完成。

docs/components/251-date-separator.md

@@ -0,0 +1,39 @@
+# 251 DateSeparator · 日期分隔
+
+## 用途
+
+在消息流中标出新的一天：今天、昨天，其余显示本地化的完整日期。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.DateSeparator(c, mujica.DateOf(time.Now()), mujica.DateSeparatorOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func DateSeparator(c *ui.Context, day Date, opts DateSeparatorOptions) *ui.Element`。`day` 必须是有效日期。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Today` | `Date` | 零值（窗口时钟） | 判断“今天/昨天”的当天。 |
+
+## 状态
+
+细线 + 旧金色菱形 + 说明文字；无交互状态。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点；辅助技术读出日期文字。
+
+## 限制
+
+- 日期格式沿用 Calendar 的文案（`calendar.day_label`），en-US 为“Tuesday, September 1, 2026”，zh-CN 为“2026年9月1日 星期二”。

docs/components/252-thinking-indicator.md

@@ -0,0 +1,39 @@
+# 252 ThinkingIndicator · 思考指示
+
+## 用途
+
+显示助手正在思考：三个菱形依次起伏，旁边是阶段文字；减少动画时静止并加省略号。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.ThinkingIndicator(c, mujica.ThinkingIndicatorOptions{Phase: "Searching the archives"})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ThinkingIndicator(c *ui.Context, opts ThinkingIndicatorOptions) *ui.Element`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Phase` | `string` | 内置“正在思考” | 阶段文字，如“正在检索资料”。 |
+
+## 状态
+
+动画（1.2 秒一周）、减少动画（静止菱形 + “…”）。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点；角色为 Status，辅助技术读出阶段文字。
+
+## 限制
+
+- 动画只在绘制时请求下一帧；组件隐藏后不再重绘。

docs/components/253-stop-generating-button.md

@@ -0,0 +1,44 @@
+# 253 StopGeneratingButton · 停止生成按钮
+
+## 用途
+
+生成回复时显示的停止按钮，并提供 Cmd+.（其他平台 Ctrl+.）快捷键；生成结束后不显示。
+
+## 最小示例
+
+```go
+generating := true
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.StopGeneratingButton(c, mujica.StopGeneratingButtonOptions{Generating: generating}).Changed() {
+		generating = false
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func StopGeneratingButton(c *ui.Context, opts StopGeneratingButtonOptions) ChoiceResult`。不显示时返回的 `Element` 为 nil。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Generating` | `bool` | false | 正在生成时显示。 |
+| `Disabled` | `bool` | false | 禁用按钮与快捷键。 |
+
+## 状态
+
+默认（方块图标 + 文字 + 快捷键提示）、悬停、聚焦、禁用、隐藏。
+
+## 事件
+
+`Changed()`：请求停止。
+
+## 键盘操作
+
+- Enter/Space：停止。
+- Cmd+.（macOS）/ Ctrl+.（Windows、Linux）：窗口级快捷键，焦点所在控件未占用该键时生效。
+
+## 限制
+
+- 快捷键用 MyGo 窗口快捷键注册，焦点控件若注册了同一组合键会优先获得。

docs/components/254-system-prompt-editor.md

@@ -0,0 +1,47 @@
+# 254 SystemPromptEditor · 系统提示编辑器
+
+## 用途
+
+多行编辑系统提示，显示字数，可恢复默认，有未保存标记，Cmd/Ctrl+S 保存。
+
+## 最小示例
+
+```go
+prompt, saved := "You are helpful.", "You are helpful."
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.SystemPromptEditor(c, &prompt, mujica.SystemPromptEditorOptions{Default: "You are helpful.", Saved: saved}).Save {
+		saved = prompt
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func SystemPromptEditor(c *ui.Context, value *string, opts SystemPromptEditorOptions) SystemPromptEditorView`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Default` | `string` | "" | 恢复默认时写回的文字。 |
+| `Saved` | `string` | "" | 最近一次保存的文字；与当前值不同即显示“未保存”。 |
+| `MaxLength` | `int` | 0 | 字数上限：显示 n / 上限，超出时提示并禁止保存。 |
+| `Saving` | `bool` | false | 调用方正在保存，编辑被阻止。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+已保存、未保存（警告色菱形 + 文字）、超出上限（错误提示）、保存中、禁用。
+
+## 事件
+
+`Save`：请求保存当前值；`Restored`：已恢复默认。
+
+## 键盘操作
+
+- Tab：进入文本框，再到恢复默认与保存按钮。
+- Cmd+S（macOS）/ Ctrl+S：保存（有改动且未超限时）。
+
+## 限制
+
+- 超出上限不会截断文字，只阻止保存。

docs/components/255-cost-estimator.md

@@ -0,0 +1,42 @@
+# 255 CostEstimator · 费用估算
+
+## 用途
+
+显示输入、输出 token 数及按调用方单价估算的费用。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.CostEstimator(c, mujica.CostEstimatorOptions{InputTokens: 12000, OutputTokens: 3400, InputPrice: 3, OutputPrice: 15})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func CostEstimator(c *ui.Context, opts CostEstimatorOptions) *ui.Element`。另有 `EstimateCost(inputTokens, outputTokens, inputPrice, outputPrice) CostEstimate`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `InputTokens`, `OutputTokens` | `int` | 0 | token 数，不能为负。 |
+| `InputPrice`, `OutputPrice` | `float64` | 0 | 每百万 tokens 单价，须有限且不为负。 |
+| `Currency` | `string` | "$" | 金额前缀。 |
+| `Digits` | `int` | 0 → 4 | 金额小数位；负数 panic。 |
+
+## 状态
+
+只读表格：输入、输出、合计（衬线标签、酒红加粗金额）与单价说明。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点；整体读作“预计费用 金额”。
+
+## 限制
+
+- 估算按 tokens × 单价 / 1,000,000 的浮点运算；显示按 `Digits` 位小数四舍五入，不用于结算。

docs/components/256-shared-conversation-view.md

@@ -0,0 +1,48 @@
+# 256 SharedConversationView · 分享会话视图
+
+## 用途
+
+只读显示他人分享的会话，带分享者与时间，提供复制链接回调。
+
+## 最小示例
+
+```go
+msgs := []mujica.SessionMessage{{Role: mujica.SessionUser, Text: "Hello"}, {Role: mujica.SessionAssistant, Text: "Good day."}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.SharedConversationView(c, msgs, mujica.SharedConversationViewOptions{Title: "Greeting", SharedBy: "Ann"}).Changed() {
+		c.WriteClipboard("https://example.com/share/1")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func SharedConversationView(c *ui.Context, messages []SessionMessage, opts SharedConversationViewOptions) ChoiceResult`。
+
+`SessionMessage`：`Role`（`SessionUser`、`SessionAssistant`、`SessionSystem`）、`Author`、`Text`、`Time`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Title` | `string` | 必填 | 会话标题。 |
+| `SharedBy` | `string` | "" | 分享者，空显示“未知”。 |
+| `SharedAt` | `time.Time` | 零值 | 分享时间，零值不显示。 |
+| `Disabled` | `bool` | false | 禁用复制链接。 |
+
+## 状态
+
+标题区、只读标记（锁形图标）、用户消息（描边气泡）、助手消息、禁用。
+
+## 事件
+
+`Changed()`：点击“复制链接”，由调用方生成链接并写入剪贴板。
+
+## 键盘操作
+
+- Tab：复制链接按钮，再到消息列表；消息文字可选择复制。
+
+## 限制
+
+- 消息以纯文本显示，不渲染 Markdown（Markdown 渲染属于 MarkdownView 组件）。
+- 消息列表虚拟化，只构建可见消息。

docs/components/257-conversation-export.md

@@ -0,0 +1,48 @@
+# 257 ConversationExport · 会话导出
+
+## 用途
+
+选择格式（Markdown、JSON、纯文本）与范围，预览后生成导出文字；写文件由调用方完成。
+
+## 最小示例
+
+```go
+var state mujica.ConversationExportState
+msgs := []mujica.SessionMessage{{Role: mujica.SessionUser, Text: "Hello"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if v := mujica.ConversationExport(c, &state, msgs, mujica.ConversationExportOptions{Title: "Greeting"}); v.Exported {
+		log.Println(len(v.Content), "bytes to save")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ConversationExport(c *ui.Context, s *ConversationExportState, messages []SessionMessage, opts ConversationExportOptions) ConversationExportView`。另有纯函数 `ExportConversation(title, messages, format) string`。
+
+`ConversationExportState`：`Format`（`ExportMarkdown`、`ExportJSON`、`ExportText`）、`Range`（`ExportAll`、`ExportLast`、`ExportSelected`）、`Last`（0 → 10）。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Title` | `string` | 必填 | 会话标题，写入导出内容。 |
+| `Selected` | `[]int` | nil | `ExportSelected` 使用的消息下标；越界 panic。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+格式单选、范围单选（无选中消息时“已选”不可选）、最近 N 条数字框、等宽字体预览、导出按钮、禁用。
+
+## 事件
+
+`Exported`：导出请求；`Content` 为生成的文字，`Format` 为格式。
+
+## 键盘操作
+
+- Tab 依次经过格式组、范围组、数字框、预览、导出按钮；单选组内方向键选择。
+
+## 限制
+
+- 导出不解析消息文字：Markdown 只加标题与作者行，原文原样写入。
+- 预览只在格式、范围或消息变化时重新生成。

docs/components/258-regenerate-menu.md

@@ -0,0 +1,44 @@
+# 258 RegenerateMenu · 重新生成菜单
+
+## 用途
+
+重新生成回复：同模型重试、换模型重试，以及更长、更短等改写变体。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if v := mujica.RegenerateMenu(c, mujica.RegenerateMenuOptions{Models: []string{"Opus", "Sonnet"}, Current: "Opus"}); v.Chosen {
+		log.Println("retry", v.Choice.Kind, v.Choice.Model, v.Choice.Variant)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func RegenerateMenu(c *ui.Context, opts RegenerateMenuOptions) RegenerateMenuView`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Models` | `[]string` | nil | 可换用的模型；为空或只有当前模型时子菜单禁用。 |
+| `Current` | `string` | "" | 当前模型，不出现在子菜单中。 |
+| `Variants` | `[]string` | nil（内置） | 替换内置的更长、更短、更简单、更详细。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+触发按钮（刷新图标）、菜单打开、子菜单、分组标题、禁用项。
+
+## 事件
+
+`Chosen` 与 `Choice`：`Kind` 为 `RegenerateAgain`、`RegenerateModel`（`Model`）或 `RegenerateVariant`（`Variant`）。
+
+## 键盘操作
+
+- Enter、Space 或 ↓ 打开菜单；↑/↓ 移动；→ 打开子菜单，← 返回；Enter 选择；Escape 关闭。
+
+## 限制
+
+- 菜单在窗口内绘制（DropdownMenu），不使用系统菜单。

docs/components/259-artifact-card.md

@@ -0,0 +1,45 @@
+# 259 ArtifactCard · 产物卡片
+
+## 用途
+
+消息中的产物卡片（代码、文档、网页），点击打开产物面板。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.ArtifactCard(c, mujica.ArtifactCardOptions{Title: "seating.go", Detail: "Go · 120 lines"}).Changed() {
+		log.Println("open artifact panel")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ArtifactCard(c *ui.Context, opts ArtifactCardOptions) ChoiceResult`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Kind` | `ArtifactKind` | `ArtifactCode` | `ArtifactCode`、`ArtifactDocument`、`ArtifactWeb`；越界 panic。 |
+| `Title` | `string` | 必填 | 产物标题。 |
+| `Detail` | `string` | "" | 简短说明，如“Go · 120 行”。 |
+| `Streaming` | `bool` | false | 仍在生成，显示旋转标记。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+默认、悬停、聚焦、生成中、禁用。种类同时用图标与文字表示。
+
+## 事件
+
+`Changed()`：请求打开产物面板。
+
+## 键盘操作
+
+- Tab 聚焦；Enter/Space 打开。
+
+## 限制
+
+- 卡片不渲染产物内容，面板由调用方实现。

docs/components/260-chat-empty-state.md

@@ -0,0 +1,44 @@
+# 260 ChatEmptyState · 会话空状态
+
+## 用途
+
+会话界面的三种空状态：新会话、无搜索结果、离线，并给出下一步操作。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.ChatEmptyState(c, mujica.ChatEmptyStateOptions{Kind: mujica.ChatEmptyOffline}).Action {
+		log.Println("reconnect")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ChatEmptyState(c *ui.Context, opts ChatEmptyStateOptions) EmptyStateResult`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Kind` | `ChatEmptyKind` | `ChatEmptyNew` | `ChatEmptyNew`、`ChatEmptyNoResults`、`ChatEmptyOffline`；越界 panic。 |
+| `Query` | `string` | "" | 无结果时在说明中显示的查询。 |
+| `Title`, `Description` | `string` | 内置 | 替换文案。 |
+| `Action` | `string` | 内置 | 按钮文字：新建对话、清除搜索、重试。 |
+
+## 状态
+
+新会话（星形图标）、无结果（搜索图标）、离线（断网图标）。
+
+## 事件
+
+返回值 `Action`：点击按钮。
+
+## 键盘操作
+
+- Tab 聚焦按钮；Enter/Space 触发。
+
+## 限制
+
+- 基于 EmptyState 组件，布局与其一致。