Merge branch 'main' into worktree-agent-ab9ba373bc47c2352

2026-10-05 14:39:12 -04:00
commit eb78b0a4a1
@@ -0,0 +1,54 @@
+# 101 LineChart 折线图
+
+## 用途
+
+多序列折线图：数值或时间横轴，缺值（NaN）处断开，悬停与键盘读数，图例勾选框控制序列显隐。大数据按像素列抽稀绘制，10 万点保持流畅。
+
+## 最小示例
+
+```go
+series := []mujica.ChartSeries{
+	{Name: "Pews", Values: []float64{3, 5, math.NaN(), 4, 8}},
+	{Name: "Candles", Values: []float64{5, 2, 6, 7, 1}},
+}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.LineChart(c, series, mujica.LineChartOptions{Frame: mujica.ChartFrame{Label: "Chapel"}})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func LineChart(c *ui.Context, series []ChartSeries, opts LineChartOptions) ChartResult`；`ChartSeries{Name, Values}`，各序列等长且名称唯一。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `X` | `[]float64` | nil | 点 i 的横坐标，须递增；nil 时为下标。 |
+| `Times` | `[]time.Time` | nil | 时间轴；与 `X` 二选一，须递增。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 读数中的数值格式。 |
+
+## 状态
+
+默认、悬停或键盘读数（竖线 + 各序列放大标记）、隐藏序列（图例划线、空心标记）、加载、失败、无数据（全部为缺值时）。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试；`Toggled()` 返回本帧被切换显隐的序列名。
+
+## 键盘操作
+
+- Tab：聚焦绘图区（图例勾选框在其前）。
+- ←/→（以及 ↑/↓）：在数据点之间移动，读数显示在图表下方并向读屏软件播报；第一次按键进入第一个点。
+- Home/End：第一个/最后一个点；Escape：清除读数。
+- 图例勾选框：Space 切换序列显隐。
+
+## 限制
+
+- 数据切片以首元素地址与长度识别；原地修改数据后请传入新切片，缓存的坐标范围才会更新。
+- 每条序列除颜色外还有不同形状的标记（圆、方、菱形、三角），密集时按间隔绘制。
@@ -0,0 +1,54 @@
+# 102 AreaChart 面积图
+
+## 用途
+
+面积图：单序列填充到基线，或多序列堆叠；基线可配置；悬停与键盘读数显示各序列原值（不是堆叠后的值）。
+
+## 最小示例
+
+```go
+series := []mujica.ChartSeries{
+	{Name: "Matins", Values: []float64{3, 4, 6, 5}},
+	{Name: "Vespers", Values: []float64{2, 3, 2, 4}},
+}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.AreaChart(c, series, mujica.AreaChartOptions{Frame: mujica.ChartFrame{Label: "Attendance"}, Stacked: true})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func AreaChart(c *ui.Context, series []ChartSeries, opts AreaChartOptions) ChartResult`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `X`, `Times` | | nil | 同 LineChart。 |
+| `Stacked` | `bool` | false | 可见序列依次堆叠；隐藏序列不参与堆叠。 |
+| `Baseline` | `float64` | `0` | 面积的起始值；坐标轴总包含基线。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 读数格式。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试；`Toggled()` 同 LineChart。
+
+## 键盘操作
+
+- Tab：聚焦绘图区（图例勾选框在其前）。
+- ←/→（以及 ↑/↓）：在数据点之间移动，读数显示在图表下方并向读屏软件播报；第一次按键进入第一个点。
+- Home/End：第一个/最后一个点；Escape：清除读数。
+
+## 限制
+
+- 缺值处面积断开；堆叠时缺值按 0 计入后续序列。
+- 填充为半透明的序列色，边线保持实色以满足 3:1 对比。
@@ -0,0 +1,52 @@
+# 103 BarChart 柱状图
+
+## 用途
+
+柱状图：纵向或横向，分组或堆叠，支持负值与柱端数值标签，键盘逐柱读数。
+
+## 最小示例
+
+```go
+categories := []string{"Nave", "Choir", "Crypt"}
+series := []mujica.ChartSeries{{Name: "Gold", Values: []float64{4, -2, 3}}, {Name: "Silver", Values: []float64{2, 5, 1}}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.BarChart(c, categories, series, mujica.BarChartOptions{Frame: mujica.ChartFrame{Label: "Tithes"}, Labels: true})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func BarChart(c *ui.Context, categories []string, series []ChartSeries, opts BarChartOptions) ChartResult`；每条序列的值与类别一一对应，NaN 不画柱。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `Horizontal` | `bool` | false | 类别在纵轴，柱横向延伸。 |
+| `Stacked` | `bool` | false | 每个类别一根柱，正值向上、负值向下堆叠。 |
+| `Labels` | `bool` | false | 在柱端写出数值（堆叠时不写）。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 数值格式。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。 选中柱以描边标出，柱内有序列形状标记。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试；多序列时 `Toggled()` 报告图例切换。
+
+## 键盘操作
+
+- Tab：聚焦绘图区（图例勾选框在其前）。
+- ←/→（以及 ↑/↓）：逐柱移动（按类别、再按序列），读数显示在图表下方并向读屏软件播报；第一次按键进入第一个点。
+- Home/End：第一个/最后一个点；Escape：清除读数。
+
+## 限制
+
+- 极细的柱仍有 6 DIP 的悬停范围。
+- 类别标签过密时会跳过重叠的标签，读数仍包含完整类别名。
@@ -0,0 +1,50 @@
+# 104 PieChart 饼图
+
+## 用途
+
+饼图与环形图：扇区按占比绘制并标注百分比；过窄的扇区可合并为“其他”；环形图中心显示总计。
+
+## 最小示例
+
+```go
+slices := []mujica.ChartSlice{{Label: "Wax", Value: 50}, {Label: "Oil", Value: 30}, {Label: "Salt", Value: 4}, {Label: "Ash", Value: 3}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.PieChart(c, slices, mujica.PieChartOptions{Frame: mujica.ChartFrame{Label: "Stores"}, Donut: true, MinAngle: 20})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func PieChart(c *ui.Context, slices []ChartSlice, opts PieChartOptions) ChartResult`；`ChartSlice{Label, Value}`，值须为有限且 ≥ 0。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `Donut` | `bool` | false | 环形图，中心写总计。 |
+| `MinAngle` | `float64` | `0` | 小于该角度（度）的扇区达到两个及以上时合并为“其他”；须在 [0, 360)。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 数值格式。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。 当前扇区向外凸出。总计为 0 时显示无数据。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试。
+
+## 键盘操作
+
+- Tab：聚焦绘图区（图例勾选框在其前）。
+- ←/→（以及 ↑/↓）：在数据点之间移动，读数显示在图表下方并向读屏软件播报；第一次按键进入第一个点。
+- Home/End：第一个/最后一个点；Escape：清除读数。
+
+## 限制
+
+- 只有一个窄扇区时不合并，以免“其他”只代表一项。
+- 扇区内的形状标记与百分比文字按对比度自动选用正文色或表面色。
@@ -0,0 +1,52 @@
+# 105 ScatterChart 散点图
+
+## 用途
+
+散点图：按分组着色并配不同形状，点大小可映射为气泡，拖动框选或用键盘选中点。
+
+## 最小示例
+
+```go
+var selected []mujica.ScatterKey
+groups := []mujica.ScatterGroup{{Name: "Monks", Points: []mujica.ScatterPoint{{X: 1, Y: 2, Size: 4}, {X: 3, Y: 5, Size: 9}}}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.ScatterChart(c, &selected, groups, mujica.ScatterChartOptions{Frame: mujica.ChartFrame{Label: "Choir"}, Bubbles: true})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ScatterChart(c *ui.Context, selected *[]ScatterKey, groups []ScatterGroup, opts ScatterChartOptions) ChartResult`；`ScatterGroup{Name, Points []ScatterPoint{X, Y, Size}}`，`ScatterKey{Group, Point}` 标识一个点。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `Bubbles` | `bool` | false | 按 `Size` 映射点面积（直径 4–18 DIP）。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 读数格式。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。 选中的点外加圆环，读数注明“已选”。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试；`ValueChanged()` 表示 `*selected` 被框选或键盘改变；多组时 `Toggled()` 报告图例切换。
+
+## 键盘操作
+
+- Tab：聚焦绘图区（图例勾选框在其前）。
+- ←/→（以及 ↑/↓）：在数据点之间移动，读数显示在图表下方并向读屏软件播报；第一次按键进入第一个点。
+- Home/End：第一个/最后一个点；Escape：清除读数。
+- Enter/Space：选中或取消当前点。
+- 在绘图区拖动：框选，替换现有选择。
+
+## 限制
+
+- 框选替换选择，不支持按住修饰键追加。
+- 点数较多时逐点绘制，没有抽稀。
@@ -0,0 +1,49 @@
+# 106 RadarChart 雷达图
+
+## 用途
+
+雷达图：三个及以上维度，多序列多边形，刻度环，按维度悬停或键盘读数。
+
+## 最小示例
+
+```go
+axes := []string{"Voice", "Latin", "Chant", "Organ"}
+series := []mujica.ChartSeries{{Name: "Agnès", Values: []float64{8, 6, 9, 4}}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.RadarChart(c, axes, series, mujica.RadarChartOptions{Frame: mujica.ChartFrame{Label: "Skills"}})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func RadarChart(c *ui.Context, axes []string, series []ChartSeries, opts RadarChartOptions) ChartResult`；每条序列每个维度一个值，值须 ≥ 0。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `Max` | `float64` | 自动取整 | 外环代表的值；0 按数据向上取整。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 读数格式。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。 当前维度的轴线加粗、标签变为正文色。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试；多序列时 `Toggled()` 报告图例切换。
+
+## 键盘操作
+
+- Tab：聚焦绘图区（图例勾选框在其前）。
+- ←/→（以及 ↑/↓）：按维度移动，读数显示在图表下方并向读屏软件播报；第一次按键进入第一个点。
+- Home/End：第一个/最后一个点；Escape：清除读数。
+
+## 限制
+
+- 缺值按 0 画在中心，读数显示“无数值”。
@@ -0,0 +1,48 @@
+# 107 HeatmapChart 热力图
+
+## 用途
+
+二维矩阵热力图：按值分五级着色，右侧色阶图例标出最小与最大值；单元格读数；空值单元格为虚线框。
+
+## 最小示例
+
+```go
+rows, cols := []string{"Mon", "Tue"}, []string{"Matins", "Lauds", "Vespers"}
+values := [][]float64{{1, 4, 9}, {3, math.NaN(), 7}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.HeatmapChart(c, rows, cols, values, mujica.HeatmapChartOptions{Frame: mujica.ChartFrame{Label: "Hours"}})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func HeatmapChart(c *ui.Context, rows, cols []string, values [][]float64, opts HeatmapChartOptions) ChartResult`；`values[行][列]`，NaN 为空值。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 单元格与读数格式。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。 单元格足够大时直接写出数值，不只依赖颜色。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试。
+
+## 键盘操作
+
+- Tab：聚焦热力图。
+- ←/→：同一行左右移动；↑/↓：同一列上下移动；第一次按键进入左上角。
+- Home/End：第一个/最后一个单元格；Escape：清除读数。
+
+## 限制
+
+- 颜色分五级，不做连续渐变。
@@ -0,0 +1,50 @@
+# 108 CalendarHeatmap 日历热力图
+
+## 用途
+
+按日的贡献图：一列一周，按当年最大值分四级着色；年份切换；周起始可配置；逐日读数。
+
+## 最小示例
+
+```go
+year := 2026
+values := map[mujica.Date]float64{{Year: 2026, Month: time.March, Day: 4}: 5}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.CalendarHeatmap(c, &year, values, mujica.CalendarHeatmapOptions{Frame: mujica.ChartFrame{Label: "Prayers"}})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func CalendarHeatmap(c *ui.Context, year *int, values map[Date]float64, opts CalendarHeatmapOptions) ChartResult`；`*year` 须在 1–9999。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `WeekStart` | `WeekStart` | 跟随语言 | 每列第一行是星期几。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 读数格式。 |
+
+## 状态
+
+默认、无记录日（浅色格）、四级色阶、悬停或键盘读数（描边）、加载、失败。下方图例从“少”到“多”。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试；`ValueChanged()` 表示上一年/下一年按钮改变了 `*year`。
+
+## 键盘操作
+
+- Tab：年份按钮，再到日历。
+- ←/→：前后一周；↑/↓：前后一天；Home/End：全年第一天与最后一天。
+- 上一年/下一年按钮：Enter/Space。
+
+## 限制
+
+- 方格较小，只作读数目标，不是独立操作，因此不要求 28 DIP 命中区。
+- 值 ≤ 0 视为无记录。
@@ -0,0 +1,50 @@
+# 109 Histogram 直方图
+
+## 用途
+
+分箱计数直方图：箱数或箱宽可配置，可切换为累计模式；分箱只在数据或参数变化时计算一次。
+
+## 最小示例
+
+```go
+values := []float64{1, 2, 2, 3, 4, 5, 9, 10}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Histogram(c, values, mujica.HistogramOptions{Frame: mujica.ChartFrame{Label: "Ages"}, BinWidth: 5})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func Histogram(c *ui.Context, values []float64, opts HistogramOptions) ChartResult`；NaN 与无穷值被忽略。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `Bins` | `int` | Sturges 规则 | 箱数；负数 panic。 |
+| `BinWidth` | `float64` | 0 | 箱宽；设定时优先于 `Bins`，箱边取箱宽的整数倍。超过 10000 箱 panic。 |
+| `Cumulative` | `bool` | false | 每箱计入不超过其上界的全部值。 |
+| `Format` | `func(float64) string` | 按箱宽取精度 | 箱边格式。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试。
+
+## 键盘操作
+
+- Tab：聚焦绘图区（图例勾选框在其前）。
+- ←/→（以及 ↑/↓）：逐箱移动，读数显示在图表下方并向读屏软件播报；第一次按键进入第一个点。
+- Home/End：第一个/最后一个点；Escape：清除读数。
+
+## 限制
+
+- 按箱数分箱时最后一箱包含上界，读数用 `]` 表示。
@@ -0,0 +1,47 @@
+# 110 BoxPlot 箱线图
+
+## 用途
+
+箱线图：四分位箱、中位线、1.5 倍四分距内的须线与离群点，多组对比。统计只在数据变化时计算。
+
+## 最小示例
+
+```go
+groups := []mujica.BoxGroup{{Name: "Choir", Values: []float64{1, 2, 3, 4, 5, 40}}, {Name: "Nave", Values: []float64{4, 5, 6, 7}}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.BoxPlot(c, groups, mujica.BoxPlotOptions{Frame: mujica.ChartFrame{Label: "Hymns"}})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func BoxPlot(c *ui.Context, groups []BoxGroup, opts BoxPlotOptions) ChartResult`；`BoxGroup{Name, Values}`，名称必填。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 读数格式。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。 离群点画为空心圆。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试。
+
+## 键盘操作
+
+- Tab：聚焦绘图区（图例勾选框在其前）。
+- ←/→（以及 ↑/↓）：按组移动，读数显示在图表下方并向读屏软件播报；第一次按键进入第一个点。
+- Home/End：第一个/最后一个点；Escape：清除读数。
+
+## 限制
+
+- 四分位数用线性插值计算。
@@ -0,0 +1,52 @@
+# 111 WaterfallChart 瀑布图
+
+## 用途
+
+瀑布图：增减项累计，小计与总计柱显示累计值；增加为 Success 色并配 ▲，减少为 Danger 色并配 ▼，合计为中性色配 ■，柱端写出带符号的数值。
+
+## 最小示例
+
+```go
+steps := []mujica.WaterfallStep{
+	{Label: "Tithes", Value: 12},
+	{Label: "Repairs", Value: -5},
+	{Label: "Year", Kind: mujica.WaterfallTotal},
+}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.WaterfallChart(c, steps, mujica.WaterfallChartOptions{Frame: mujica.ChartFrame{Label: "Ledger"}})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func WaterfallChart(c *ui.Context, steps []WaterfallStep, opts WaterfallChartOptions) ChartResult`；`WaterfallStep{Label, Value, Kind}`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `steps[i].Kind` | `WaterfallKind` | `WaterfallDelta` | `WaterfallDelta` 累加；`WaterfallSubtotal`、`WaterfallTotal` 显示当前累计，`Value` 须为 0。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 数值格式。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试。
+
+## 键盘操作
+
+- Tab：聚焦绘图区（图例勾选框在其前）。
+- ←/→（以及 ↑/↓）：逐柱移动，读数显示在图表下方并向读屏软件播报；第一次按键进入第一个点。
+- Home/End：第一个/最后一个点；Escape：清除读数。
+
+## 限制
+
+- 小计与总计都显示到该步为止的累计值，不清零。
@@ -0,0 +1,47 @@
+# 112 FunnelChart 漏斗图
+
+## 用途
+
+漏斗图：阶段宽度与值成比例，右侧写出值与相对上一阶段的转化率；读数同时给出相对首阶段的比例。
+
+## 最小示例
+
+```go
+stages := []mujica.ChartSlice{{Label: "Visitors", Value: 1000}, {Label: "Novices", Value: 400}, {Label: "Vows", Value: 100}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.FunnelChart(c, stages, mujica.FunnelChartOptions{Frame: mujica.ChartFrame{Label: "Order"}})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func FunnelChart(c *ui.Context, stages []ChartSlice, opts FunnelChartOptions) ChartResult`；值须为有限且 ≥ 0。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 数值格式。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。 全部为 0 时显示无数据。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试。
+
+## 键盘操作
+
+- Tab：聚焦绘图区（图例勾选框在其前）。
+- ←/→（以及 ↑/↓）：逐阶段移动，读数显示在图表下方并向读屏软件播报；第一次按键进入第一个点。
+- Home/End：第一个/最后一个点；Escape：清除读数。
+
+## 限制
+
+- 上一阶段为 0 时转化率显示“—”。
@@ -0,0 +1,51 @@
+# 113 BulletChart 子弹图
+
+## 用途
+
+子弹图：实际值的细条、目标值的垂直线与定性区间带，可横向或纵向。
+
+## 最小示例
+
+```go
+target := 250.0
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.BulletChart(c, 270, mujica.BulletChartOptions{Frame: mujica.ChartFrame{Label: "Alms"}, Target: &target, Bands: []float64{150, 225, 300}})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func BulletChart(c *ui.Context, value float64, opts BulletChartOptions) ChartResult`；值须 ≥ 0。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `72` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `Target` | `*float64` | nil | 目标值，画为与刻度垂直的粗线。 |
+| `Bands` | `[]float64` | nil | 各区间的上界，须为正且递增。 |
+| `Max` | `float64` | 自动取整 | 刻度终点；0 按值、目标与区间取整。 |
+| `Vertical` | `bool` | false | 纵向摆放。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 数值格式。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。 区间由浅到深的中性色带表示，读数写出区间范围。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试。
+
+## 键盘操作
+
+- Tab：聚焦绘图区（图例勾选框在其前）。
+- ←/→（以及 ↑/↓）：依次读实际值、目标值与各区间，读数显示在图表下方并向读屏软件播报；第一次按键进入第一个点。
+- Home/End：第一个/最后一个点；Escape：清除读数。
+
+## 限制
+
+- 超出 `Max` 的值画到刻度终点，读数仍为原值。
@@ -0,0 +1,48 @@
+# 114 Sparkline 迷你图
+
+## 用途
+
+行内迷你图：折线、柱形或面积，无坐标轴；末值以菱形标记并在右侧写出数值；聚焦后可逐点读数。
+
+## 最小示例
+
+```go
+values := []float64{3, 5, 4, 7, 6, 9}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Sparkline(c, values, mujica.SparklineOptions{Frame: mujica.ChartFrame{Label: "Bells"}, Kind: mujica.SparklineArea})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func Sparkline(c *ui.Context, values []float64, opts SparklineOptions) ChartResult`；NaN 为缺值。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `28` | 迷你图高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `Kind` | `SparklineKind` | `SparklineLine` | `SparklineLine`、`SparklineBar` 或 `SparklineArea`。 |
+| `Width` | `float32` | `96` | 迷你图宽度（DIP）。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 右侧数值格式。 |
+
+## 状态
+
+默认（显示末值）、悬停或键盘读数（右侧数值变为当前点，点外加圆环）、加载（小型加载标记）、失败（错误文字与重试图标）、无数据。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试。
+
+## 键盘操作
+
+- Tab：聚焦迷你图。
+- ←/→：逐点移动；Home/End：首尾；Escape：恢复显示末值。
+
+## 限制
+
+- 不显示图例与提示行，以便放在表格行或文字中。
@@ -0,0 +1,51 @@
+# 115 Gauge 仪表盘
+
+## 用途
+
+仪表盘：半圆或整圆表盘，按阈值分段着色，指针指向当前值，下方写出数值、单位和所在分段的名称，不只靠颜色表达区间。
+
+## 最小示例
+
+```go
+segments := []mujica.GaugeSegment{{To: 60, Label: "Calm", Tone: mujica.GaugeGood}, {To: 100, Label: "Crowded", Tone: mujica.GaugeDanger}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Gauge(c, 72, mujica.GaugeOptions{Frame: mujica.ChartFrame{Label: "Nave"}, Max: 100, Unit: "%", Segments: segments})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func Gauge(c *ui.Context, value float64, opts GaugeOptions) ChartResult`；值须在 `Min`–`Max` 之间。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `200` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `Min`, `Max` | `float64` | 必须 `Min < Max` | 刻度范围。 |
+| `Segments` | `[]GaugeSegment` | nil | 分段 `{To, Label, Tone}`，上界递增且最后一段止于 `Max`；`Tone` 为 `GaugeNeutral`、`GaugeGood`、`GaugeWarning`、`GaugeDanger`。 |
+| `Unit` | `string` | 空 | 数值后的单位。 |
+| `Full` | `bool` | false | 整圆表盘，从底部顺时针一周。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 数值格式。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。 当前分段加宽显示。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试。
+
+## 键盘操作
+
+- Tab：聚焦绘图区（图例勾选框在其前）。
+- ←/→（以及 ↑/↓）：依次读当前值与各分段，读数显示在图表下方并向读屏软件播报；第一次按键进入第一个点。
+- Home/End：第一个/最后一个点；Escape：清除读数。
+
+## 限制
+
+- 不做指针动画，值变化时直接切换。
@@ -0,0 +1,53 @@
+# 116 Treemap 矩形树图
+
+## 用途
+
+层级矩形树图：按大小平铺当前节点的子项（squarify 布局），点击或回车下钻有子项的矩形，返回按钮与面包屑回到上层；标签按面积显示并截断。
+
+## 最小示例
+
+```go
+var path []string
+root := mujica.ChartNode{Name: "Abbey", Children: []mujica.ChartNode{
+	{Name: "Library", Children: []mujica.ChartNode{{Name: "Psalters", Value: 30}, {Name: "Maps", Value: 10}}},
+	{Name: "Kitchen", Value: 25},
+}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Treemap(c, &path, root, mujica.TreemapOptions{Frame: mujica.ChartFrame{Label: "Rooms"}})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func Treemap(c *ui.Context, path *[]string, root ChartNode, opts TreemapOptions) ChartResult`；`ChartNode{Name, Value, Children}`，叶子的 `Value` 为大小，分支为子项之和；`*path` 是从根的子项起的名称路径。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 数值格式。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。 当前矩形内描边。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试；`ValueChanged()` 表示下钻、返回或点击面包屑改变了 `*path`。
+
+## 键盘操作
+
+- Tab：聚焦绘图区（图例勾选框在其前）。
+- ←/→（以及 ↑/↓）：按大小顺序在矩形间移动，读数显示在图表下方并向读屏软件播报；第一次按键进入第一个点。
+- Home/End：第一个/最后一个点；Escape：清除读数。
+- Enter/Space：下钻；Backspace：返回上一层；返回按钮与面包屑可用 Tab 到达。
+
+## 限制
+
+- 名称为空、兄弟同名或值为负时 panic；`*path` 指向不存在的节点时 panic。
+- 只显示当前节点的一层子项。
@@ -0,0 +1,53 @@
+# 117 Sunburst 旭日图
+
+## 用途
+
+层级环形图：中心是当前节点及总计，外圈依次是各层后代；点击或回车下钻，路径面包屑与返回按钮回到上层。
+
+## 最小示例
+
+```go
+var path []string
+root := mujica.ChartNode{Name: "Abbey", Children: []mujica.ChartNode{
+	{Name: "Library", Children: []mujica.ChartNode{{Name: "Psalters", Value: 30}, {Name: "Maps", Value: 10}}},
+	{Name: "Kitchen", Value: 25},
+}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Sunburst(c, &path, root, mujica.SunburstOptions{Frame: mujica.ChartFrame{Label: "Rooms"}})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func Sunburst(c *ui.Context, path *[]string, root ChartNode, opts SunburstOptions) ChartResult`；数据结构同 Treemap。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `Depth` | `int` | `3` | 显示的层数；负数 panic。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 数值格式。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。 外层颜色向表面色淡化，但保持 3:1 对比。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试；`ValueChanged()` 表示 `*path` 改变。
+
+## 键盘操作
+
+- Tab：聚焦绘图区（图例勾选框在其前）。
+- ←/→（以及 ↑/↓）：按深度优先顺序在扇区间移动，读数显示在图表下方并向读屏软件播报；第一次按键进入第一个点。
+- Home/End：第一个/最后一个点；Escape：清除读数。
+- Enter/Space：下钻到当前扇区；Backspace：返回上一层。
+
+## 限制
+
+- 弧长不足时不写标签，名称在读数中完整给出。
@@ -0,0 +1,49 @@
+# 118 SankeyChart 桑基图
+
+## 用途
+
+桑基图：节点按最长路径分列，列内顺序与传入顺序一致（稳定）；流量带宽度与值成比例；悬停或键盘读到节点或流量时，高亮经过它的全部路径。
+
+## 最小示例
+
+```go
+nodes := []mujica.SankeyNode{{ID: "tithe", Label: "Tithes"}, {ID: "fund", Label: "Fund"}, {ID: "roof", Label: "Roof"}}
+links := []mujica.SankeyLink{{From: "tithe", To: "fund", Value: 60}, {From: "fund", To: "roof", Value: 50}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.SankeyChart(c, nodes, links, mujica.SankeyChartOptions{Frame: mujica.ChartFrame{Label: "Money"}})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func SankeyChart(c *ui.Context, nodes []SankeyNode, links []SankeyLink, opts SankeyChartOptions) ChartResult`；`SankeyNode{ID, Label}`，`SankeyLink{From, To, Value}`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 数值格式。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。 高亮时其余流量淡化。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试。
+
+## 键盘操作
+
+- Tab：聚焦绘图区（图例勾选框在其前）。
+- ←/→（以及 ↑/↓）：先按节点、再按流量移动，读数显示在图表下方并向读屏软件播报；第一次按键进入第一个点。
+- Home/End：第一个/最后一个点；Escape：清除读数。
+
+## 限制
+
+- 链接成环、端点未知或值不为正时 panic。
+- 布局只在节点或链接切片变化时计算。
@@ -0,0 +1,51 @@
+# 119 NetworkGraph 网络图
+
+## 用途
+
+网络图：节点与边，使用调用方给定的坐标或简单的力导布局；拖动节点、拖动空白处平移、滚轮或 +/- 缩放。
+
+## 最小示例
+
+```go
+var state mujica.NetworkGraphState
+nodes := []mujica.GraphNode{{ID: "a", Label: "Abbot"}, {ID: "b", Label: "Prior"}, {ID: "c", Label: "Novice"}}
+edges := []mujica.GraphEdge{{From: "a", To: "b"}, {From: "b", To: "c"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.NetworkGraph(c, &state, nodes, edges, mujica.NetworkGraphOptions{Frame: mujica.ChartFrame{Label: "House"}, Force: true})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func NetworkGraph(c *ui.Context, s *NetworkGraphState, nodes []GraphNode, edges []GraphEdge, opts NetworkGraphOptions) ChartResult`；`GraphNode{ID, Label, X, Y}`，`GraphEdge{From, To}`。`NetworkGraphState` 保存拖动后的位置与视图：`Position(id)`、`Zoom()`、`ResetView()`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `Force` | `bool` | false | 用力导模拟布局（固定 300 步，结果确定）；最多 500 个节点。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。 当前节点外加圆环，相连的边加粗。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试。
+
+## 键盘操作
+
+- Tab：聚焦绘图区（图例勾选框在其前）。
+- ←/→（以及 ↑/↓）：在节点间移动，读数显示在图表下方并向读屏软件播报；第一次按键进入第一个点。
+- Home/End：第一个/最后一个点；Escape：清除读数。
+- Shift+方向键：移动当前节点；+/-：缩放；0：复位视图。
+
+## 限制
+
+- 布局只在节点或边的切片变化时重新计算，拖动不会重新适配视图。
+- 不支持边标签与有向箭头。
@@ -0,0 +1,53 @@
+# 120 RealtimeChart 实时图表
+
+## 用途
+
+实时折线图：调用方向 `RealtimeBuffer` 追加数据后刷新，图表显示截至最新数据的固定时间窗口；可暂停视图；组件自身不设计时器，隐藏或空闲时不重绘。
+
+## 最小示例
+
+```go
+buf := mujica.NewRealtimeBuffer(600, "Bell")
+start := time.Date(2026, 10, 5, 9, 0, 0, 0, time.UTC)
+for i := range 60 {
+	buf.Append(start.Add(time.Duration(i)*time.Second), float64(i%7))
+}
+var state mujica.RealtimeChartState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.RealtimeChart(c, &state, buf, mujica.RealtimeChartOptions{Frame: mujica.ChartFrame{Label: "Sound"}, Window: 30 * time.Second})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func RealtimeChart(c *ui.Context, s *RealtimeChartState, buf *RealtimeBuffer, opts RealtimeChartOptions) ChartResult`；`NewRealtimeBuffer(capacity, names...)` 保存最近 `capacity` 个样本，`Append(t, values...)` 每个序列一个值且时间不倒退。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Frame.Label` | `string` | 必填 | 图表的无障碍名称；为空 panic。 |
+| `Frame.Height` | `float32` | `240` | 绘图区高度（DIP）；负数 panic。 |
+| `Frame.Status` | `DataStatus` | `DataReady` | `DataLoading` 显示加载标记，`DataFailed` 显示错误与“重试”；占位与图表同尺寸。 |
+| `Frame.Error` | `string` | 内置“加载失败” | 失败时的具体说明。 |
+| `Frame.Empty` | `string` | 内置“暂无数据” | 无数据时的说明。 |
+| `Window` | `time.Duration` | 必填 | 显示的时间窗口，止于最新样本（暂停时止于暂停那一刻）。 |
+| `Format` | `func(float64) string` | 6 位有效数字 | 读数格式。 |
+
+## 状态
+
+默认、悬停读数、键盘读数（焦点环 + 当前点加粗或描边）、加载、失败（可重试）、无数据。图表区始终保持同样尺寸。 暂停时按钮显示“继续”，新数据继续进入缓冲区但不改变视图。
+
+## 事件
+
+返回 `ChartResult`：`Point` 为当前读数点（无则 -1）；`Changed()` 读数点变化；`Retried()` 点击了重试；`ValueChanged()` 表示暂停或继续；`Toggled()` 报告图例切换。
+
+## 键盘操作
+
+- Tab：暂停按钮、图例、图表。
+- 图表读数键同 LineChart；暂停按钮：Enter/Space。
+
+## 限制
+
+- 数据追加在后台时，请通过 `Window.Update` 回到界面线程追加并刷新。
+- 缓冲区按块丢弃旧样本，最多占用两倍容量。
@@ -0,0 +1,46 @@
+# 161 TickerTape
+
+行情滚动条。
+
+## 用途
+
+横向循环滚动的行情条，显示代码、价格与涨跌幅。指针悬停或键盘聚焦时暂停；减少动画时改为静态分页。
+
+## 最小示例
+
+```go
+items := []mujica.TickerItem{{Symbol: "MUJC", Price: 412.08, ChangePercent: -1.35}, {Symbol: "AVE", Price: 88.2, ChangePercent: 2.1}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.TickerTape(c, items, mujica.TickerTapeOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `items` | `[]TickerItem` | 必填 | 代码、价格、涨跌幅（%）。 |
+| `Decimals` | `int` | 2 | 价格小数位，0 表示 2，负数 panic。 |
+| `Speed` | `float32` | 40 | 每秒滚动的 DIP。 |
+| `PerPage` | `int` | 4 | 减少动画时每页条数。 |
+| `Label` | `string` | 内置“Market ticker” | 无障碍名称。 |
+
+## 状态
+
+滚动、暂停（悬停或聚焦）、静态分页（减少动画）、空列表。
+
+## 事件
+
+无业务事件。
+
+## 键盘操作
+
+Tab 聚焦滚动条即暂停；减少动画时 ←/→ 翻页，也可用上一页、下一页按钮。
+
+## 限制
+
+- 滚动以四分之一 DIP 取整，暂停时停止请求重绘。
+- 第二份副本用于无缝循环，屏幕阅读器可能读到重复内容。
+- 涨跌颜色由 `UseTrend(c, GreenUp|RedUp)` 按窗口设置，默认绿涨红跌；方向同时用箭头与正负号表达，不只靠颜色。
@@ -0,0 +1,43 @@
+# 162 QuoteCard
+
+报价卡片。
+
+## 用途
+
+显示代码、名称、现价、涨跌额与涨跌幅，并提供迷你图插槽。
+
+## 最小示例
+
+```go
+quote := mujica.Quote{Symbol: "MUJC", Name: "Ave Mujica Holdings", Price: 412.08, Change: -5.62, ChangePercent: -1.35}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.QuoteCard(c, quote, mujica.QuoteCardOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `q` | `Quote` | 必填 | Symbol 必填，空值 panic；Name、Price、Change、ChangePercent。 |
+| `Decimals` | `int` | 2 | 价格与涨跌额小数位。 |
+| `Chart` | `func()` | nil | 迷你图插槽，高 40 DIP，例如 Sparkline。 |
+
+## 状态
+
+默认；涨、跌、平三种方向。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+卡片本身不获取焦点；插槽内控件自行处理键盘。
+
+## 限制
+
+- 不计算涨跌，数值由调用方提供。
+- 涨跌颜色由 `UseTrend(c, GreenUp|RedUp)` 按窗口设置，默认绿涨红跌；方向同时用箭头与正负号表达，不只靠颜色。
@@ -0,0 +1,46 @@
+# 163 PriceText
+
+价格文本。
+
+## 用途
+
+按固定小数位与千分位显示价格；可与参考价比较着色并加箭头；价格变化时闪烁一次。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.UseTrend(c, mujica.RedUp)
+	mujica.PriceText(c, 18234.5, mujica.PriceTextOptions{Compare: true, Reference: 18000})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `value` | `float64` | 必填 | 价格。 |
+| `Decimals` | `int` | 2 | 小数位，0 表示 2，负数 panic。 |
+| `NoGrouping` | `bool` | false | 不显示千分位。 |
+| `Compare / Reference` | `bool / float64` | false / 0 | 按相对 Reference 的方向着色并加箭头。 |
+| `NoFlash` | `bool` | false | 变化时不闪烁。 |
+| `Size` | `float32` | 正文字号 | 字号（DIP），随系统文字缩放。 |
+
+## 状态
+
+默认；上涨、下跌、持平；变化闪烁（360 ms 淡出）。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点。
+
+## 限制
+
+- 闪烁由帧间比较值得出：同一元素的值改变才会闪烁。减少动画时不闪烁，结束后不再请求重绘。
+- 涨跌颜色由 `UseTrend(c, GreenUp|RedUp)` 按窗口设置，默认绿涨红跌；方向同时用箭头与正负号表达，不只靠颜色。
@@ -0,0 +1,42 @@
+# 164 PriceChangeBadge
+
+涨跌徽标。
+
+## 用途
+
+显示涨跌额与涨跌幅，带箭头、正负号与语义底色。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.PriceChangeBadge(c, -5.62, -1.35, mujica.PriceChangeBadgeOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `change` | `float64` | 必填 | 涨跌额。 |
+| `percent` | `float64` | 必填 | 涨跌幅（%），固定 2 位小数。 |
+| `Decimals` | `int` | 2 | 涨跌额小数位。 |
+| `HidePercent` | `bool` | false | 只显示涨跌额。 |
+
+## 状态
+
+上涨、下跌、持平。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点；无障碍名称含方向词与数值。
+
+## 限制
+
+- 涨跌颜色由 `UseTrend(c, GreenUp|RedUp)` 按窗口设置，默认绿涨红跌；方向同时用箭头与正负号表达，不只靠颜色。
@@ -0,0 +1,52 @@
+# 165 OrderBook
+
+盘口。
+
+## 用途
+
+按价格显示卖档（上）与买档（下），带累计深度条与价差；可按价格步长合并档位；点击档位回传价格。
+
+## 最小示例
+
+```go
+var state mujica.OrderBookState
+book := mujica.OrderBookData{
+	Bids: []mujica.BookLevel{{Price: 100.00, Size: 5}, {Price: 99.99, Size: 3}},
+	Asks: []mujica.BookLevel{{Price: 100.01, Size: 1}, {Price: 100.02, Size: 2}},
+}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if price, side, ok := mujica.OrderBook(c, &state, book, mujica.OrderBookOptions{Groups: []float64{0.01, 0.05}}).Clicked(); ok {
+		fmt.Println("order at", price, side)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `s` | `*OrderBookState` | 必填 | Group 为合并步长，0 取 Groups 第一项；不在 Groups 中 panic。 |
+| `book` | `OrderBookData` | 必填 | Bids、Asks 与 Version（原地修改时递增）。 |
+| `Decimals / SizeDecimals` | `int` | 2 / 0 | 价格与数量小数位。 |
+| `Depth` | `int` | 8 | 每侧档数。 |
+| `Groups` | `[]float64` | nil | 可选合并步长，须为价格精度的整数倍，否则 panic。 |
+| `Disabled` | `bool` | false | 禁用点击与合并选择。 |
+
+## 状态
+
+默认、悬停、聚焦、禁用；空盘口时只显示表头。
+
+## 事件
+
+`OrderBookResult.Clicked()` 返回被点击档位的价格与方向。
+
+## 键盘操作
+
+Tab 进入档位列表，↑/↓ 在档位间移动，Enter/Space 选中价格。
+
+## 限制
+
+- 合并以整数价格单位计算：买档向下取整、卖档向上取整。只在数据或步长变化时重新聚合。
+- 涨跌颜色由 `UseTrend(c, GreenUp|RedUp)` 按窗口设置，默认绿涨红跌；方向同时用箭头与正负号表达，不只靠颜色。
@@ -0,0 +1,46 @@
+# 166 Level2Quotes
+
+多档行情。
+
+## 用途
+
+并排显示买卖各 N 档的价格、数量与委托笔数；档位变化时高亮一次，并以箭头标出数量增减。
+
+## 最小示例
+
+```go
+data := mujica.Level2Data{
+	Bids: []mujica.L2Level{{Price: 100.00, Size: 500, Orders: 12}},
+	Asks: []mujica.L2Level{{Price: 100.01, Size: 200, Orders: 3}},
+}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Level2Quotes(c, data, mujica.Level2QuotesOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `data` | `Level2Data` | 必填 | Bids、Asks，最优价在前。 |
+| `Decimals / SizeDecimals` | `int` | 2 / 0 | 价格与数量小数位。 |
+| `Levels` | `int` | 5 | 每侧档数；不足的档位显示“—”。 |
+
+## 状态
+
+默认、档位变化高亮（减少动画时只显示箭头）、空档。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点；每行有包含档位、价格、数量和笔数的无障碍名称。
+
+## 限制
+
+- 价格变化视为新档位，不标增减箭头。
+- 涨跌颜色由 `UseTrend(c, GreenUp|RedUp)` 按窗口设置，默认绿涨红跌；方向同时用箭头与正负号表达，不只靠颜色。
@@ -0,0 +1,48 @@
+# 167 TimeAndSales
+
+逐笔成交。
+
+## 用途
+
+逐笔成交列表，最新在上，只构建可见行；大单以菱形与粗体标记；可暂停跟随。
+
+## 最小示例
+
+```go
+var state mujica.TimeAndSalesState
+trades := []mujica.TradePrint{{ID: "1", Time: time.Now(), Price: 100.01, Size: 300, Side: mujica.SideBuy}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.TimeAndSales(c, &state, trades, mujica.TimeAndSalesOptions{LargeSize: 1000})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `s` | `*TimeAndSalesState` | 必填 | Paused 暂停跟随。 |
+| `trades` | `[]TradePrint` | 必填 | 按时间先后追加；ID 唯一。 |
+| `Decimals / SizeDecimals` | `int` | 2 / 0 | 价格与数量小数位。 |
+| `LargeSize` | `float64` | 0 | 数量达到即标记为大单。 |
+| `Height` | `float32` | 320 | 高度（DIP）。 |
+| `Status / Error` | `DataStatus / string` | Ready | 加载、失败等状态。 |
+
+## 状态
+
+跟随、暂停（显示新成交数量）、加载、失败、空列表。
+
+## 事件
+
+`ChoiceResult.Changed()` 在暂停或继续时为 true。
+
+## 键盘操作
+
+Tab 到达暂停按钮（Enter/Space 切换）与列表；列表内 ↑/↓ 移动。
+
+## 限制
+
+- 基于 List 虚拟化，100,000 条成交只构建可见行。
+- 暂停时冻结显示的条数，新成交不打断阅读。
+- 涨跌颜色由 `UseTrend(c, GreenUp|RedUp)` 按窗口设置，默认绿涨红跌；方向同时用箭头与正负号表达，不只靠颜色。
@@ -0,0 +1,50 @@
+# 168 DepthLadder
+
+价格阶梯。
+
+## 用途
+
+按最小变动价位排列的价格阶梯（DOM）：买量、价格、卖量三列，最新价居中并加框；点击买量或卖量单元格回调下单。
+
+## 最小示例
+
+```go
+var state mujica.DepthLadderState
+book := mujica.OrderBookData{Bids: []mujica.BookLevel{{Price: 100, Size: 5}}, Asks: []mujica.BookLevel{{Price: 100.01, Size: 2}}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if price, side, ok := mujica.DepthLadder(c, &state, 100, book, mujica.DepthLadderOptions{TickSize: 0.01}).Clicked(); ok {
+		fmt.Println("place", side, "at", price)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `s` | `*DepthLadderState` | 必填 | Offset 为相对最新价滚动的档数。 |
+| `last` | `float64` | 必填 | 最新价。 |
+| `book` | `OrderBookData` | 必填 | 盘口数据。 |
+| `TickSize` | `float64` | 必填 | 最小变动价位，须为价格精度的整数倍，否则 panic。 |
+| `Decimals / SizeDecimals` | `int` | 2 / 0 | 小数位。 |
+| `Rows` | `int` | 15 | 显示的行数。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+默认、悬停、聚焦、最新价行（底色、框线与菱形）、已滚动（显示回到最新价按钮）、禁用。
+
+## 事件
+
+`DepthLadderResult.Clicked()` 返回价格与方向（买量列为买入，卖量列为卖出）。
+
+## 键盘操作
+
+Tab 进入阶梯，方向键在单元格间移动，Enter/Space 下单；PageUp/PageDown 滚动半屏；滚轮逐档滚动。
+
+## 限制
+
+- 只构建可见行；按价位建立的数量索引只在数据变化时重建。
+- 涨跌颜色由 `UseTrend(c, GreenUp|RedUp)` 按窗口设置，默认绿涨红跌；方向同时用箭头与正负号表达，不只靠颜色。
@@ -0,0 +1,41 @@
+# 169 SpreadIndicator
+
+价差指示。
+
+## 用途
+
+显示卖一减买一的价差与占中间价的百分比；超过阈值或买卖倒挂时给出带图标的文字提示。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.SpreadIndicator(c, 99.95, 100.05, mujica.SpreadIndicatorOptions{WarnPercent: 0.5})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `bid / ask` | `float64` | 必填 | 买一价与卖一价。 |
+| `Decimals` | `int` | 2 | 价差小数位。 |
+| `WarnPercent` | `float64` | 0 | 价差百分比达到即提示；0 不提示，负数 panic。 |
+
+## 状态
+
+正常、价差过大、倒挂。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点；以状态角色读出。
+
+## 限制
+
+- 无。
@@ -0,0 +1,41 @@
+# 170 BidAskBar
+
+买卖力量条。
+
+## 用途
+
+以分段条对比买卖成交量，两端标出占比与数量。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.BidAskBar(c, 6234, 3820, mujica.BidAskBarOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `bid / ask` | `float64` | 必填 | 买量与卖量，负数或 NaN panic。 |
+| `Decimals` | `int` | 0 | 数量小数位。 |
+| `Label` | `string` | 内置“Bid and ask volume” | 无障碍名称。 |
+
+## 状态
+
+默认；两者都为 0 时显示中性灰条与 50%。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点；以计量角色读出买卖占比。
+
+## 限制
+
+- 涨跌颜色由 `UseTrend(c, GreenUp|RedUp)` 按窗口设置，默认绿涨红跌；方向同时用箭头与正负号表达，不只靠颜色。
@@ -0,0 +1,52 @@
+# 171 OrderEntry
+
+下单面板。
+
+## 用途
+
+限价、市价、止损与条件限价单的录入：方向、类型、数量、价格、触发价与有效期；同步与调用方异步校验；预估金额；提交防重入。建立在 Form 之上。
+
+## 最小示例
+
+```go
+var state mujica.OrderEntryState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if order, ok := mujica.OrderEntry(c, &state, mujica.OrderEntryOptions{Symbol: "MUJC", Last: 100.2}).Submitted(); ok {
+		fmt.Println("place", order.Quantity)
+		state.EndSubmit("")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `s` | `*OrderEntryState` | 必填 | Draft 为当前订单，Form 为表单状态。 |
+| `Symbol` | `string` | 必填 | 代码，空值 panic。 |
+| `Last` | `float64` | 0 | 最新价，用于市价预估和止损方向检查。 |
+| `TickSize / LotSize` | `float64` | 0.01 / 1 | 价格与数量步长。 |
+| `MaxQuantity` | `float64` | 0 | 数量上限，0 不限。 |
+| `Initial` | `OrderDraft` | 买入限价 | 重置恢复的订单。 |
+| `Validate` | `func(OrderDraft) string` | nil | 调用方同步规则。 |
+| `Check` | `func(OrderDraft, uint64)` | nil | 异步检查（如可用资金），以 `s.Resolve(version, msg)` 回传；旧版本结果被丢弃。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+默认、字段错误（失焦或提交后）、异步检查中、提交中（按钮加载）、表单错误、禁用。
+
+## 事件
+
+`OrderEntryResult.Submitted()` 返回通过全部校验的订单；处理完毕后调用 `s.EndSubmit(err)`。
+
+## 键盘操作
+
+Tab 依次经过方向、类型、各字段与按钮；数量与价格字段 ↑/↓ 按步长调整；提交失败聚焦第一个错误字段。
+
+## 限制
+
+- 止损单检查：买入触发价须高于最新价，卖出须低于。
+- 数量字段的异步检查覆盖整张订单：任一字段变化都会让旧结果失效。
@@ -0,0 +1,47 @@
+# 172 QuickTradeButtons
+
+快速交易按钮。
+
+## 用途
+
+以预设数量一键市价买入或卖出；可配置在发送前就近确认。
+
+## 最小示例
+
+```go
+quantity := 10.0
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if side, q, ok := mujica.QuickTradeButtons(c, &quantity, mujica.QuickTradeButtonsOptions{Symbol: "MUJC", Confirm: true}).Traded(); ok {
+		fmt.Println(side, q)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `quantity` | `*float64` | 必填 | 当前数量，须为 Presets 之一，0 取第一项。 |
+| `Symbol` | `string` | 必填 | 代码。 |
+| `Presets` | `[]float64` | 1, 10, 100 | 数量预设。 |
+| `Decimals` | `int` | 0 | 数量小数位。 |
+| `Confirm` | `bool` | false | 发送前弹出确认，默认聚焦取消。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+默认、悬停、按下、聚焦、确认中、禁用。
+
+## 事件
+
+`QuickTradeResult.Traded()` 返回方向与数量。
+
+## 键盘操作
+
+Tab 到达数量分段与买卖按钮；Enter/Space 触发；确认浮层中 Enter 默认取消，Escape 关闭。
+
+## 限制
+
+- 涨跌颜色由 `UseTrend(c, GreenUp|RedUp)` 按窗口设置，默认绿涨红跌；方向同时用箭头与正负号表达，不只靠颜色。
@@ -0,0 +1,49 @@
+# 173 PositionTable
+
+持仓表。
+
+## 用途
+
+持仓列表：数量、成本、现价、市值、浮动盈亏与比例，每行提供平仓操作。基于 DataTable，以稳定行 ID 保存选择与排序。
+
+## 最小示例
+
+```go
+var state mujica.DataTableState[string]
+rows := []mujica.PositionRow{{ID: "p1", Symbol: "MUJC", Quantity: 100, AvgCost: 400, Price: 412.08}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if id, ok := mujica.PositionTable(c, &state, rows, mujica.PositionTableOptions{}).Acted(); ok {
+		fmt.Println("close", id)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `s` | `*DataTableState[string]` | 必填 | 表格状态。 |
+| `rows` | `[]PositionRow` | 必填 | ID 必须稳定。 |
+| `Decimals` | `int` | 2 | 小数位。 |
+| `Version` | `int` | 0 | 原地修改行时递增。 |
+| `Status / Error` | `DataStatus / string` | Ready | 加载与失败状态。 |
+| `Disabled` | `bool` | false | 禁用平仓。 |
+
+## 状态
+
+默认、排序、选中、加载、失败、空、禁用。
+
+## 事件
+
+`TableActionResult.Acted()` 返回要平仓的行 ID；`Table` 为 DataTable 事件。
+
+## 键盘操作
+
+沿用 DataTable 的键盘操作；Tab 到达各行的平仓按钮。
+
+## 限制
+
+- 只构建可见行。
+- 涨跌颜色由 `UseTrend(c, GreenUp|RedUp)` 按窗口设置，默认绿涨红跌；方向同时用箭头与正负号表达，不只靠颜色。
@@ -0,0 +1,48 @@
+# 174 OrderTable
+
+委托表。
+
+## 用途
+
+委托列表：方向、类型、价格、成交进度与状态，按状态筛选；进行中的委托提供撤单。基于 DataTable。
+
+## 最小示例
+
+```go
+var state mujica.OrderTableState
+rows := []mujica.OrderRow{{ID: "o1", Symbol: "MUJC", Side: mujica.SideBuy, Price: 99.5, Quantity: 100, Filled: 40, Status: mujica.OrderPartial}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if id, ok := mujica.OrderTable(c, &state, rows, mujica.OrderTableOptions{}).Acted(); ok {
+		fmt.Println("cancel", id)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `s` | `*OrderTableState` | 必填 | Filter 为状态筛选，Table 为表格状态。 |
+| `rows` | `[]OrderRow` | 必填 | Filled 不得超过 Quantity，否则 panic。 |
+| `Decimals / QuantityDecimals` | `int` | 2 / 0 | 小数位。 |
+| `Version` | `int` | 0 | 原地修改行时递增。 |
+| `Status / Error` | `DataStatus / string` | Ready | 加载与失败状态。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+全部、进行中、已成交、已关闭四种筛选；部分成交进度条；禁用。
+
+## 事件
+
+`TableActionResult.Acted()` 返回要撤销的委托 ID。
+
+## 键盘操作
+
+筛选分段用方向键切换；表格沿用 DataTable 键盘操作；Tab 到达撤单按钮。
+
+## 限制
+
+- 筛选只在数据或条件变化时执行。
@@ -0,0 +1,49 @@
+# 175 TradeHistoryTable
+
+成交记录表。
+
+## 用途
+
+成交记录：时间、代码、方向、价格、数量与手续费；按日期范围筛选；导出当前范围的记录交给调用方。
+
+## 最小示例
+
+```go
+var state mujica.TradeHistoryTableState
+rows := []mujica.FillRow{{ID: "f1", Time: time.Now(), Symbol: "MUJC", Side: mujica.SideBuy, Price: 400, Quantity: 10, Fee: 1.2}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if fills, ok := mujica.TradeHistoryTable(c, &state, rows, mujica.TradeHistoryTableOptions{}).Exported(); ok {
+		fmt.Println("export", len(fills))
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `s` | `*TradeHistoryTableState` | 必填 | Range 为日期范围，零值不筛选。 |
+| `rows` | `[]FillRow` | 必填 | 成交记录。 |
+| `Decimals / QuantityDecimals` | `int` | 2 / 0 | 小数位。 |
+| `Version` | `int` | 0 | 原地修改行时递增。 |
+| `Status / Error` | `DataStatus / string` | Ready | 加载与失败状态。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+全部日期、指定范围、空范围、加载、失败、禁用。
+
+## 事件
+
+`TradeHistoryResult.Exported()` 返回导出请求时当前范围内的记录。
+
+## 键盘操作
+
+日期范围选择器与按钮按 Tab 顺序；表格沿用 DataTable 键盘操作。
+
+## 限制
+
+- 只回传数据，不生成文件：导出格式与写入由调用方负责。
+- 日期按每条记录自身时区的日期比较。
@@ -0,0 +1,44 @@
+# 176 PnLDisplay
+
+盈亏显示。
+
+## 用途
+
+并列显示已实现、未实现与当日盈亏，带正负号、箭头与语义色；可切换隐私遮蔽。
+
+## 最小示例
+
+```go
+hidden := false
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.PnLDisplay(c, mujica.PnL{Realized: 1200.5, Unrealized: -340.2, Today: 88}, &hidden, mujica.PnLDisplayOptions{Currency: "$"})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `pnl` | `PnL` | 必填 | Realized、Unrealized、Today。 |
+| `hidden` | `*bool` | 必填 | 为 true 时以“••••”遮蔽。 |
+| `Decimals` | `int` | 2 | 小数位。 |
+| `Currency` | `string` | "" | 金额前缀，例如 "$"。 |
+
+## 状态
+
+正、负、零；已遮蔽。
+
+## 事件
+
+`ChoiceResult.Changed()` 在遮蔽切换时为 true。
+
+## 键盘操作
+
+Tab 到达遮蔽按钮，Enter/Space 切换。
+
+## 限制
+
+- 遮蔽时无障碍名称只读出“已隐藏”，不读出金额。
+- 涨跌颜色由 `UseTrend(c, GreenUp|RedUp)` 按窗口设置，默认绿涨红跌；方向同时用箭头与正负号表达，不只靠颜色。
@@ -0,0 +1,46 @@
+# 177 LeverageSlider
+
+杠杆滑块。
+
+## 用途
+
+在预设杠杆档位间选择草稿值，显示高风险与极高风险区间提示，按“确认”后才写入值。
+
+## 最小示例
+
+```go
+leverage := 5.0
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.LeverageSlider(c, &leverage, mujica.LeverageSliderOptions{Warning: 10, Danger: 50}).Changed() {
+		fmt.Println("leverage", leverage)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `value` | `*float64` | 必填 | 当前杠杆，须为 Levels 之一。 |
+| `Levels` | `[]float64` | 1–100 八档 | 递增档位，至少两档。 |
+| `Warning / Danger` | `float64` | 0 | 高风险与极高风险起点；Danger 须大于 Warning。 |
+| `Label` | `string` | 内置“Leverage” | 名称。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+默认、聚焦、拖动、高风险、极高风险、草稿未确认、禁用。
+
+## 事件
+
+`ChoiceResult.Changed()` 在确认写入时为 true。
+
+## 键盘操作
+
+Tab 聚焦滑块：←/↓ 与 →/↑ 逐档、Home/End 到两端；Tab 到达确认按钮。
+
+## 限制
+
+- 滑块命中区高 44 DIP；风险区间以色带、图标和文字共同表达。
@@ -0,0 +1,41 @@
+# 178 MarginIndicator
+
+保证金率指示。
+
+## 用途
+
+显示保证金率（维持保证金 / 权益）及其与警戒线、强平线的关系。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.MarginIndicator(c, 0.86, mujica.MarginIndicatorOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `ratio` | `float64` | 必填 | 保证金率，0 以上。 |
+| `Warning / Liquidation` | `float64` | 0.8 / 1 | 警戒与强平线；须 0 < Warning < Liquidation。 |
+| `Label` | `string` | 内置“Margin ratio” | 名称。 |
+
+## 状态
+
+安全、追加保证金、强制平仓。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点；以计量角色读出比率、状态与两条线。
+
+## 限制
+
+- 状态同时用图标、文字与颜色表达；两条线粗细不同，并在下方以文字标注。
@@ -0,0 +1,41 @@
+# 179 RiskMeter
+
+风险等级。
+
+## 用途
+
+分段刻度显示风险等级，当前段上方有菱形标记，并显示等级名称与说明。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.RiskMeter(c, 4, mujica.RiskMeterOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `level` | `int` | 必填 | 从 1 开始，超出范围 panic。 |
+| `Levels` | `[]RiskLevel` | 内置五级 | 各级名称与说明，至少两级。 |
+| `Label` | `string` | 内置“Risk level” | 名称。 |
+
+## 状态
+
+各等级。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点；以计量角色读出“第 n 级，共 N 级”和名称。
+
+## 限制
+
+- 颜色只辅助：位置标记与等级文字同时表达等级。
@@ -0,0 +1,52 @@
+# 180 OrderConfirmDialog
+
+下单确认对话框。
+
+## 用途
+
+以模态对话框展示下单摘要与风险提示，默认聚焦取消；可要求勾选确认后才能下单。
+
+## 最小示例
+
+```go
+open := true
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.OrderConfirmDialog(c, &open, mujica.OrderConfirmDialogOptions{
+		Lines:       []mujica.OrderSummaryLine{{Label: "Symbol", Value: "MUJC"}, {Label: "Quantity", Value: "100"}},
+		Risk:        "Leveraged products can lose more than the deposit.",
+		Acknowledge: "I understand the risk",
+	})
+	if r.Confirmed {
+		fmt.Println("send order")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `open` | `*bool` | 必填 | 是否显示。 |
+| `Lines` | `[]OrderSummaryLine` | 必填 | 摘要行，空值 panic。 |
+| `Title` | `string` | 内置“Confirm order” | 标题。 |
+| `Risk` | `string` | "" | 风险提示。 |
+| `Acknowledge` | `string` | "" | 二次确认复选框文字；设置后须勾选才能下单。 |
+| `ConfirmLabel` | `string` | 内置“Place order” | 确认按钮文字。 |
+
+## 状态
+
+打开、未勾选（下单按钮禁用）、已勾选。
+
+## 事件
+
+`AlertDialogResult.Confirmed` / `Canceled`；Escape 视为取消。
+
+## 键盘操作
+
+打开时焦点在取消上；Tab 在复选框与按钮间移动；Escape 取消。点击遮罩不关闭。
+
+## 限制
+
+- 每次打开都需重新勾选。
@@ -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）包裹。
@@ -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 在显示时测量，未显示消息按已测高度估算，长距离跳转时滚动条可能微调。
@@ -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 中或气泡下方。
@@ -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 的日期分隔显示。
@@ -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），它的增量解析同样适合流式输出。
@@ -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 标题、链接引用定义，列表项内不支持多段落。
+- 表格单元格按纯文本显示，不解析行内样式。
+- 源文本被整体替换（不是在末尾追加）时重新解析全部块。
@@ -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 触发。
+
+## 限制
+
+- 着色是逐行的词法着色，不做语法分析；块注释可跨行。
+- 不做虚拟化，适合消息中的代码片段，不适合上万行文件。
@@ -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 起）。
@@ -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。
+
+## 限制
+
+- 查看器只包含已加载的图片，序号按已加载图片计算。
@@ -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 触发。
+
+## 限制
+
+- 组件不读取文件、不下载：打开与下载由调用方完成。
@@ -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 到开头与结尾。
+
+## 限制
+
+- 不解码音频、不生成波形：采样由调用方提供。
@@ -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 触发。
+
+## 限制
+
+- 组件不联网：标题、描述与缩略图都由调用方提供。
@@ -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 触发。辅助技术读到“回复 作者：摘要”。
+
+## 限制
+
+- 只显示一行摘要，不渲染原消息的格式。
@@ -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 触发。
+
+## 限制
+
+- 不内置复制内容与朗读：调用方收到操作后自行处理。
@@ -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 依次到文本框、取消、保存。
+
+## 限制
+
+- 不保存历史：分支与原文由调用方保存。
@@ -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 序列，避免到达首末分支时焦点停在禁用按钮上。
@@ -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。
@@ -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 展开与折叠。
+
+## 限制
+
+- 思考中每秒重绘一次以更新秒数；折叠且完成后不再重绘。
@@ -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 条新消息”。
+
+## 限制
+
+- 按钮以绝对定位贴在父元素底部，父元素需要占满滚动区域。
@@ -0,0 +1,35 @@
+# 220 TypingIndicator 正在输入
+
+## 用途
+
+对方正在输入的提示：三个依次明暗变化的圆点；减少动画时改为静态文字“某某 正在输入…”。
+
+## 最小示例
+
+```go
+mujica.TypingIndicator(c, "Herald")
+```
+
+签名：`func TypingIndicator(c *ui.Context, name string) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `name` | `string` | 必填 | 正在输入的一方；为空 panic。 |
+
+## 状态
+
+动画 / 静态文字；状态角色，辅助技术读到“某某 正在输入…”。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点。
+
+## 限制
+
+- 动画只在显示时请求下一帧，移出界面后停止重绘。
@@ -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`。
@@ -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 位之外另设快捷键。
@@ -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 行为）。
+
+## 限制
+
+- 匹配高亮为不区分大小写的逐字符匹配，不做分词、拼音或模糊匹配；排序完全由调用方决定。
+- 结果行固定高度（标题一行、片段一行），片段超长时截断。
@@ -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`，其展开状态可被辅助技术读到。
+- 列表未虚拟化，适合数百个项目以内。
@@ -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 数由调用方计算；面板只做求和与比例显示。
@@ -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。
@@ -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 选择。
+
+## 限制
+
+- 建议换行排列；数量很多时请调用方截取。
@@ -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 选择。
+
+## 限制
+
+- 过滤只在模板切片、查询或分类变化时重算。
+- 变量为简单占位替换，不支持条件或循环。
@@ -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`。
@@ -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：取消。
+
+## 限制
+
+- 表单不发送任何数据；提交由调用方完成。
@@ -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日 星期二”。
@@ -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，辅助技术读出阶段文字。
+
+## 限制
+
+- 动画只在绘制时请求下一帧；组件隐藏后不再重绘。
@@ -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 窗口快捷键注册，焦点控件若注册了同一组合键会优先获得。
@@ -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：保存（有改动且未超限时）。
+
+## 限制
+
+- 超出上限不会截断文字，只阻止保存。
@@ -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` 位小数四舍五入，不用于结算。
@@ -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 组件）。
+- 消息列表虚拟化，只构建可见消息。
@@ -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 只加标题与作者行，原文原样写入。
+- 预览只在格式、范围或消息变化时重新生成。
@@ -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），不使用系统菜单。
@@ -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 打开。
+
+## 限制
+
+- 卡片不渲染产物内容，面板由调用方实现。
@@ -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 组件，布局与其一致。
@@ -0,0 +1,47 @@
+# 261 ToolCallCard 工具调用卡片
+
+## 用途
+
+显示一次工具调用：工具名、状态、耗时，参数与结果可折叠，JSON 自动格式化并高亮。
+
+## 最小示例
+
+```go
+call := mujica.ToolCall{ID: "1", Name: "read_file", Args: "{\"path\":\"ledger.md\"}",
+	Result: "{\"lines\":40}", State: mujica.AgentDone, Duration: 420 * time.Millisecond}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.ToolCallCard(c, call, mujica.ToolCallCardOptions{OpenArgs: true})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func ToolCallCard(c *ui.Context, call ToolCall, opts ToolCallCardOptions) ChoiceResult`。`call.Name` 为空时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `OpenArgs` | `bool` | `false` | 参数区初始展开。 |
+| `OpenResult` | `bool` | `false` | 结果区初始展开。 |
+| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
+
+## 状态
+
+- `ToolCall` 字段：`ID`、`Name`、`Args`（JSON 或纯文本）、`Result`、`Error`（非空时替代结果并以错误色显示）、`State`、`Duration`。
+- `AgentState`：`AgentPending`、`AgentPlanning`、`AgentRunning`、`AgentWaiting`、`AgentDone`、`AgentFailed`、`AgentSkipped`，越界 panic。状态同时由图标形状和文字表达，不只靠颜色。
+- 仅完成或失败时显示耗时；合法 JSON 以两格缩进格式化，非 JSON 原样显示。
+- 结果超过 200 行时虚拟化，只构建可见行。
+
+## 事件
+
+- `Changed()`：用户展开或折叠参数、结果。
+
+## 键盘操作
+
+- Tab 到“参数”“结果”折叠按钮，Enter / Space 展开或折叠。
+
+## 限制
+
+- 展开状态保存在卡片元素上；在列表中请用稳定 `Key` 包裹每张卡片。
+- 高亮只区分关键字、字符串、数字和标点，不做 JSON 结构校验提示。
@@ -0,0 +1,47 @@
+# 262 ToolCallGroup 工具调用组
+
+## 用途
+
+把连续的工具调用折叠成一组，标题行显示调用次数、总耗时与失败数。
+
+## 最小示例
+
+```go
+open := false
+calls := []mujica.ToolCall{
+	{ID: "a", Name: "list_dir", State: mujica.AgentDone, Duration: 300 * time.Millisecond},
+	{ID: "b", Name: "read_file", State: mujica.AgentFailed, Error: "not found"},
+}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.ToolCallGroup(c, &open, calls, mujica.ToolCallGroupOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func ToolCallGroup(c *ui.Context, open *bool, calls []ToolCall, opts ToolCallGroupOptions) ChoiceResult`。`open` 为 nil、调用 `ID` 为空或重复时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Title` | `string` | “N 次工具调用” | 替换内置标题。 |
+| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
+
+## 状态
+
+- 组的状态：有调用执行中为执行中，否则有失败为失败，否则为完成。
+- 失败数以文字“N 次失败”显示。
+- 展开后每次调用用 ToolCallCard 显示。
+
+## 事件
+
+- `Changed()`：用户展开或折叠该组。
+
+## 键盘操作
+
+- Tab 到组标题，Enter / Space 展开或折叠；组内卡片各自可折叠。
+
+## 限制
+
+- 总耗时是各调用耗时之和，不扣除并行重叠。
@@ -0,0 +1,51 @@
+# 263 ToolApprovalDialog 工具审批对话框
+
+## 用途
+
+工具执行前请求批准：显示工具名、执行理由和参数预览，允许或拒绝。遵循 Dialog 与 AlertDialog 规则。
+
+## 最小示例
+
+```go
+open := true
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.ToolApprovalDialog(c, &open, mujica.ToolApprovalOptions{
+		Tool: "delete_files", Args: "{\"glob\":\"*.tmp\"}", Reason: "Clean the build folder.",
+	})
+	if r.Allowed {
+		fmt.Println("run the tool")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func ToolApprovalDialog(c *ui.Context, open *bool, opts ToolApprovalOptions) ToolApprovalResult`。`Tool` 为空时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Tool` | `string` | 必填 | 工具名。 |
+| `Args` | `string` | `""` | 参数，合法 JSON 会格式化高亮。 |
+| `Reason` | `string` | `""` | Agent 给出的理由，作为对话框说明。 |
+
+## 状态
+
+- 打开时焦点在“拒绝”；点击遮罩不做任何事。
+- 参数过长时在预览区内滚动，按钮始终可见。
+
+## 事件
+
+- `Allowed`：点击允许，或焦点在允许上按 Enter / Space。
+- `Denied`：点击拒绝、焦点在拒绝上按 Enter、或按 Escape。
+- `Element`：对话框面板，关闭时为 nil。
+
+## 键盘操作
+
+- 打开时焦点在拒绝，Enter 只触发聚焦按钮，必须 Tab 到“允许”才能批准。
+- Escape 等同拒绝；Tab 在对话框内循环；关闭后焦点回到打开者。
+
+## 限制
+
+- 输入法组合期间按 Escape 仍会拒绝（MyGo 不公开组合状态，`ui/editor.go:73`）。
@@ -0,0 +1,48 @@
+# 264 PermissionPrompt 权限请求
+
+## 用途
+
+请求权限：允许一次、始终允许或拒绝，并说明“始终允许”覆盖的范围。
+
+## 最小示例
+
+```go
+open := true
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.PermissionPrompt(c, &open, mujica.PermissionPromptOptions{
+		Title: "Write to the ledger?", Scope: "Write access to ~/court/ledger",
+	})
+	if r.Choice == mujica.PermissionAllowAlways {
+		fmt.Println("remember the grant")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func PermissionPrompt(c *ui.Context, open *bool, opts PermissionPromptOptions) PermissionResult`。`Title` 或 `Scope` 为空时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Title` | `string` | 必填 | 问题。 |
+| `Description` | `string` | `""` | 补充说明。 |
+| `Scope` | `string` | 必填 | “始终允许”覆盖的范围。 |
+
+## 状态
+
+- 范围说明放在带锁形图标的框内。
+- 打开时焦点在“拒绝”，点击遮罩无效。
+
+## 事件
+
+- `Choice`：本帧的选择，`PermissionAllowOnce`、`PermissionAllowAlways`、`PermissionDeny`；无选择为 `PermissionNone`。Escape 记为拒绝。
+
+## 键盘操作
+
+- 打开时焦点在拒绝；Tab 依次到“始终允许”“允许一次”；Enter 触发聚焦按钮；Escape 拒绝。
+
+## 限制
+
+- 组件不保存授权，记住“始终允许”由调用方负责。
@@ -0,0 +1,51 @@
+# 265 AgentStepList 执行步骤列表
+
+## 用途
+
+以时间线显示 Agent 的执行步骤：当前步加框标出，步骤可展开详情，失败步提供重试。
+
+## 最小示例
+
+```go
+steps := []mujica.AgentStep{
+	{ID: "read", Title: "Read the guest list", State: mujica.AgentDone, Duration: time.Second},
+	{ID: "seat", Title: "Assign the seats", State: mujica.AgentFailed, Detail: "Table 4 is full."},
+	{ID: "send", Title: "Send invitations", State: mujica.AgentPending},
+}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if r := mujica.AgentStepList(c, steps, mujica.AgentStepListOptions{}); r.Retry != "" {
+		fmt.Println("retry", r.Retry)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func AgentStepList(c *ui.Context, steps []AgentStep, opts AgentStepListOptions) AgentStepListResult`。步骤 `ID` 为空或重复、`Title` 为空时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Disabled` | `bool` | `false` | 禁止展开与重试。 |
+| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
+
+## 状态
+
+- `AgentStep` 字段：`ID`、`Title`、`Detail`、`State`、`Duration`。
+- `AgentState`：`AgentPending`、`AgentPlanning`、`AgentRunning`、`AgentWaiting`、`AgentDone`、`AgentFailed`、`AgentSkipped`，越界 panic。状态同时由图标形状和文字表达，不只靠颜色。
+- 当前步是第一个执行中、等待或规划中的步骤，用选中底色、边框和“当前”文字标出。
+- 失败步下方显示“重试”。
+
+## 事件
+
+- `Toggled`：本帧展开或折叠的步骤 ID。
+- `Retry`：本帧请求重试的步骤 ID。
+
+## 键盘操作
+
+- Tab 进入列表；↑ ↓ 在步骤与重试按钮间移动；Enter / Space 展开详情或重试。
+
+## 限制
+
+- 步骤数量较少时使用；列表不虚拟化。
@@ -0,0 +1,49 @@
+# 266 AgentPlan 执行计划
+
+## 用途
+
+显示 Agent 的计划清单与进度：随 Agent 实时勾选，用户可勾选、跳过、恢复和新增项。
+
+## 最小示例
+
+```go
+items := []mujica.PlanItem{
+	{ID: "a", Text: "Read the guest list", State: mujica.AgentDone},
+	{ID: "b", Text: "Assign the seats", State: mujica.AgentRunning},
+	{ID: "c", Text: "Order the flowers"},
+}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.AgentPlan(c, &items, mujica.AgentPlanOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func AgentPlan(c *ui.Context, items *[]PlanItem, opts AgentPlanOptions) ChoiceResult`。`items` 为 nil、项 `ID` 重复或状态不是待办、进行中、完成、跳过之一时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Title` | `string` | “计划” | 标题。 |
+| `Disabled` | `bool` | `false` | 只读显示，隐藏跳过与新增。 |
+| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
+
+## 状态
+
+- `PlanItem` 字段：`ID`、`Text`、`State`（`AgentPending`、`AgentRunning`、`AgentDone`、`AgentSkipped`）。
+- 进度为“已完成 / 未跳过总数”，以文字和细进度条显示。
+- 跳过的项加删除线并禁用勾选；进行中的项显示“进行中”。
+- 新增项的 ID 自动生成为未使用的 `item-N`。
+
+## 事件
+
+- `Changed()`：用户勾选、跳过、恢复或新增了项，`*items` 已更新。
+
+## 键盘操作
+
+- Tab 到每项的勾选框（Space 切换）、跳过或恢复按钮；在新增输入框中按 Enter 添加。
+
+## 限制
+
+- 空白内容不会被添加。
@@ -0,0 +1,41 @@
+# 267 AgentStatus Agent 状态
+
+## 用途
+
+显示 Agent 当前状态：规划中、执行中、等待、完成、失败，用图标形状和文字表达，不只靠颜色。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.AgentStatus(c, mujica.AgentWaiting, mujica.AgentStatusOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func AgentStatus(c *ui.Context, state AgentState, opts AgentStatusOptions) *ui.Element`。未知状态 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Label` | `string` | 内置状态词 | 替换显示的文字。 |
+| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
+
+## 状态
+
+- `AgentState`：`AgentPending`、`AgentPlanning`、`AgentRunning`、`AgentWaiting`、`AgentDone`、`AgentFailed`、`AgentSkipped`，越界 panic。状态同时由图标形状和文字表达，不只靠颜色。
+- 执行中显示旋转的菱形；`Still` 或系统减少动画时改为静态图标。
+
+## 事件
+
+- 无事件；屏幕阅读器以状态角色读出文字。
+
+## 键盘操作
+
+- 不获取焦点。
+
+## 限制
+
+- 状态动画只在显示时重绘，隐藏后停止。
@@ -0,0 +1,42 @@
+# 268 AgentProgress Agent 进度
+
+## 用途
+
+显示整体进度和当前动作文字；时长未知时用不确定模式。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.AgentProgress(c, 0.4, mujica.AgentProgressOptions{Action: "Reading ledger.md"})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func AgentProgress(c *ui.Context, value float64, opts AgentProgressOptions) *ui.Element`。确定模式下 `value` 不在 0 到 1 时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Label` | `string` | “进度” | 进度名称。 |
+| `Action` | `string` | `""` | 当前动作，如“正在读取 ledger.md”。 |
+| `Indeterminate` | `bool` | `false` | 不确定模式，忽略 value。 |
+| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
+
+## 状态
+
+- 确定模式显示百分比；不确定模式显示流动条，减少动画时为静态条加“进行中”。
+
+## 事件
+
+- 无事件；当前动作以状态角色读出。
+
+## 键盘操作
+
+- 不获取焦点。
+
+## 限制
+
+- 进度值由调用方计算。
@@ -0,0 +1,45 @@
+# 269 SubAgentTree 子 Agent 树
+
+## 用途
+
+以树显示子 Agent 层级、各自任务与状态，可展开查看下级。
+
+## 最小示例
+
+```go
+agents := []mujica.SubAgent{{ID: "lead", Name: "Steward", State: mujica.AgentRunning, Children: []mujica.SubAgent{
+	{ID: "cook", Name: "Cook", Task: "Plan the menu", State: mujica.AgentWaiting},
+}}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.SubAgentTree(c, agents, mujica.SubAgentTreeOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func SubAgentTree(c *ui.Context, roots []SubAgent, opts SubAgentTreeOptions) ChoiceResult`。`ID` 为空或重复、`Name` 为空时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Disabled` | `bool` | `false` | 禁止展开与折叠。 |
+| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
+
+## 状态
+
+- `SubAgent` 字段：`ID`、`Name`、`Task`、`State`、`Children`。
+- `AgentState`：`AgentPending`、`AgentPlanning`、`AgentRunning`、`AgentWaiting`、`AgentDone`、`AgentFailed`、`AgentSkipped`，越界 panic。状态同时由图标形状和文字表达，不只靠颜色。
+- 有下级的行显示箭头和“N 个子智能体”。
+
+## 事件
+
+- `Changed()`：用户展开或折叠了某个 Agent。
+
+## 键盘操作
+
+- Tab 进入树；↑ ↓ 移动；→ 展开，← 折叠；Enter / Space 切换。
+
+## 限制
+
+- 树不虚拟化，适合几十到几百个 Agent。
@@ -0,0 +1,48 @@
+# 270 FileChangeCard 文件变更卡片
+
+## 用途
+
+预览一个文件的变更：增删行数、首处修改附近的差异行，提供接受、拒绝和打开完整差异的入口。
+
+## 最小示例
+
+```go
+decision := mujica.FilePending
+change := mujica.FileChange{Path: "ledger.md", Old: "Guests: 40\n", New: "Guests: 42\n"}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.FileChangeCard(c, &decision, change, mujica.FileChangeCardOptions{}).OpenDiff {
+		fmt.Println("open the full diff")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func FileChangeCard(c *ui.Context, decision *FileDecision, change FileChange, opts FileChangeCardOptions) FileChangeResult`。`decision` 为 nil、`Path` 为空或 `Preview` 为负时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Preview` | `int` | 8 | 从首处修改前两行起显示的差异行数。 |
+| `Disabled` | `bool` | `false` | 禁止决定与打开差异。 |
+
+## 状态
+
+- `FileChange` 字段：`Path`、`Old`、`New`；`Old` 为空表示新文件，`New` 为空表示删除。
+- 差异由 `internal.LineDiff`（Myers 行差异）计算，文本不变时只算一次。
+- 新增行带“+”、删除行带“−”和行号，颜色只是辅助。
+- 决定状态 `FilePending`、`FileAccepted`、`FileRejected` 以图标和文字显示；已决定后显示“撤销”。
+
+## 事件
+
+- `Decided`：`*decision` 被用户改变。
+- `OpenDiff`：请求调用方打开完整差异。
+
+## 键盘操作
+
+- Tab 依次到“打开差异”“拒绝”“接受”（或“撤销”），Enter / Space 触发。
+
+## 限制
+
+- 只做行级差异；词级高亮由 Git 组扩展。
@@ -0,0 +1,48 @@
+# 271 MultiFileDiffReview 多文件差异审阅
+
+## 用途
+
+审阅多个文件的变更：左侧文件列表，右侧所选文件的完整差异，逐文件接受或拒绝，全部接受，并显示审阅进度。
+
+## 最小示例
+
+```go
+files := []mujica.FileChange{
+	{Path: "ledger.md", Old: "Guests: 40\n", New: "Guests: 42\n"},
+	{Path: "menu.md", Old: "soup\n", New: "soup\ntart\n"},
+}
+decisions := make([]mujica.FileDecision, len(files))
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.MultiFileDiffReview(c, &decisions, files, mujica.MultiFileDiffReviewOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func MultiFileDiffReview(c *ui.Context, decisions *[]FileDecision, files []FileChange, opts MultiFileDiffReviewOptions) ChoiceResult`。`decisions` 与 `files` 数量不同、`Path` 为空或重复、`Height` 为负时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Height` | `float32` | 420 | 组件高度。 |
+| `Disabled` | `bool` | `false` | 禁止选择与决定。 |
+
+## 状态
+
+- 进度为“已审阅 N / 总数”，以文字和细进度条显示。
+- 所选文件用选中底色和左侧竖条标出。
+- 文件超过 200 个或差异超过 200 行时虚拟化。
+- “全部接受”只接受尚未决定的文件，全部决定后禁用。
+
+## 事件
+
+- `Changed()`：用户改变了任一文件的决定。
+
+## 键盘操作
+
+- Tab 进入文件列表；↑ ↓ 移动，Enter 选择；Tab 到右侧按钮后 Enter 接受或拒绝。
+
+## 限制
+
+- 文件很多时方向键只在已构建的可见行间移动，滚动后再继续。
@@ -0,0 +1,48 @@
+# 272 CommandExecutionCard 命令执行卡片
+
+## 用途
+
+显示一条命令的执行：命令、工作目录、带 ANSI 颜色的输出、退出码与耗时，执行中可请求中止。
+
+## 最小示例
+
+```go
+run := mujica.CommandRun{Command: "go test ./...", Dir: "~/court", Running: true, Output: "\x1b[32mok\x1b[0m court\n"}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.CommandExecutionCard(c, run, mujica.CommandExecutionCardOptions{}).Changed() {
+		fmt.Println("abort the process")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func CommandExecutionCard(c *ui.Context, run CommandRun, opts CommandExecutionCardOptions) ChoiceResult`。`Command` 为空或 `Height` 为负时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Height` | `float32` | 240 | 输出区高度。 |
+| `Disabled` | `bool` | `false` | 禁止中止。 |
+| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
+
+## 状态
+
+- `CommandRun` 字段：`Command`、`Dir`、`Output`、`Running`、`ExitCode`、`Duration`。
+- 输出由 `internal.ParseAnsi` 解析，颜色映射到主题；样式可跨行延续；追加输出只解析新增行。
+- 输出虚拟化并跟随末尾，用户向上滚动后停止跟随。
+- 退出码以图标和“退出码 N”文字显示。
+
+## 事件
+
+- `Changed()`：用户点击了“中止”；终止进程由调用方完成。
+
+## 键盘操作
+
+- Tab 到“中止”，Enter / Space 触发；输出区可滚动。
+
+## 限制
+
+- 只支持 SGR 颜色与样式，其它转义序列原样显示。
+- 不运行命令，也不提供 PTY。
@@ -0,0 +1,45 @@
+# 273 ScreenshotStream Agent 画面流
+
+## 用途
+
+查看 Agent 的画面帧序列：默认跟随最新帧，可暂停并逐帧前后查看。帧由调用方提供。
+
+## 最小示例
+
+```go
+var st mujica.ScreenshotStreamState
+var frames []mujica.ScreenshotFrame // appended as the agent captures them
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.ScreenshotStream(c, &st, frames, mujica.ScreenshotStreamOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func ScreenshotStream(c *ui.Context, st *ScreenshotStreamState, frames []ScreenshotFrame, opts ScreenshotStreamOptions) ChoiceResult`。`st` 为 nil、帧没有图像或 `Height` 为负时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Height` | `float32` | 280 | 画面区高度。 |
+| `Disabled` | `bool` | `false` | 禁止暂停与逐帧。 |
+
+## 状态
+
+- `ScreenshotFrame` 字段：`Image`（`ui.ImageSource`）、`Caption`、`At`。
+- `ScreenshotStreamState` 字段：`Index`、`Paused`；未暂停时 `Index` 总是最后一帧。
+- 逐帧操作会自动暂停；“回到实时”恢复跟随。
+- 没有帧时显示“等待画面”。
+
+## 事件
+
+- `Changed()`：用户暂停、恢复或移动了帧。
+
+## 键盘操作
+
+- Tab 到画面区：← → 逐帧，Space 暂停或恢复；上一帧、下一帧按钮同样可用。
+
+## 限制
+
+- 不解码视频，帧图像由调用方提供。
@@ -0,0 +1,47 @@
+# 274 ArtifactPanel 产物面板
+
+## 用途
+
+展示 Agent 生成的产物：代码高亮显示，文档与网页由调用方的预览插槽渲染，可在预览与源码间切换，提供复制与导出。
+
+## 最小示例
+
+```go
+art := mujica.Artifact{Title: "seating.go", Language: "go", Content: "package court\n"}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.ArtifactPanel(c, art, mujica.ArtifactPanelOptions{}).Exported {
+		fmt.Println("save the file")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func ArtifactPanel(c *ui.Context, art Artifact, opts ArtifactPanelOptions) ArtifactPanelResult`。`Title` 为空、`Kind` 越界、文档或网页缺少 `Preview`、`Height` 为负时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Preview` | `func()` | `nil` | 预览插槽；文档与网页必填。 |
+| `Height` | `float32` | 320 | 内容区高度。 |
+| `Disabled` | `bool` | `false` | 禁止复制、导出与切换。 |
+
+## 状态
+
+- `Artifact` 字段：`Title`、`Kind`（`ArtifactCode`、`ArtifactDocument`、`ArtifactWeb`）、`Language`、`Content`。
+- 预览与源码切换用选中底色加勾号标出当前项。
+- 复制后两秒内按钮显示“已复制”。
+
+## 事件
+
+- `Copied`：内容已写入剪贴板。
+- `Exported`：请求调用方导出。
+
+## 键盘操作
+
+- Tab 到切换组，← → 移动，Enter / Space 选择；Tab 到复制、导出。
+
+## 限制
+
+- 不内置网页渲染，网页预览须由调用方提供（无 WebView）。
@@ -0,0 +1,45 @@
+# 275 ArtifactVersionSwitcher 产物版本切换
+
+## 用途
+
+在产物的多个版本之间切换，并提供与上一版本比较差异的入口。
+
+## 最小示例
+
+```go
+current := 1
+versions := []mujica.ArtifactVersion{{Label: "v1", Note: "First draft"}, {Label: "v2", Note: "Added music"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.ArtifactVersionSwitcher(c, &current, versions, mujica.ArtifactVersionSwitcherOptions{}).Compare {
+		fmt.Println("diff v1 and v2")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func ArtifactVersionSwitcher(c *ui.Context, current *int, versions []ArtifactVersion, opts ArtifactVersionSwitcherOptions) ArtifactVersionResult`。没有版本、`*current` 越界或版本 `Label` 为空时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Disabled` | `bool` | `false` | 禁止切换与比较。 |
+
+## 状态
+
+- 显示版本名、“N / 总数”和说明；第一个版本时“较早版本”禁用，最后一个时“较新版本”禁用。
+- 非第一个版本显示“与上一版本比较”。
+
+## 事件
+
+- `Changed`：`*current` 改变。
+- `Compare`：请求比较当前版本与上一版本。
+
+## 键盘操作
+
+- 焦点在组件内时 ← → 切换版本；Tab 到各按钮，Enter / Space 触发。
+
+## 限制
+
+- 差异视图由调用方打开，可用 FileChangeCard 或 MultiFileDiffReview 呈现。
@@ -0,0 +1,43 @@
+# 276 SandboxStatus 沙箱状态
+
+## 用途
+
+显示沙箱的运行状态、资源占用和剩余时间。
+
+## 最小示例
+
+```go
+info := mujica.SandboxInfo{Name: "sandbox-7", State: mujica.SandboxRunning,
+	Resources: []mujica.SandboxResource{{Name: "CPU", Used: 1.5, Limit: 2, Unit: "cores"}}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.SandboxStatus(c, info, mujica.SandboxStatusOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func SandboxStatus(c *ui.Context, info SandboxInfo, opts SandboxStatusOptions) *ui.Element`。状态未知、资源名为空、`Limit` 不大于 0 或 `Used` 不在 0 到 `Limit` 之间时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
+
+## 状态
+
+- `SandboxInfo` 字段：`Name`、`State`（`SandboxStarting`、`SandboxRunning`、`SandboxStopped`、`SandboxFailed`）、`Resources`、`Expires`。
+- 每项资源显示“已用 / 上限 单位”与细条；达到 90% 时加警示图标和“接近上限”说明。
+- 设置 `Expires` 且运行中时显示剩余时间，每秒刷新；到时显示“已到时”。
+
+## 事件
+
+- 无事件。
+
+## 键盘操作
+
+- 不获取焦点。
+
+## 限制
+
+- 倒计时依赖界面帧，窗口隐藏时 MyGo 暂停帧，重新显示后立即校正。
@@ -0,0 +1,46 @@
+# 277 MCPServerList MCP 服务器列表
+
+## 用途
+
+列出 MCP 服务器：连接状态、传输方式、工具数，提供启动、停止与重新连接回调。
+
+## 最小示例
+
+```go
+servers := []mujica.MCPServer{{ID: "fs", Name: "filesystem", Transport: "stdio", State: mujica.MCPConnected, Tools: 12}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if r := mujica.MCPServerList(c, servers, mujica.MCPServerListOptions{}); r.Action == mujica.MCPStop {
+		fmt.Println("stop", r.Server)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func MCPServerList(c *ui.Context, servers []MCPServer, opts MCPServerListOptions) MCPServerListResult`。`ID` 为空或重复、`Name` 为空、状态未知、`Tools` 为负、`MaxHeight` 为负时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `MaxHeight` | `float32` | 360 | 列表最大高度，超出后滚动。 |
+| `Disabled` | `bool` | `false` | 禁止所有操作。 |
+| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
+
+## 状态
+
+- `MCPServer` 字段：`ID`、`Name`、`Transport`、`State`（`MCPStopped`、`MCPConnecting`、`MCPConnected`、`MCPError`）、`Tools`、`Error`。
+- 已连接时显示“N 个工具”；连接失败时显示错误文字与“重新连接”。
+- 超过 200 台服务器时虚拟化。
+
+## 事件
+
+- `Action`：本帧请求 `MCPStart`、`MCPStop` 或 `MCPReconnect`，`Server` 为对应 ID。
+
+## 键盘操作
+
+- Tab 依次到各行按钮，Enter / Space 触发。
+
+## 限制
+
+- 组件只发出请求，连接管理由调用方完成。
@@ -0,0 +1,47 @@
+# 278 MemoryPanel 记忆面板
+
+## 用途
+
+列出 Agent 的记忆条目，支持搜索、行内编辑和确认后删除。
+
+## 最小示例
+
+```go
+entries := []mujica.MemoryEntry{{ID: "1", Text: "Lady Sakiko prefers the east wing.", Source: "Chat"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if r := mujica.MemoryPanel(c, &entries, mujica.MemoryPanelOptions{}); r.Deleted != "" {
+		fmt.Println("forget", r.Deleted)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func MemoryPanel(c *ui.Context, entries *[]MemoryEntry, opts MemoryPanelOptions) MemoryPanelResult`。`entries` 为 nil、条目 `ID` 为空或 `MaxHeight` 为负时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `MaxHeight` | `float32` | 360 | 列表最大高度。 |
+| `Disabled` | `bool` | `false` | 只读，禁止搜索、编辑与删除。 |
+
+## 状态
+
+- `MemoryEntry` 字段：`ID`、`Text`、`Source`。
+- 搜索不区分大小写，匹配内容与来源；只在搜索词或条目变化时重新筛选。
+- 编辑时出现文本框和保存、取消；删除前用 Popconfirm 确认，确认按钮为危险样式且默认聚焦取消。
+- 条目超过 200 条时虚拟化。
+
+## 事件
+
+- `Edited`：本帧保存的条目 ID，`*entries` 已更新。
+- `Deleted`：本帧删除的条目 ID，已从 `*entries` 移除。
+
+## 键盘操作
+
+- Tab 到搜索框、各条的编辑与删除；删除确认中 Escape 取消。
+
+## 限制
+
+- 调用方原地修改条目文本而不改变切片长度时，筛选结果到下次搜索变化才更新。
@@ -0,0 +1,46 @@
+# 279 CheckpointList 检查点列表
+
+## 用途
+
+列出 Agent 运行的检查点，标出当前点，回滚到其它检查点前要求确认。
+
+## 最小示例
+
+```go
+current := "c2"
+points := []mujica.Checkpoint{{ID: "c2", Label: "Menu drafted"}, {ID: "c1", Label: "Start"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.CheckpointList(c, &current, points, mujica.CheckpointListOptions{}).Changed() {
+		fmt.Println("restore", current)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func CheckpointList(c *ui.Context, current *string, points []Checkpoint, opts CheckpointListOptions) ChoiceResult`。`current` 为 nil、`ID` 为空或重复、`Label` 为空、`MaxHeight` 为负时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `MaxHeight` | `float32` | 360 | 列表最大高度。 |
+| `Disabled` | `bool` | `false` | 禁止回滚。 |
+
+## 状态
+
+- 当前点用实心菱形、选中底色和“当前”文字标出；其它点为空心菱形。
+- 回滚用 AlertDialog 确认：默认聚焦取消，Enter 不会直接回滚。
+- 超过 200 个检查点时虚拟化。
+
+## 事件
+
+- `Changed()`：确认回滚后 `*current` 已改为目标 ID。
+
+## 键盘操作
+
+- Tab 到各“回滚”，Enter 打开确认；确认框内 Tab 到“回滚”再按 Enter。
+
+## 限制
+
+- 恢复文件与状态由调用方完成。
@@ -0,0 +1,52 @@
+# 280 HumanInputRequest 人工输入请求
+
+## 用途
+
+Agent 向用户提问：显示问题、可选答案与自由回答，并提示剩余时间与超时。
+
+## 最小示例
+
+```go
+answer := ""
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.HumanInputRequest(c, &answer, mujica.HumanInputRequestOptions{
+		Question: "Which hall?", Options: []string{"East wing", "Great hall"}, AllowFree: true,
+	})
+	if r.Submitted {
+		fmt.Println("reply", answer)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func HumanInputRequest(c *ui.Context, answer *string, opts HumanInputRequestOptions) HumanInputResult`。`answer` 为 nil、`Question` 为空、既无选项又不允许自由回答时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Question` | `string` | 必填 | 问题。 |
+| `Options` | `[]string` | `nil` | 可选答案。 |
+| `AllowFree` | `bool` | `false` | 允许自由回答。 |
+| `Deadline` | `time.Time` | 零值 | 截止时间；零值不限时。 |
+| `Disabled` | `bool` | `false` | 禁止回答。 |
+
+## 状态
+
+- 选择选项会清空自由回答；输入自由回答会取代所选选项。
+- 剩余时间每秒刷新；到时显示“智能体已停止等待”并禁用。
+- 回答为空白时“发送回答”禁用。
+
+## 事件
+
+- `Submitted`：用户发送了 `*answer`。
+- `TimedOut`：截止时间在本帧到达（只报告一次）。
+
+## 键盘操作
+
+- Tab 进入选项组，方向键选择；Tab 到输入框，Enter 发送；或 Tab 到“发送回答”。
+
+## 限制
+
+- 超时只在界面帧中检测，窗口隐藏期间推迟到重新显示。