Merge branch 'worktree-agent-a9950b6fffa6f4a57'

docs/components/381-file-explorer.md

@@ -0,0 +1,43 @@
+# FileExplorer
+
+## 用途
+
+组合文件夹树、文件列表、导航历史与多选。
+
+## 最小示例
+
+```go
+var state mujica.FileExplorerState
+opts := mujica.FileExplorerOptions{
+	Roots:   []string{"/court"},
+	Folders: func(string) []string { return nil },
+	Entries: func(string) []mujica.FileEntry {
+		return []mujica.FileEntry{{Path: "/court/seal.go", Name: "seal.go", Size: 1024}}
+	},
+}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.FileExplorer(c, &state, opts).Element.Height(240)
+}
+ui.Render(view, 600, 300, 1)
+```
+
+## 参数
+
+Roots、Folders、Entries 必填；Disabled 默认 false；Revision 用于原地更新条目。
+
+## 状态
+
+默认、焦点、禁用；空数据按组件内容展示。
+
+## 事件
+
+Navigated、Changed、Opened 返回本帧导航、选择和打开。
+
+## 键盘操作
+
+Tab 切换；方向键选择；Enter 打开；macOS Command+[ / ] / ↑，其他平台 Alt+← / → / ↑。
+
+## 限制
+
+文件及目录由调用方提供，读取与打开由调用方执行。条目 Path 必须唯一且非空；切片地址、长度或 Revision 变化时重建索引并清理已删除的选择。

docs/components/382-file-grid.md

@@ -0,0 +1,37 @@
+# FileGrid
+
+## 用途
+
+通过缩略图插槽展示文件网格与多选。
+
+## 最小示例
+
+```go
+entries := []mujica.FileEntry{{Path: "/court/seal.go", Name: "seal.go"}}
+var state mujica.FileGridState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.FileGrid(c, entries, &state, mujica.FileGridOptions{}).Element.Height(240)
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+ItemWidth 默认 128 DIP；Thumbnail 返回是否已绘制；Disabled 默认 false；Revision 用于原地更新条目。Path 顺序变化时重建范围选择锚点；相同 Path 顺序保留锚点与滚动位置。
+
+## 状态
+
+默认、焦点、禁用；空数据按组件内容展示。
+
+## 事件
+
+Changed 表示选择变化；Opened 表示打开请求。
+
+## 键盘操作
+
+方向键选择；Command/Ctrl+点击多选；Shift 扩展；Enter 打开。
+
+## 限制
+
+仅创建可见瓦片；缩略图解码由调用方完成。

docs/components/383-file-icon.md

@@ -0,0 +1,35 @@
+# FileIcon
+
+## 用途
+
+按扩展名和文件夹开合显示类型图标。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.FileIcon(c, "seal.go", mujica.FileIconOptions{Size: 32})
+}
+ui.Render(view, 100, 80, 1)
+```
+
+## 参数
+
+Size 默认 20 DIP；Folder 表示目录；Open 需要 Folder。
+
+## 状态
+
+文件、目录关闭、目录打开。
+
+## 事件
+
+展示组件。
+
+## 键盘操作
+
+展示组件，沿用父级焦点。
+
+## 限制
+
+扩展名大小写无关；未知扩展名显示通用文件图标。

docs/components/384-file-preview.md

@@ -0,0 +1,36 @@
+# FilePreview
+
+## 用途
+
+展示图片、文本、代码和不支持类型说明。
+
+## 最小示例
+
+```go
+file := mujica.PreviewFile{Name: "seal.go", Text: "package court\nfunc Seal() {}"}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.FilePreview(c, file, mujica.FilePreviewOptions{}).Element.Height(240)
+}
+ui.Render(view, 500, 300, 1)
+```
+
+## 参数
+
+Name 必填；Image、Text、Language、Size 为调用方数据；Status、Error 描述加载状态。
+
+## 状态
+
+内容就绪、加载、失败、不支持类型。
+
+## 事件
+
+Closed、Opened、Retried 返回关闭、打开和重试请求。
+
+## 键盘操作
+
+Escape 关闭；Tab 到操作；文本支持选择与复制。
+
+## 限制
+
+读取和解码由调用方提供；预览作为内嵌面板布局。

docs/components/385-path-bar.md

