Merge branch 'worktree-agent-a9950b6fffa6f4a57'

docs/components/321-terminal.md

@@ -0,0 +1,52 @@
+# 321 Terminal · 终端
+
+## 用途
+
+显示终端网格：调用方把 PTY 输出写入 `TerminalState.Write`，组件解析 ANSI 样式（`internal.ParseAnsi`）、光标移动与清屏，保留滚动缓冲，支持鼠标选择复制，并把键盘输入编码后交给调用方写回 PTY。PTY 本身由调用方提供。
+
+## 最小示例
+
+```go
+var term mujica.TerminalState
+term.Write("\x1b[1m~/court\x1b[0m $ ls\r\n\x1b[34mdecrees\x1b[0m  ledger.txt\r\n$ ")
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Terminal(c, &term, mujica.TerminalOptions{
+		Input:   func(data string) { fmt.Printf("to pty: %q\n", data) },
+		Resized: func(cols, rows int) { fmt.Println("pty size", cols, rows) },
+	}).Size(380, 200)
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func Terminal(c *ui.Context, s *TerminalState, opts TerminalOptions) *ui.Element`。`TerminalState` 零值是 80×24 空屏，由调用方持有；`Write(data)` 写入输出（须在界面线程，例如经 `Window.Update`），`Resize(cols, rows)`、`Lines()`、`LineText(i)`、`Select(a, b)`、`Selection()`、`ScrollBack(n)`、`Offset()`、`Cursor()`、`Size()` 供程序读取与控制。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Input` | `func(data string)` | nil | 用户输入编码后的字节：文字原样，Enter 为 `\r`，退格 `\x7f`，方向键 `ESC [ A–D`，Ctrl+字母为控制码。 |
+| `Resized` | `func(cols, rows int)` | nil | 网格尺寸随元素大小变化时回调，用于同步 PTY 窗口大小。 |
+| `Scrollback` | `int` | 1000 | 滚动缓冲最多保留的行数；负数 panic。 |
+| `Label` | `string` | 内置“终端” | 无障碍名称。 |
+| `Disabled` | `bool` | false | 不接收任何输入。 |
+
+## 状态
+
+默认（Surface 底、细边框）、聚焦（外侧 2 DIP 焦点环，光标为 AccentText 实心块并反白字符）、未聚焦（光标只描边）、选择（Selection 背景）、回看滚动缓冲（隐藏光标）、输入法组合（光标处显示带下划线的组合文字）、禁用。
+
+## 事件
+
+`Input`：每次按键、输入文字或粘贴；`Resized`：网格尺寸变化。复制写入系统剪贴板。
+
+## 键盘操作
+
+- 焦点在终端时，文字、Enter、Backspace、Tab、Shift+Tab、Escape、方向键、Home/End、Delete、PageUp/PageDown 与 Ctrl+字母都发送给 PTY。
+- 复制：macOS 上 Cmd+C，其他平台 Ctrl+Shift+C（复制选中文字）；粘贴：Cmd+V / Ctrl+Shift+V。
+- Shift+PageUp / Shift+PageDown：翻看滚动缓冲；滚轮同样可用；任意输入回到底部。
+
+## 限制
+
+- 状态机覆盖常用序列：SGR 样式、CUU/CUD/CUF/CUB、CHA、CUP、ED（0/1/2/3）、EL、CR/LF/BS/TAB 与 OSC（忽略）。其余 CSI 序列只记录 Debug 日志后忽略；不支持备用屏幕、滚动区域、鼠标上报与宽字符占两格。
+- 需要完整终端仿真时请使用 MyGo 的 `plugins/terminal`（基于 libghostty-vt）。
+- 字形用 `ui.Shape` 逐格排布并按行缓存，等宽字体由系统回退决定。

docs/components/322-terminal-tabs.md

@@ -0,0 +1,52 @@
+# 322 TerminalTabs · 终端标签
+
+## 用途
+
+管理多个终端的标签：切换、重命名、关闭；仍有进程运行（`Busy`）的终端关闭前弹出确认。
+
+## 最小示例
+
+```go
+tabs := []mujica.TerminalTab{{ID: "a", Title: "zsh"}, {ID: "b", Title: "build", Busy: true}}
+active := "a"
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.TerminalTabs(c, &tabs, &active, mujica.TerminalTabsOptions{}, func(id string) {
+		ui.Text(c, "terminal "+id)
+	})
+	if r.Closed != "" {
+		fmt.Println("close pty", r.Closed)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func TerminalTabs(c *ui.Context, tabs *[]TerminalTab, active *string, opts TerminalTabsOptions, content func(id string)) TerminalTabsResult`。`*tabs` 与 `*active` 由调用方持有，组件直接修改：重命名改 `Title`，关闭删除元素并把 `active` 移到相邻标签。`active` 不是任何标签 ID 时 panic。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `TerminalTab.ID` | `string` | 必填 | 稳定标识，也是事件值。 |
+| `TerminalTab.Title` | `string` | 必填 | 标签文字。 |
+| `TerminalTab.Busy` | `bool` | false | 进程仍在运行：显示小圆点并在关闭前确认。 |
+| `Disabled` | `bool` | false | 不响应切换、重命名与关闭。 |
+| `content` | `func(id string)` | 必填 | 构建当前标签的内容。 |
+
+## 状态
+
+当前标签（Selection 背景、粗体与底部 AccentText 线）、悬停、键盘焦点环、正在运行（圆点与无障碍描述“进程运行中”）、重命名输入框、关闭确认对话框、无标签时的空状态、禁用。
+
+## 事件
+
+`Changed`：当前标签变化；`Renamed`：被重命名的标签 ID；`Closed`：被关闭的标签 ID（调用方应关闭对应 PTY）。
+
+## 键盘操作
+
+- ←/→、Home/End：在标签间移动并切换。
+- F2 或双击：重命名；Enter 确认，Escape 取消。
+- Delete：关闭焦点所在标签；运行中的标签先确认，确认框默认聚焦“取消”。
+
+## 限制
+
+- 不提供新建按钮与拖动排序；新建由调用方向 `*tabs` 追加。

docs/components/323-terminal-search.md

@@ -0,0 +1,48 @@
+# 323 TerminalSearch · 终端搜索
+
+## 用途
+
+在终端的滚动缓冲与屏幕中查找文字，显示匹配数，上下跳转并把当前匹配滚动到可见处。
+
+## 最小示例
+
+```go
+var term mujica.TerminalState
+term.Write("build ok\r\nerror: missing seal\r\n")
+var search mujica.TerminalSearchState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	ui.Column(c).Gap(8).Children(func() {
+		mujica.TerminalSearch(c, &term, &search, mujica.TerminalSearchOptions{})
+		mujica.Terminal(c, &term, mujica.TerminalOptions{}).Height(160)
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func TerminalSearch(c *ui.Context, term *TerminalState, s *TerminalSearchState, opts TerminalSearchOptions) ChoiceResult`。匹配在查询或终端内容变化时重算一次，不逐帧计算；匹配结果写入 `term`，由同一 `TerminalState` 的 `Terminal` 绘制下划线，当前匹配加框。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `TerminalSearchState.Query` | `string` | "" | 查找文字，不区分大小写。 |
+| `TerminalSearchState.Current` | `int` | 0 | 当前匹配序号，从 0 开始。 |
+| `Disabled` | `bool` | false | 不能输入与跳转。 |
+
+## 状态
+
+无查询、有匹配（“第 n 项，共 m 项”）、无匹配（“无匹配”）、禁用；终端中其余匹配为 AccentText 下划线，当前匹配加 AccentText 框。
+
+## 事件
+
+`Changed()`：查询变化或跳到另一匹配。
+
+## 键盘操作
+
+- Enter / Shift+Enter：下一项 / 上一项；macOS 上 Cmd+G / Shift+Cmd+G，其他平台 F3 / Shift+F3。
+- 上一项、下一项按钮可用 Tab 到达。
+
+## 限制
+
+- 只做纯文字匹配，不支持正则与整词；跨行文字不会匹配。

docs/components/324-command-history.md

@@ -0,0 +1,50 @@
+# 324 CommandHistory · 命令历史
+
+## 用途
+
+按时间倒序列出执行过的命令，可搜索，并通过回调重新运行。
+
+## 最小示例
+
+```go
+history := []mujica.HistoryEntry{{Command: "git status"}, {Command: "go test ./...", ExitCode: 1}}
+var state mujica.CommandHistoryState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.CommandHistory(c, history, &state, mujica.CommandHistoryOptions{})
+	r.Element.Height(240)
+	if r.Replayed != nil {
+		fmt.Println("run", r.Replayed.Command)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func CommandHistory(c *ui.Context, entries []HistoryEntry, s *CommandHistoryState, opts CommandHistoryOptions) CommandHistoryResult`。列表虚拟化，筛选只在条目数或查询变化时重算。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `HistoryEntry.Command` | `string` | 必填 | 命令文字。 |
+| `HistoryEntry.Time` | `time.Time` | 零值不显示 | 执行时间。 |
+| `HistoryEntry.ExitCode` | `int` | 0 | 非零时显示“退出码 n”。 |
+| `CommandHistoryState.Query` | `string` | "" | 搜索文字，不区分大小写。 |
+| `Disabled` | `bool` | false | 不能搜索与重放。 |
+
+## 状态
+
+默认、选中（Selection 背景与菱形标记）、失败命令（Danger 退出码）、无历史、无匹配、禁用。
+
+## 事件
+
+`Replayed`：要重新运行的条目，没有则为 nil。
+
+## 键盘操作
+
+- Tab 依次到达搜索框与列表；↑/↓、Home/End 选择；输入字母按命令定位。
+- Enter 或双击：重放当前条目；每行的重放按钮可用 Tab 到达。
+
+## 限制
+
+- 只追加或整体替换 `entries` 会被识别；原地修改中间条目后请传入新切片。

docs/components/325-log-viewer.md

@@ -0,0 +1,48 @@
+# 325 LogViewer · 日志查看器
+
+## 用途
+
+显示日志：按级别过滤、跟随尾部、关键字高亮，十万行也只构建可见行。
+
+## 最小示例
+
+```go
+lines := []mujica.LogLine{{Level: mujica.LogInfo, Text: "court opened"}, {Level: mujica.LogError, Text: "seal missing"}}
+var state mujica.LogViewerState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.LogViewer(c, lines, &state, mujica.LogViewerOptions{}).Element.Height(240)
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func LogViewer(c *ui.Context, lines []LogLine, s *LogViewerState, opts LogViewerOptions) ChoiceResult`。新追加的行增量过滤；级别变化时重新过滤一次，不逐帧计算。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `LogLine.Level` | `LogLevel` | `LogDebug` | `LogDebug`、`LogInfo`、`LogWarn`、`LogError`；越界 panic。 |
+| `LogLine.Time`, `Text` | `time.Time`, `string` | — | 时间（零值不显示）与内容。 |
+| `LogViewerState.Hidden` | `[4]bool` | 全显示 | 被隐藏的级别。 |
+| `LogViewerState.Query` | `string` | "" | 高亮关键字，不区分大小写。 |
+| `LogViewerState.Follow` | `bool` | 首次为 true | 跟随尾部；向上滚动后 MyGo 暂停跟随，滚回底部恢复。 |
+| `Disabled` | `bool` | false | 不能改过滤与跟随。 |
+
+## 状态
+
+级别按钮按下表示显示；级别同时用文字（DEBUG/INFO/WARN/ERROR）与颜色区分；高亮为 Selection 背景、粗体与下划线；无日志空状态；禁用。
+
+## 事件
+
+`Changed()`：级别过滤或跟随开关变化。
+
+## 键盘操作
+
+- Tab 依次到达级别按钮、高亮输入框、跟随按钮与日志列表；Space 切换按钮。
+- 列表中方向键、PageUp/PageDown、Home/End 滚动。
+
+## 限制
+
+- 只识别向末尾追加；替换为更短的切片会重新过滤。
+- 高亮不过滤行，只标出匹配。

docs/components/326-process-list.md

@@ -0,0 +1,50 @@
+# 326 ProcessList · 进程列表
+
+## 用途
+
+以表格列出进程，可按名称、PID、CPU、内存排序；结束进程前必须确认，确认后通过结果交给调用方执行。
+
+## 最小示例
+
+```go
+procs := []mujica.Process{{PID: 7, Name: "archivist", CPU: 42, Memory: 50 << 20}, {PID: 9, Name: "herald", CPU: 3, Memory: 8 << 20}}
+var state mujica.ProcessListState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.ProcessList(c, procs, &state, mujica.ProcessListOptions{})
+	r.Element.Height(240)
+	if r.End != nil {
+		fmt.Println("kill", r.End.PID)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ProcessList(c *ui.Context, procs []Process, s *ProcessListState, opts ProcessListOptions) ProcessListResult`。排序只在切片或排序方式变化时进行；刷新数据请传入新切片。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Process.PID`, `Name` | `int`, `string` | — | 进程号与名称；PID 是行的稳定键。 |
+| `Process.CPU` | `float64` | 0 | 占用百分比。 |
+| `Process.Memory` | `uint64` | 0 | 常驻内存字节数，显示为 KB/MB/GB。 |
+| `ProcessListState.Sort` | `ui.SortOrder` | CPU 降序 | 列为 `name`、`pid`、`cpu`、`memory`，其他值 panic。 |
+| `Disabled` | `bool` | false | 不能排序与结束进程。 |
+
+## 状态
+
+选中行（Selection 背景与菱形）、排序列箭头、确认对话框（默认聚焦“取消”）、无进程、禁用。
+
+## 事件
+
+`End`：用户确认要结束的进程，没有则为 nil。
+
+## 键盘操作
+
+- Tab 到达表格；↑/↓、Home/End 选择；Delete 结束所选进程（先确认）。
+- 点击列头排序，再点反向；每行结束按钮可用 Tab 到达。
+
+## 限制
+
+- 组件不发送信号，只回报确认结果。

docs/components/327-code-viewer.md

@@ -0,0 +1,46 @@
+# 327 CodeViewer · 代码查看器
+
+## 用途
+
+只读代码视图：行号、基础语法着色（`internal.Highlight`）、按缩进折叠、当前行、选择复制；大文件只构建可见行。
+
+## 最小示例
+
+```go
+lines := []string{"func Seal(d string) int {", "\treturn len(d)", "}"}
+var state mujica.CodeViewerState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.CodeViewer(c, lines, &state, mujica.CodeViewerOptions{Language: "go"}).Element.Height(240)
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func CodeViewer(c *ui.Context, lines []string, s *CodeViewerState, opts CodeViewerOptions) ChoiceResult`。块注释状态与折叠范围在代码变化时扫描一次。`s.Line()` 返回当前行，`s.GoTo(line)` 跳转并展开遮住它的折叠，`s.Visible()` 返回可见行范围，`s.ScrollTo(line)` 只滚动；`s.Selection` 保存选中行，`s.Folded` 保存折叠起始行。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Language` | `string` | ""（纯文本） | `go`、`javascript`、`typescript`、`python`、`json`、`shell`、`sql`。 |
+| `Label` | `string` | "" | 无障碍名称。 |
+| `Disabled` | `bool` | false | 不能折叠。 |
+
+## 状态
+
+当前行（Selection 背景与菱形）、选中行（Selection 背景）、可折叠行（向下箭头）、已折叠（向右箭头）、空代码、禁用。关键字 AccentText、字符串 Success、数字 Warning、类型 Info、注释 TextMuted 斜体。
+
+## 事件
+
+`Changed()`：当前行或选择变化。
+
+## 键盘操作
+
+- ↑/↓、Home/End：移动当前行；Shift+方向键扩展选择；Cmd/Ctrl+A 全选。
+- Cmd+C（macOS）/ Ctrl+C：复制选中行，未选则复制当前行。
+- ←：折叠当前行开始的块；→：展开。折叠按钮可用 Tab 到达。
+
+## 限制
+
+- 折叠按缩进推断，不解析语法；空行不结束块。
+- 只读，不提供编辑与行内（字符级）选择。

docs/components/328-minimap.md

@@ -0,0 +1,45 @@
+# 328 Minimap · 代码缩略图
+
+## 用途
+
+以细条绘制代码缩略图，框出编辑器可见区域；点击或拖动跳转，键盘可移动。
+
+## 最小示例
+
+```go
+lines := []string{"package court", "", "func Seal() {}", "func Herald() {}"}
+view := mujica.MinimapView{Top: 0, Visible: 2}
+draw := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.Minimap(c, lines, &view, mujica.MinimapOptions{Language: "go"}).Changed() {
+		fmt.Println("scroll editor to", view.Top)
+	}
+}
+ui.Render(draw, 400, 300, 1)
+```
+
+## 参数
+
+`func Minimap(c *ui.Context, lines []string, view *MinimapView, opts MinimapOptions) ChoiceResult`。`MinimapView{Top, Visible}` 是编辑器当前首行与可见行数，由调用方与编辑器同步（可用 `CodeViewerState.Visible` 与 `ScrollTo`）。每行 2 DIP、每字符 1 DIP；文件比缩略图高时缩略图随视图滚动，只绘制可见的行。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Language` | `string` | "" | 着色语言，同 CodeViewer。 |
+| `Width` | `float32` | 96 | 宽度（DIP）；负数 panic。 |
+| `Disabled` | `bool` | false | 不能跳转。 |
+
+## 状态
+
+可见区为 Selection 半透明填充加 AccentText 边框；聚焦时外侧焦点环；禁用。
+
+## 事件
+
+`Changed()`：用户移动了视图，读取 `view.Top`。
+
+## 键盘操作
+
+- Tab 聚焦；↑/↓ 移动一行，PageUp/PageDown 移动一屏，Home/End 到开头与结尾。
+
+## 限制
+
+- 缩略图按行独立着色，不跟踪跨行的块注释。

docs/components/329-find-widget.md

@@ -0,0 +1,51 @@
+# 329 FindWidget · 查找替换
+
+## 用途
+
+在文本中查找与替换：区分大小写、整词、正则表达式，显示匹配数并上下跳转。
+
+## 最小示例
+
+```go
+text := "the seal and the seal"
+state := mujica.FindState{Query: "seal", Replacement: "signet", ShowReplace: true}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.FindWidget(c, &text, &state, mujica.FindWidgetOptions{}).Replaced > 0 {
+		fmt.Println(text)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func FindWidget(c *ui.Context, text *string, s *FindState, opts FindWidgetOptions) FindWidgetResult`。匹配在文本、查询或选项变化时重算；`s.Matches()` 返回各匹配的字节范围。替换直接修改 `*text`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `FindState.Query`, `Replacement` | `string` | "" | 查找与替换文字；正则模式下替换支持 `$1` 分组。 |
+| `MatchCase`, `WholeWord`, `Regex` | `bool` | false | 区分大小写、整词、正则。 |
+| `ShowReplace` | `bool` | false | 展开替换行。 |
+| `Current` | `int` | 0 | 当前匹配。 |
+| `ReadOnly` | `bool` | false | 隐藏替换。 |
+| `Disabled` | `bool` | false | 不能输入与替换。 |
+
+## 状态
+
+选项按钮按下状态、匹配计数、无匹配、正则错误（Danger 文字说明具体错误）、替换按钮在无匹配时禁用、禁用。
+
+## 事件
+
+`Moved`：查询、选项或当前匹配变化；`Replaced`：本帧替换的数量。
+
+## 键盘操作
+
+- Enter / Shift+Enter：下一项 / 上一项；macOS Cmd+G，其他平台 F3。
+- 替换输入框中 Enter：替换当前项。
+- Tab 依次到达展开按钮、查找框、上下按钮、三个选项与替换控件。
+
+## 限制
+
+- 使用 Go 的 RE2 正则语法，不支持回溯引用。
+- 不在编辑器中绘制高亮，调用方用 `Matches()` 自行标记。

docs/components/330-search-panel.md

@@ -0,0 +1,51 @@
+# 330 SearchPanel · 多文件搜索
+
+## 用途
+
+展示多文件搜索结果：按文件分组、可折叠，匹配预览带高亮；提供包含与排除模式输入。
+
+## 最小示例
+
+```go
+results := []mujica.SearchFileResult{{Path: "court/seal.go", Matches: []mujica.SearchMatch{{Line: 12, Text: "func Seal() {", Start: 5, End: 9}}}}
+state := mujica.SearchPanelState{Query: "seal"}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.SearchPanel(c, results, &state, mujica.SearchPanelOptions{})
+	r.Element.Height(280)
+	if r.Opened != nil {
+		fmt.Println("open", r.Opened.Path, r.Opened.Line)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func SearchPanel(c *ui.Context, results []SearchFileResult, s *SearchPanelState, opts SearchPanelOptions) SearchPanelResult`。搜索由调用方执行：查询或模式变化时 `Changed` 为 true，完成后传入新的 `results`。行列表虚拟化。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `SearchFileResult.Path` | `string` | 必填 | 文件路径，也是折叠键。 |
+| `SearchMatch.Line`, `Text` | `int`, `string` | — | 行号与行文字。 |
+| `SearchMatch.Start`, `End` | `int` | — | 匹配在 `Text` 中的字节范围；越界 panic。 |
+| `SearchPanelState.Query`, `Include`, `Exclude` | `string` | "" | 查询与包含、排除模式（格式由调用方解释）。 |
+| `Status`, `Error` | `DataStatus`, `string` | `DataReady` | 搜索中或失败。 |
+| `Disabled` | `bool` | false | 不能输入、折叠与打开。 |
+
+## 状态
+
+结果摘要、文件标题（折叠箭头与匹配数）、匹配行（Selection 背景与粗体下划线标出匹配）、选中行（Selection 与菱形）、搜索中、失败（可重试）、未输入、无结果、禁用。
+
+## 事件
+
+`Changed`：查询或模式变化，或点击重试；`Opened`：用户打开的匹配（路径与行号）。
+
+## 键盘操作
+
+- Tab 依次到达查询、包含、排除与结果列表。
+- ↑/↓ 选择；Enter 或双击：打开匹配，或折叠/展开文件；文件行上 ← 折叠、→ 展开。
+
+## 限制
+
+- 长行只显示匹配前 40 个字节。

docs/components/331-problems-panel.md

@@ -0,0 +1,49 @@
+# 331 ProblemsPanel · 问题面板
+
+## 用途
+
+列出错误、警告与信息，按文件分组并按行列排序，可按级别过滤，打开问题时回调跳转。
+
+## 最小示例
+
+```go
+problems := []mujica.Problem{{Severity: mujica.ProblemError, File: "court/seal.go", Line: 12, Col: 5, Message: "undefined: Decree"}}
+var state mujica.ProblemsPanelState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.ProblemsPanel(c, problems, &state, mujica.ProblemsPanelOptions{})
+	r.Element.Height(240)
+	if r.Opened != nil {
+		fmt.Println("go to", r.Opened.File, r.Opened.Line)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ProblemsPanel(c *ui.Context, problems []Problem, s *ProblemsPanelState, opts ProblemsPanelOptions) ProblemsPanelResult`。分组排序只在数据、过滤或折叠变化时进行。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Problem.Severity` | `ProblemSeverity` | `ProblemError` | `ProblemError`、`ProblemWarning`、`ProblemInfo`；越界 panic。 |
+| `Problem.File`, `Line`, `Col` | `string`, `int` | — | 位置。 |
+| `Problem.Message`, `Source` | `string` | — | 说明与来源（如编译器名）。 |
+| `ProblemsPanelState.Hidden` | `[3]bool` | 全显示 | 被隐藏的级别。 |
+| `Disabled` | `bool` | false | 不能过滤、折叠与打开。 |
+
+## 状态
+
+级别按钮带图标与计数；问题行用不同形状的图标（圆叉、三角、圆 i）与颜色共同标识级别，并有无障碍名称；选中行 Selection 与菱形；无问题；禁用。
+
+## 事件
+
+`Opened`：用户打开的问题。
+
+## 键盘操作
+
+- Tab 到达级别按钮与列表；↑/↓ 选择；Enter 或双击打开问题，在文件行上折叠/展开；← 折叠、→ 展开。
+
+## 限制
+
+- 同一文件的问题按行、列排序，文件按路径排序。

docs/components/332-output-panel.md

@@ -0,0 +1,48 @@
+# 332 OutputPanel · 输出面板
+
+## 用途
+
+显示多个输出通道之一，跟随尾部，支持 ANSI 颜色；清空请求通过结果交给调用方。
+
+## 最小示例
+
+```go
+channels := []mujica.OutputChannel{{Name: "Build", Lines: []string{"compiling court", "\x1b[32mok\x1b[0m"}}}
+var state mujica.OutputPanelState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.OutputPanel(c, channels, &state, mujica.OutputPanelOptions{})
+	r.Element.Height(240)
+	if r.Cleared != "" {
+		channels[state.Channel].Lines = nil
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func OutputPanel(c *ui.Context, channels []OutputChannel, s *OutputPanelState, opts OutputPanelOptions) OutputPanelResult`。通道为空或 `Channel` 越界时 panic。行列表虚拟化。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `OutputChannel.Name`, `Lines` | `string`, `[]string` | — | 通道名与内容，行内可含 ANSI 样式。 |
+| `OutputPanelState.Channel` | `int` | 0 | 当前通道。 |
+| `OutputPanelState.Follow` | `bool` | 首次为 true | 跟随尾部。 |
+| `Disabled` | `bool` | false | 不能切换、清空与改跟随。 |
+
+## 状态
+
+通道下拉、跟随按钮按下、清空按钮、无输出、禁用。
+
+## 事件
+
+`Changed`：切换了通道；`Cleared`：要清空的通道名，调用方清空其 `Lines`。
+
+## 键盘操作
+
+- Tab 到达通道下拉、跟随按钮、清空按钮与输出列表；下拉中方向键选择。
+
+## 限制
+
+- 只渲染 SGR 样式，其余控制序列原样保留（与 `internal.ParseAnsi` 一致）。

docs/components/333-symbol-outline.md

@@ -0,0 +1,53 @@
+# 333 SymbolOutline · 符号大纲
+
+## 用途
+
+以树显示文件中的符号，带类型标记，可筛选，并跟随编辑器光标选中所在符号。
+
+## 最小示例
+
+```go
+symbols := []mujica.Symbol{{Name: "Court", Kind: mujica.SymbolType, Line: 3, EndLine: 40, Children: []mujica.Symbol{
+	{Name: "Seal", Kind: mujica.SymbolMethod, Line: 10, EndLine: 20},
+}}}
+var state mujica.SymbolOutlineState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.SymbolOutline(c, symbols, &state, mujica.SymbolOutlineOptions{CursorLine: 12})
+	r.Element.Height(240)
+	if r.Jumped != nil {
+		fmt.Println("go to line", r.Jumped.Line)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func SymbolOutline(c *ui.Context, symbols []Symbol, s *SymbolOutlineState, opts SymbolOutlineOptions) SymbolOutlineResult`。符号树在数据变化时编号一次。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Symbol.Name`, `Detail` | `string` | — | 名称与补充说明（如签名）。 |
+| `Symbol.Kind` | `SymbolKind` | `SymbolFunction` | 函数 f、方法 m、类型 T、接口 I、字段 p、变量 v、常量 c、模块 M；越界 panic。 |
+| `Symbol.Line`, `EndLine` | `int` | — | 所在行范围，从 1 开始。 |
+| `SymbolOutlineState.Query` | `string` | "" | 筛选文字；匹配项与其祖先保留并自动展开。 |
+| `CursorLine` | `int` | 0（不跟随） | 变化时选中包含该行的最内层符号并展开祖先。 |
+| `Disabled` | `bool` | false | 不能跳转。 |
+
+## 状态
+
+类型以字母徽记加颜色区分；选中行 Selection 与菱形；筛选高亮；无符号；禁用。
+
+## 事件
+
+`Jumped`：用户要跳转的符号。
+
+## 键盘操作
+
+- Tab 到达筛选框与树；↑/↓ 移动，→ 展开或进入子项，← 折叠或回到父项；输入字母按名称定位。
+- Enter 或双击：跳转到符号。
+
+## 限制
+
+- 光标跟随只在 `CursorLine` 变化时生效，之后用户可自由移动选择。

docs/components/334-completion-menu.md

@@ -0,0 +1,50 @@
+# 334 CompletionMenu · 补全菜单
+
+## 用途
+
+在编辑器下方显示补全候选：类型徽记、详情与说明；方向键选择，Tab 或 Enter 接受，焦点始终留在编辑器。
+
+## 最小示例
+
+```go
+text := "se"
+open := true
+items := []mujica.Completion{{Label: "Seal", Kind: mujica.SymbolMethod, Detail: "func()"}, {Label: "Search", Kind: mujica.SymbolFunction}}
+var state mujica.CompletionMenuState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	in := mujica.TextInput(c, &text, mujica.TextInputOptions{Label: "Code"})
+	if r := mujica.CompletionMenu(c, in.Input, &open, items, &state, mujica.CompletionMenuOptions{}); r.Accepted != nil {
+		text = r.Accepted.Label
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func CompletionMenu(c *ui.Context, anchor *ui.Element, open *bool, items []Completion, s *CompletionMenuState, opts CompletionMenuOptions) CompletionMenuResult`。`anchor` 是编辑器元素（如 `InputResult.Input`）；打开期间组件替换它的 `HandleInput` 以先拿到菜单按键。候选为空、禁用或编辑器禁用时自动关闭。列表虚拟化，最多显示 8 行后滚动；窗口下方空间不足时在上方弹出。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Completion.Label` | `string` | 必填 | 候选文字。 |
+| `Completion.Kind` | `SymbolKind` | `SymbolFunction` | 类型徽记；越界 panic。 |
+| `Completion.Detail`, `Doc` | `string` | "" | 右侧详情与当前候选的说明。 |
+| `CompletionMenuState.Selected` | `int` | 0 | 当前候选。 |
+| `Disabled` | `bool` | false | 关闭菜单。 |
+
+## 状态
+
+当前候选 Selection 背景与菱形；弹层 160 ms 淡入（减少动画时直接显示）。
+
+## 事件
+
+`Accepted`：被接受的候选，同时 `*open` 置为 false。
+
+## 键盘操作
+
+- ↓/↑：循环移动；Tab 或 Enter：接受；Escape：关闭。点击候选也接受。
+
+## 限制
+
+- 打开期间编辑器自身设置的 `HandleInput` 会被覆盖。

docs/components/335-debug-toolbar.md

@@ -0,0 +1,48 @@
+# 335 DebugToolbar · 调试工具栏
+
+## 用途
+
+调试会话的继续/暂停、单步跳过、单步进入、单步跳出、重启与停止，按会话状态禁用不适用的按钮，并注册常用快捷键。
+
+## 最小示例
+
+```go
+state := mujica.DebugPaused
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	switch mujica.DebugToolbar(c, state, mujica.DebugToolbarOptions{}).Action {
+	case mujica.DebugContinue:
+		state = mujica.DebugRunning
+	case mujica.DebugStop:
+		state = mujica.DebugStopped
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func DebugToolbar(c *ui.Context, state DebugState, opts DebugToolbarOptions) DebugToolbarResult`。`DebugEnabled(state, action)` 给出禁用规则：运行中只能暂停、重启、停止；暂停时可继续、单步、重启、停止；停止时只能“开始”（`DebugContinue`）。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `state` | `DebugState` | — | `DebugStopped`、`DebugRunning`、`DebugPaused`；越界 panic。 |
+| `Disabled` | `bool` | false | 全部按钮与快捷键无效。 |
+
+## 状态
+
+运行中第一个按钮显示暂停，否则显示继续（停止时名为“开始”）；不适用的按钮禁用；按钮悬停、按下、焦点环与带快捷键的提示。
+
+## 事件
+
+`Action`：本帧请求的 `DebugAction`，无则为 `DebugNone`。
+
+## 键盘操作
+
+- F5 继续/开始，F6 暂停，F10 单步跳过，F11 单步进入，Shift+F11 单步跳出，Cmd/Ctrl+Shift+F5 重启，Shift+F5 停止（窗口内全局，焦点控件优先处理）。
+- 工具栏是一个 Tab 停靠点，←/→ 在按钮间移动。
+
+## 限制
+
+- 快捷键固定，不可配置；同一窗口只放一个调试工具栏。
+- 图标为自绘 SVG。

docs/components/336-breakpoint-list.md

@@ -0,0 +1,49 @@
+# 336 BreakpointList · 断点列表
+
+## 用途
+
+列出断点：启用开关、跳到源码位置、行内编辑条件断点。
+
+## 最小示例
+
+```go
+bps := []mujica.Breakpoint{{ID: "a", File: "court/seal.go", Line: 12, Enabled: true}, {ID: "b", File: "main.go", Line: 9, Condition: "n > 3"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.BreakpointList(c, &bps, mujica.BreakpointListOptions{})
+	r.Element.Height(200)
+	if r.Toggled != "" || r.Edited != "" {
+		fmt.Println("sync breakpoints with the debugger")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func BreakpointList(c *ui.Context, bps *[]Breakpoint, opts BreakpointListOptions) BreakpointListResult`。组件直接修改 `*bps` 中的 `Enabled` 与 `Condition`；ID 为空或重复时 panic。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Breakpoint.ID` | `string` | 必填 | 稳定标识。 |
+| `Breakpoint.File`, `Line` | `string`, `int` | — | 位置。 |
+| `Breakpoint.Enabled` | `bool` | false | 是否启用。 |
+| `Breakpoint.Condition` | `string` | "" | 条件表达式，非空时显示“当 …”。 |
+| `Disabled` | `bool` | false | 不能修改与跳转。 |
+
+## 状态
+
+启用为实心圆点，停用为空心圆点并降低文字色；条件以 Warning 等宽文字显示；编辑中的输入框；无断点；禁用。
+
+## 事件
+
+`Toggled`、`Edited`、`Opened`：本帧被切换、改条件、要打开的断点 ID。
+
+## 键盘操作
+
+- Tab 依次到达复选框、位置按钮与编辑条件按钮；Space 切换启用；Enter 打开位置。
+- 条件输入框：Enter 确认，Escape 取消。
+
+## 限制
+
+- 不提供删除与新增；由调用方修改 `*bps`。

docs/components/337-call-stack.md

@@ -0,0 +1,52 @@
+# 337 CallStack · 调用栈
+
+## 用途
+
+按线程分组显示调用栈帧，标出当前帧；选择帧即切换当前帧。
+
+## 最小示例
+
+```go
+threads := []mujica.DebugThread{{ID: "t1", Name: "main", Frames: []mujica.StackFrame{
+	{ID: "f1", Name: "court.Seal", File: "court/seal.go", Line: 14},
+	{ID: "f2", Name: "main.main", File: "main.go", Line: 9},
+}}}
+state := mujica.CallStackState{Current: "f1"}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.CallStack(c, threads, &state, mujica.CallStackOptions{})
+	r.Element.Height(200)
+	if r.Changed() {
+		fmt.Println("show frame", state.Current)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func CallStack(c *ui.Context, threads []DebugThread, s *CallStackState, opts CallStackOptions) ChoiceResult`。调用方修改 `s.Current` 时选中行随之移动。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `DebugThread.ID`, `Name` | `string` | — | 线程标识与名称。 |
+| `StackFrame.ID`, `Name`, `File`, `Line` | `string`, `int` | — | 帧标识、函数名与位置，最内层在前。 |
+| `CallStackState.Current` | `string` | "" | 当前帧 ID。 |
+| `CallStackState.Collapsed` | `ui.Selection[string]` | 空 | 折叠的线程 ID。 |
+| `Disabled` | `bool` | false | 不能切换与折叠。 |
+
+## 状态
+
+线程标题（折叠箭头与栈深度）、当前帧（Selection 背景与菱形）、未暂停空状态、禁用。
+
+## 事件
+
+`Changed()`：用户选了另一帧，读取 `s.Current`。
+
+## 键盘操作
+
+- Tab 到达列表；↑/↓ 移动，到达帧即切换当前帧；线程行上 Enter 折叠/展开，← 折叠、→ 展开。
+
+## 限制
+
+- 不区分线程的运行状态；需要时写入线程名。

docs/components/338-variables-panel.md

@@ -0,0 +1,49 @@
+# 338 VariablesPanel · 变量面板
+
+## 用途
+
+以树显示调试变量，可展开结构，标出自上次停止以来变化的值，并在行内修改叶子变量的值。
+
+## 最小示例
+
+```go
+vars := []mujica.Variable{{Name: "decree", Value: "{…}", Children: []mujica.Variable{{Name: "id", Value: "42", Changed: true}}}, {Name: "count", Value: "7"}}
+var state mujica.VariablesPanelState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.VariablesPanel(c, vars, &state, mujica.VariablesPanelOptions{})
+	r.Element.Height(200)
+	if r.Edited != nil {
+		fmt.Println("set", r.Edited.Path, "=", r.Edited.Value)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func VariablesPanel(c *ui.Context, vars []Variable, s *VariablesPanelState, opts VariablesPanelOptions) VariablesPanelResult`。变量按名称以点连接成路径作为键，同层重名 panic。修改值通过结果交给调用方写回调试器并传入新值。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Variable.Name`, `Value`, `Type` | `string` | — | 名称、显示值与类型。 |
+| `Variable.Changed` | `bool` | false | 值自上次停止后变化。 |
+| `Variable.Children` | `[]Variable` | nil（叶子） | 成员；非 nil 时可展开。 |
+| `Disabled` | `bool` | false | 不能编辑。 |
+
+## 状态
+
+变化的值以菱形标记、粗体与 AccentText 显示并带无障碍描述“已变化”；编辑中的输入框；选中行 Selection；无变量；禁用。
+
+## 事件
+
+`Edited`：新值与变量路径。
+
+## 键盘操作
+
+- Tab 到达树；↑/↓ 移动，→ 展开，← 折叠。
+- 叶子上 Enter、F2 或双击：编辑；Enter 确认，Escape 取消。
+
+## 限制
+
+- 子项不支持按需加载；需要时调用方在展开后补充 `Children`。

docs/components/339-hex-viewer.md

@@ -0,0 +1,44 @@
+# 339 HexViewer · 十六进制查看器
+
+## 用途
+
+以偏移、十六进制与 ASCII 三列对照显示字节；两列共享同一选择与光标，只构建可见行。
+
+## 最小示例
+
+```go
+data := []byte("MUJICA court ledger\x00\x01")
+var state mujica.HexViewerState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.HexViewer(c, data, &state, mujica.HexViewerOptions{}).Element.Height(160)
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func HexViewer(c *ui.Context, data []byte, s *HexViewerState, opts HexViewerOptions) ChoiceResult`。每行 16 字节；`s.Selection()` 返回选中范围；光标或锚点越界 panic。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `HexViewerState.Cursor`, `Anchor` | `int` | 0 | 光标字节与 Shift 选择的起点。 |
+| `Disabled` | `bool` | false | 不能移动与选择。 |
+
+## 状态
+
+选中字节在两列都显示 Selection 背景，光标字节在两列都加 AccentText 框；不可打印字节显示为点；聚焦时外侧焦点环；空数据；禁用。
+
+## 事件
+
+`Changed()`：光标或选择变化。
+
+## 键盘操作
+
+- Tab 聚焦；←/→ 移动一字节，↑/↓ 移动一行，Home/End 到行首行尾；加 Shift 扩展选择。
+- Cmd+C（macOS）/ Ctrl+C：以空格分隔的十六进制复制选中字节。
+- 点击任一列选择字节，Shift+点击扩展。
+
+## 限制
+
+- 只读，不支持编辑与搜索。

docs/components/340-flamegraph.md

@@ -0,0 +1,50 @@
+# 340 Flamegraph · 火焰图
+
+## 用途
+
+以层叠框绘制性能剖析：点击放大子树，搜索高亮匹配帧，悬停或键盘移动时显示并朗读耗时读数。
+
+## 最小示例
+
+```go
+root := &mujica.FlameNode{Name: "main", Value: 100, Children: []mujica.FlameNode{
+	{Name: "court.Seal", Value: 60}, {Name: "ledger.Write", Value: 30},
+}}
+var state mujica.FlamegraphState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Flamegraph(c, root, &state, mujica.FlamegraphOptions{Unit: "ms"})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func Flamegraph(c *ui.Context, root *FlameNode, s *FlamegraphState, opts FlamegraphOptions) ChoiceResult`。帧宽按耗时占比；放大的帧占满宽度，祖先以淡色整宽显示。子帧耗时之和大于父帧或出现负值时 panic。帧颜色按名称取自主题调色板（AccentText、Info、Success、Warning、加深的 Ornament、TextMuted，均对 Surface 至少 3:1）。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `FlameNode.Name`, `Value`, `Children` | `string`, `float64`, `[]FlameNode` | — | 帧名、含子帧的总耗时与子帧。 |
+| `FlamegraphState.Zoom`, `Focus` | `[]int` | nil（根） | 放大与键盘焦点所在帧的子序号路径。 |
+| `FlamegraphState.Query` | `string` | "" | 搜索高亮。 |
+| `Unit` | `string` | "" | 读数中的单位。 |
+| `Status`, `Error` | `DataStatus`, `string` | `DataReady` | 加载中或失败，与图同高显示。 |
+| `Disabled` | `bool` | false | 不能放大与移动。 |
+
+## 状态
+
+帧为浅色底加同色边框与名称；搜索匹配加 AccentText 粗框，其余帧变淡；焦点帧带焦点环；读数行显示名称、耗时与占比；加载、失败、无数据。
+
+## 事件
+
+`Changed()`：放大或焦点变化（失败状态下点击“重试”也为 true）。
+
+## 键盘操作
+
+- Tab 聚焦图表；↑ 到父帧，↓ 到第一个子帧，←/→ 在兄弟帧间移动；Enter 放大当前帧，Escape 缩小一级。
+- 读数随焦点更新并通过屏幕阅读器朗读。
+
+## 限制
+
+- 窄于 1 DIP 的帧不绘制，窄于 24 DIP 的帧不写名称；用键盘可到达所有帧。
+- 帧行高 28 DIP，窄帧的点击区域可能小于 28 DIP，请用键盘或先放大。