@@ -0,0 +1,35 @@
+# PathBar
+
+## 用途
+
+分段跳转，长路径折叠中间段。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.PathBar(c, "/court/chronicles/seals", mujica.PathBarOptions{})
+}
+ui.Render(view, 400, 100, 1)
+```
+
+## 参数
+
+Separator 默认 /；RootLabel 默认分隔符；Disabled 默认 false。
+
+## 状态
+
+默认、焦点、禁用；空数据按组件内容展示。
+
+## 事件
+
+Navigated 返回目标祖先路径。
+
+## 键盘操作
+
+Tab 进入；左右移动；Enter 激活；Escape 关闭折叠菜单。
+
+## 限制
+
+路径必须至少包含一个分段；调用方处理导航。

docs/components/386-rename-inline.md

@@ -0,0 +1,36 @@
+# RenameInline
+
+## 用途
+
+编辑文件名，校验后确认或取消。
+
+## 最小示例
+
+```go
+name, editing := "seal.txt", true
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.RenameInline(c, &name, &editing, mujica.RenameInlineOptions{})
+}
+ui.Render(view, 400, 100, 1)
+```
+
+## 参数
+
+name、editing 必填；Folder 默认 false；Validate 返回错误文案；Disabled 默认 false。
+
+## 状态
+
+默认、焦点、禁用；空数据按组件内容展示。
+
+## 事件
+
+Renamed 表示已写回名称；Canceled 表示取消。
+
+## 键盘操作
+
+Enter 确认；Escape 取消；双击开始编辑；失焦确认有效名称。
+
+## 限制
+
+默认文件名主体选择采用视觉标记和首次输入替换。MyGo ui/editor.go:133 的选择接口为私有；剪贴板和撤销沿用原生编辑器的实际选区。组合输入期间 Enter 由 MyGo ui/editor.go:485、688 处理，组件无法查询组合状态；使用输入法提交文本后再确认。

docs/components/387-file-operation-progress.md

@@ -0,0 +1,36 @@
+# FileOperationProgress
+
+## 用途
+
+显示复制、移动、删除进度、取消和冲突回答。
+
+## 最小示例
+
+```go
+op := mujica.FileOperation{Kind: mujica.FileCopy, Done: 2, Total: 10, Current: "seal.go"}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.FileOperationProgress(c, op, mujica.FileOperationOptions{})
+}
+ui.Render(view, 500, 240, 1)
+```
+
+## 参数
+
+Done、Total、BytesDone、BytesTotal 为计数；Conflict 为冲突名称；Disabled 默认 false。
+
+## 状态
+
+默认、焦点、禁用；空数据按组件内容展示。
+
+## 事件
+
+Canceled、Resolved、ApplyAll 返回操作意图。
+
+## 键盘操作
+
+Tab 到取消、全选规则和冲突选项；Enter / Space 激活。
+
+## 限制
+
+文件操作由调用方执行；非法计数或 Kind 会 panic。

docs/components/388-transfer-queue.md

@@ -0,0 +1,37 @@
+# TransferQueue
+
+## 用途
+
+显示上传下载队列并回传暂停、继续、重试、移除。
+
+## 最小示例
+
+```go
+items := []mujica.QueuedTransfer{{ID: "a", Name: "ledger.zip", Upload: true, Status: mujica.TransferActive, Done: 25, Total: 100}}
+var state mujica.TransferQueueState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.TransferQueue(c, items, &state, mujica.TransferQueueOptions{}).Element.Height(240)
+}
+ui.Render(view, 500, 300, 1)
+```
+
+## 参数
+
+ID 唯一且必填；Status 默认为排队；Revision 原地更新数据时递增；Disabled 默认 false。
+
+## 状态
+
+默认、焦点、禁用；空数据按组件内容展示。
+
+## 事件
+
+Action 与 ID 返回对应传输操作。
+
+## 键盘操作
+
+Tab 在可见行操作间移动；Enter / Space 激活。
+
+## 限制
+
+网络由调用方执行；汇总仅在数据切片或 Revision 变化时重算。

docs/components/389-storage-usage.md

@@ -0,0 +1,36 @@
+# StorageUsage
+
+## 用途
+
+存储分段条、分类明细及键盘读数。
+
+## 最小示例
+
+```go
+segments := []mujica.StorageSegment{{Label: "Documents", Bytes: 24 << 30}, {Label: "Photos", Bytes: 40 << 30}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.StorageUsage(c, segments, mujica.StorageUsageOptions{Capacity: 128 << 30, Label: "Court disk"})
+}
+ui.Render(view, 500, 240, 1)
+```
+
+## 参数
+
+Capacity 必须为正；Label 为业务名称；分类总量须处于容量内；原地更新时递增 Revision，分类明细采用虚拟列表。
+
+## 状态
+
+占用、剩余、焦点读数。
+
+## 事件
+
+方向键读数变化会朗读并记录状态。
+
+## 键盘操作
+
+Tab 聚焦分段条；左右循环读取分类与剩余空间。
+
+## 限制
+
+统计由调用方提供，组件展示分类大小与比例。

docs/components/390-recent-files.md

@@ -0,0 +1,38 @@
+# RecentFiles
+
+## 用途
+
+按今天、昨天、本周与更早分组展示最近文件。
+
+## 最小示例
+
+```go
+now := time.Date(2026, 10, 5, 12, 0, 0, 0, time.UTC)
+files := []mujica.RecentFile{{Path: "/court/seal.go", Opened: now}}
+var state mujica.RecentFilesState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.RecentFiles(c, files, &state, mujica.RecentFilesOptions{Now: now}).Element.Height(240)
+}
+ui.Render(view, 500, 300, 1)
+```
+
+## 参数
+
+Now 默认帧时间；Revision 原地更新时递增；Disabled 默认 false。
+
+## 状态
+
+默认、焦点、禁用；空数据按组件内容展示。
+
+## 事件
+
+Opened、Removed、Cleared 为打开、移除、清空请求。
+
+## 键盘操作
+
+上下选择文件；Enter 打开；Tab 到清除和移除按钮。
+
+## 限制
+
+时间按 Now 时区分组；切片替换或 Revision 更新会重算排序。

docs/components/391-archive-viewer.md

@@ -0,0 +1,37 @@
+# ArchiveViewer
+
+## 用途
+
+展示调用方条目树、大小和压缩率。
+
+## 最小示例
+
+```go
+entries := []mujica.ArchiveEntry{{Path: "court/seal.go", Size: 4000, Packed: 1000}}
+var state mujica.ArchiveViewerState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.ArchiveViewer(c, entries, &state, mujica.ArchiveViewerOptions{}).Element.Height(240)
+}
+ui.Render(view, 600, 300, 1)
+```
+
+## 参数
+
+Path 唯一；Size、Packed 非负；Status、Error 为加载状态；Revision 原地更新时递增。
+
+## 状态
+
+条目树、加载、失败、空列表。
+
+## 事件
+
+Opened 返回文件打开请求；Retried 返回重试请求。
+
+## 键盘操作
+
+上下选择；左右展开折叠；Enter 打开；Tab 到列操作。
+
+## 限制
+
+压缩包解码由调用方完成；祖先目录自动补齐，文件与目录身份冲突会 panic。

docs/components/392-presence-avatars.md

@@ -0,0 +1,36 @@
+# PresenceAvatars
+
+## 用途
+
+显示协作者、溢出人数及跟随入口。
+
+## 最小示例
+
+```go
+people := []mujica.Collaborator{{ID: "ada", Name: "Ada Lovelace"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.PresenceAvatars(c, people, mujica.PresenceAvatarsOptions{})
+}
+ui.Render(view, 300, 100, 1)
+```
+
+## 参数
+
+Max 默认 4；Size 默认 28；Following 为跟随 ID；Disabled 默认 false。
+
+## 状态
+
+默认、焦点、禁用；空数据按组件内容展示。
+
+## 事件
+
+Follow 返回 ID；Unfollow 请求停止跟随。
+
+## 键盘操作
+
+Tab 进入；左右移动；Enter 激活；Escape 关闭溢出名单。
+
+## 限制
+
+在线数据与跟随行为由调用方维护。

docs/components/394-reactions.md

@@ -0,0 +1,36 @@
+# Reactions
+
+## 用途
+
+显示回应计数、当前用户标记与添加选择器。
+
+## 最小示例
+
+```go
+items := []mujica.Reaction{{Emoji: "\U0001f44d", Count: 3, Mine: true}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Reactions(c, items, mujica.ReactionsOptions{Choices: []string{"\U0001f44d", "\U0001f389"}})
+}
+ui.Render(view, 400, 100, 1)
+```
+
+## 参数
+
+Emoji 为显示字符；Count 必须为正；Choices 必填；People 用于提示；Disabled 默认 false。
+
+## 状态
+
+默认、焦点、禁用；空数据按组件内容展示。
+
+## 事件
+
+Toggled 为切换意图；Added 为选择器选项。
+
+## 键盘操作
+
+Tab 到回应与添加；Enter / Space 激活；选择器左右导航；Escape 关闭。
+
+## 限制
+
+计数更新与持久化由调用方执行；传入系统字体支持的表情。

docs/components/395-share-dialog.md

@@ -0,0 +1,40 @@
+# ShareDialog
+
+## 用途
+
+邀请成员、调整权限、移除成员与复制链接回调。
+
+## 最小示例
+
+```go
+open := false
+members := []mujica.ShareMember{{ID: "ada", Name: "Ada", Permission: mujica.PermissionEdit, Owner: true}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.Button(c, "Share", mujica.ButtonOptions{}).Clicked() {
+		open = true
+	}
+	mujica.ShareDialog(c, &open, &members, mujica.ShareDialogOptions{Title: "Ledger", Link: "https://court.org/ledger"})
+}
+ui.Render(view, 600, 400, 1)
+```
+
+## 参数
+
+Title 必填；Link 为空隐藏复制；OnCopy 可覆盖剪贴板动作；Disabled 或祖先禁用关闭弹层。
+
+## 状态
+
+默认、焦点、禁用；空数据按组件内容展示。
+
+## 事件
+
+Invited 为邀请请求；Changed、Removed 已应用成员变化；Copied 为复制请求完成。
+
+## 键盘操作
+
+Tab 在对话框内移动；Enter 邀请或激活操作；Escape 关闭并恢复焦点。
+
+## 限制
+
+权限和成员由调用方持有；网络与链接有效性校验由业务负责。

docs/components/396-permission-select.md

@@ -0,0 +1,36 @@
+# PermissionSelect
+
+## 用途
+
+选择可查看、可评论、可编辑。
+
+## 最小示例
+
+```go
+value := mujica.PermissionView
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.PermissionSelect(c, &value, mujica.PermissionSelectOptions{})
+}
+ui.Render(view, 300, 100, 1)
+```
+
+## 参数
+
+PermissionView 为零值；Label 默认权限；Disabled 默认 false。
+
+## 状态
+
+默认、焦点、禁用；空数据按组件内容展示。
+
+## 事件
+
+ChoiceResult.Changed() 表示值已变化。
+
+## 键盘操作
+
+Enter 打开；上下移动；Enter 确认；Escape 关闭。
+
+## 限制
+
+权限枚举越界会 panic；授权操作由调用方处理。

docs/components/399-live-indicator.md

@@ -0,0 +1,35 @@
+# LiveIndicator
+
+## 用途
+
+显示实时同步状态、离线说明和重试。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.LiveIndicator(c, mujica.LiveOffline, mujica.LiveIndicatorOptions{})
+}
+ui.Render(view, 500, 100, 1)
+```
+
+## 参数
+
+LastSynced 可选；Now 默认帧时间；Error 补充失败原因。
+
+## 状态
+
+已同步、同步中、重连、离线、失败。
+
+## 事件
+
+ChoiceResult.Changed() 表示用户请求重试。
+
+## 键盘操作
+
+Tab 到重试；Enter / Space 激活。
+
+## 限制
+
+同步由调用方执行；状态变化会朗读，减少动画使用静态说明。

docs/components/400-remote-cursor.md

@@ -0,0 +1,40 @@
+# RemoteCursor
+
+## 用途
+
+绘制远程光标、选区与姓名标签。
+
+## 最小示例
+
+```go
+carets := []mujica.RemoteCaret{{ID: "ada", Name: "Ada", Offset: 4, Anchor: 4}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	ui.Box(c).Size(300, 100).Children(func() {
+		mujica.RemoteCursor(c, carets, mujica.RemoteCursorOptions{
+			Caret: func(offset int) ui.Rect { return ui.Rect{X: float32(offset) * 8, Y: 20, H: 20} },
+		})
+	})
+}
+ui.Render(view, 320, 120, 1)
+```
+
+## 参数
+
+ID 唯一且必填；Offset、Anchor 非负；Caret 必填；Selection 返回选区矩形。
+
+## 状态
+
+光标、选区、姓名；覆盖层输入穿透。
+
+## 事件
+
+展示组件。
+
+## 键盘操作
+
+输入穿透至下方编辑器。
+
+## 限制
+
+坐标映射、远程状态由调用方提供；覆盖层放在编辑器后方。