Merge branch 'worktree-agent-a1dd614394ee20ff2'

docs/components/401-channel-list.md

@@ -0,0 +1,42 @@
+# 401 ChannelList 频道列表
+
+## 用途
+
+展示频道与私信、未读计数、静音和置顶标记，支持折叠分组与频道选择。
+
+## 最小示例
+
+```go
+groups := []mujica.ChannelGroup{{ID: "ch", Title: "Channels", Channels: []mujica.Channel{
+	{ID: "general", Name: "general", Unread: 3},
+	{ID: "rehearsal", Name: "rehearsal", Pinned: true},
+}}}
+selected := "general"
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.ChannelList(c, &selected, groups, mujica.ChannelListOptions{}).Changed() {
+		_ = selected // show that channel
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`selected *string` 保存频道 ID；`groups []ChannelGroup` 提供分组。分组 ID、频道 ID 必须唯一，名称必填，`Unread` ≥ 0。`Direct`、`Presence`、`Muted`、`Pinned` 控制展示。`Height` 默认 360 DIP；`Disabled` 默认 false；`Revision` 默认 0，原地修改分组或频道数据后递增以刷新缓存。替换分组切片也会刷新。
+
+## 状态
+
+默认、聚焦和悬停状态沿用主题、密度与文字缩放；适用操作在自身或祖先禁用时停止处理。
+
+## 事件
+
+`Changed()` 表示选择 ID 发生变化；分组展开状态在组件内保存。
+
+## 键盘操作
+
+Tab 进入；上下方向键切换行；Enter / Space 选择或折叠；分组标题上的左、右方向键折叠、展开。
+
+## 限制
+
+业务连接、静音设置与置顶持久化由调用方维护。分组排序与校验在数据或 Revision 变化时进行，可见行由 MyGo List 构建。

docs/components/402-chat-message.md

@@ -0,0 +1,41 @@
+# 402 ChatMessage 聊天消息
+
+## 用途
+
+展示连续聊天消息、发送时间、编辑标记，以及调用方提供的回复和回应插槽。
+
+## 最小示例
+
+```go
+prev := mujica.ChatEntry{ID: "1", Author: "Uika", Time: time.Now(), Text: "Rehearsal at nine."}
+m := mujica.ChatEntry{ID: "2", Author: "Uika", Time: time.Now(), Text: "Bring the masks.", Edited: true}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.ChatMessage(c, prev, mujica.ChatMessageOptions{})
+	mujica.ChatMessage(c, m, mujica.ChatMessageOptions{
+		Continued: mujica.ChatContinues(prev, m),
+		Reactions: func() { mujica.Tag(c, "👍 2", mujica.TagOptions{}) },
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`ChatEntry` 包含 `ID`、必填的 `Author`、`Image`、`Time`、`Text`、`Edited`、`Own`。`ChatMessageOptions.Continued` 默认 false；`Reply` 与 `Reactions` 为可选插槽。`ChatContinues(prev, cur)` 要求同一作者、相同 Own、间隔非负且小于五分钟。
+
+## 状态
+
+状态由调用方数据控制；浅深主题、密度与文字缩放随窗口设置变化。适用插槽操作沿用控件焦点和禁用状态。
+
+## 事件
+
+插槽中的按钮、链接和回应事件由调用方处理。
+
+## 键盘操作
+
+可选文字支持选择复制；插槽控件按 Tab 访问。
+
+## 限制
+
+调用方计算 Continued 或使用 ChatContinues；回复与回应的业务逻辑在插槽中实现。

docs/components/403-unread-divider.md

@@ -0,0 +1,35 @@
+# 403 UnreadDivider 未读分隔线
+
+## 用途
+
+标记新消息开始位置，并朗读完整未读计数。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.UnreadDivider(c, 3)
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`count int` 必须 ≥ 0；0 显示“新消息”，正值显示完整计数。
+
+## 状态
+
+状态由调用方数据控制；浅深主题、密度与文字缩放随窗口设置变化。适用插槽操作沿用控件焦点和禁用状态。
+
+## 事件
+
+纯展示，计数由调用方更新。
+
+## 键盘操作
+
+展示组件保持自然焦点序列。
+
+## 限制
+
+组件展示调用方提供的计数。

docs/components/404-read-receipt.md

@@ -0,0 +1,36 @@
+# 404 ReadReceipt 已读回执
+
+## 用途
+
+通过勾选标记与文字展示发送进度，已读时显示多人头像。
+
+## 最小示例
+
+```go
+readers := []mujica.AvatarItem{{Name: "Uika"}, {Name: "Mutsumi"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.ReadReceipt(c, mujica.ReceiptRead, mujica.ReadReceiptOptions{Readers: readers})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`state ReceiptState` 为 `ReceiptSent`、`ReceiptDelivered`、`ReceiptRead`，零值表示已发送。`Readers []AvatarItem` 提供已读头像；`Max` 默认 3，必须 ≥ 0。
+
+## 状态
+
+状态由调用方数据控制；浅深主题、密度与文字缩放随窗口设置变化。适用插槽操作沿用控件焦点和禁用状态。
+
+## 事件
+
+纯展示，回执进度与读者由调用方更新。
+
+## 键盘操作
+
+展示组件保持自然焦点序列。
+
+## 限制
+
+已读数据由调用方提供；头像超过 Max 时显示剩余数量。

docs/components/405-member-list.md

@@ -0,0 +1,42 @@
+# 405 MemberList 成员列表
+
+## 用途
+
+将成员分成在线、离线两组，展示头像、状态、角色并提供选择与打开事件。
+
+## 最小示例
+
+```go
+var s mujica.MemberListState
+members := []mujica.Member{
+	{ID: "1", Name: "Sakiko", Presence: mujica.PresenceOnline, Role: "Leader"},
+	{ID: "2", Name: "Umiri", Presence: mujica.PresenceOffline},
+}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if r := mujica.MemberList(c, &s, members, mujica.MemberListOptions{}); r.Opened != "" {
+		_ = r.Opened // show that member's profile
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`MemberListState` 保存 `Selected` 和滚动位置；`members []Member` 的 ID 唯一、姓名必填。`Image`、`Presence`、`Role` 控制展示。`Height` 默认 360 DIP；`Disabled` 默认 false。修改在线分组时替换成员切片，缓存仅在切片变化时重建。
+
+## 状态
+
+默认、聚焦和悬停状态沿用主题、密度与文字缩放；适用操作在自身或祖先禁用时停止处理。
+
+## 事件
+
+`Changed()` 表示选中成员变化；`Opened` 返回 Enter 或双击打开的成员 ID。
+
+## 键盘操作
+
+Tab 聚焦列表；上下方向键选择；Home / End 首尾；Enter 或双击打开成员。
+
+## 限制
+
+分组缓存依据切片身份与长度；成员数据变化后替换切片。

docs/components/406-user-profile-card.md

@@ -0,0 +1,38 @@
+# 406 UserProfileCard 用户资料卡
+
+## 用途
+
+集中展示用户头像、姓名、在线状态、角色、自定义状态与操作插槽。
+
+## 最小示例
+
+```go
+profile := mujica.UserProfile{Name: "Sakiko Togawa", Presence: mujica.PresenceBusy, Role: "Keyboard", Status: "In rehearsal"}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.UserProfileCard(c, profile, mujica.UserProfileCardOptions{Actions: func() {
+		mujica.Button(c, "Message", mujica.ButtonOptions{})
+	}})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`UserProfile.Name` 必填；`Image`、`Presence`、`Role`、`Status`、`About` 提供展示内容。`UserProfileCardOptions.Width` 默认 300 DIP，必须 ≥ 0；`Actions func()` 提供可选操作。
+
+## 状态
+
+状态由调用方数据控制；浅深主题、密度与文字缩放随窗口设置变化。适用插槽操作沿用控件焦点和禁用状态。
+
+## 事件
+
+操作由 `Actions` 插槽中的控件返回。
+
+## 键盘操作
+
+Tab 访问操作插槽；Enter / Space 激活按钮。
+
+## 限制
+
+业务动作、头像加载与个人资料更新由调用方处理。

docs/components/407-online-status.md

@@ -0,0 +1,35 @@
+# 407 OnlineStatus 在线状态
+
+## 用途
+
+用圆形、月牙、横杠圆形和空心圆配合文字表示四种在线状态。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.OnlineStatus(c, mujica.PresenceAway, mujica.OnlineStatusOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`p Presence` 的零值为离线，支持 `PresenceOnline`、`PresenceAway`、`PresenceBusy`、`PresenceOffline`。`HideText` 默认 false；隐藏文字时保留名称和提示。`Size` 默认 10 DIP，必须 ≥ 0。
+
+## 状态
+
+状态由调用方数据控制；浅深主题、密度与文字缩放随窗口设置变化。适用插槽操作沿用控件焦点和禁用状态。
+
+## 事件
+
+纯展示，在线状态由调用方更新。
+
+## 键盘操作
+
+展示组件保持自然焦点序列。
+
+## 限制
+
+在线状态由调用方提供；隐藏文字仍保留状态形状和无障碍名称。

docs/components/408-status-setter.md

@@ -0,0 +1,38 @@
+# 408 StatusSetter 状态设置
+
+## 用途
+
+编辑自定义状态文字和表情，选择清除期限。
+
+## 最小示例
+
+```go
+status := mujica.CustomStatus{Emoji: "🎻", Text: "Rehearsing"}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.StatusSetter(c, &status, mujica.StatusSetterOptions{}).Changed() {
+		_ = status // publish it; clear it once status.Until passes
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`CustomStatus` 保存 `Emoji`、`Text`、`Until`；零 `Until` 表示持续保留。`Location` 默认 `time.Local`；`Disabled` 默认 false。清除选项为持续保留、30 分钟、1 小时、4 小时、当天结束、本周结束。
+
+## 状态
+
+默认、聚焦和悬停状态沿用主题、密度与文字缩放；适用操作在自身或祖先禁用时停止处理。
+
+## 事件
+
+`Changed()` 表示表情、文字或清除期限改变。调用方载入已有期限时显示实际时间，选择持续保留可清除期限。
+
+## 键盘操作
+
+Tab 访问表情、文字、期限和清除按钮；选择器用方向键移动、Enter 确认、Escape 关闭。
+
+## 限制
+
+Until 作为业务期限返回，调用方负责届时清除状态；组件保持空闲。

docs/components/409-call-controls.md

@@ -0,0 +1,41 @@
+# 409 CallControls 通话控制
+
+## 用途
+
+提供静音、摄像头、屏幕共享和挂断操作，状态由调用方回传。
+
+## 最小示例
+
+```go
+st := mujica.CallState{}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.CallControls(c, st, mujica.CallControlsOptions{
+		OnMute:   func(on bool) { st.Muted = on },
+		OnCamera: func(off bool) { st.CameraOff = off },
+		OnShare:  func(on bool) { st.Sharing = on },
+		OnHangUp: func() {}, // leave the call
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`CallState` 包含 `Muted`、`CameraOff`、`Sharing`。`OnMute`、`OnCamera`、`OnShare`、`OnHangUp` 均必填。摄像头回调参数表示是否关闭。`Disabled` 默认 false。
+
+## 状态
+
+默认、聚焦和悬停状态沿用主题、密度与文字缩放；适用操作在自身或祖先禁用时停止处理。
+
+## 事件
+
+每次操作调用对应回调一次；调用方回传更新后的 CallState。
+
+## 键盘操作
+
+Tab 进入工具栏；左右方向键移动；Enter / Space 激活。Cmd/Ctrl+D 静音，Cmd/Ctrl+E 摄像头，Cmd/Ctrl+Shift+S 共享，Cmd/Ctrl+Shift+H 挂断。
+
+## 限制
+
+通话、设备和屏幕采集由调用方处理；快捷键作用于当前窗口。

docs/components/410-video-call-grid.md

@@ -0,0 +1,39 @@
+# 410 VideoCallGrid 视频通话宫格
+
+## 用途
+
+按宫格显示调用方提供的视频帧，标记正在发言和静音的参与者。
+
+## 最小示例
+
+```go
+people := []mujica.CallParticipant{
+	{ID: "1", Name: "Sakiko", Speaking: true}, // Frame: the latest decoded frame
+	{ID: "2", Name: "Uika", Muted: true},
+}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.VideoCallGrid(c, people, mujica.VideoCallGridOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`people []CallParticipant` 的 ID 唯一、Name 必填；`Frame ui.ImageSource` 提供视频帧，`Image` 提供头像。`Muted`、`CameraOff`、`Speaking` 控制状态。`Columns` 默认 0，自动选择列数，必须 ≥ 0。
+
+## 状态
+
+状态由调用方数据控制；浅深主题、密度与文字缩放随窗口设置变化。适用插槽操作沿用控件焦点和禁用状态。
+
+## 事件
+
+纯展示，帧和参与者状态由调用方更新。
+
+## 键盘操作
+
+Tab 进入宫格；方向键移动参与者焦点并读取状态。
+
+## 限制
+
+视频解码、采集与帧更新由调用方处理，更新后调用 c.Invalidate()。

docs/components/411-incoming-call-dialog.md

@@ -0,0 +1,39 @@
+# 411 IncomingCallDialog 来电对话框
+
+## 用途
+
+显示语音或视频来电，提供接听、拒绝与可配置的初始焦点。
+
+## 最小示例
+
+```go
+ringing := true
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.IncomingCallDialog(c, &ringing, mujica.IncomingCall{Caller: "Sakiko", Video: true}, mujica.IncomingCallOptions{
+		OnAccept:  func(video bool) {}, // join, with the camera on when video
+		OnDecline: func() {},
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`open *bool` 控制显示；`IncomingCall.Caller` 必填，`Image` 为头像，`Video` 默认 false。`OnAccept func(video bool)` 与 `OnDecline func()` 必填。`FocusAccept` 默认 false，初始聚焦拒绝；`Disabled` 默认 false，禁用时关闭。
+
+## 状态
+
+默认、聚焦和悬停状态沿用主题、密度与文字缩放；适用操作在自身或祖先禁用时停止处理。
+
+## 事件
+
+接听调用 `OnAccept`，视频接听参数为 true；拒绝和 Escape 调用 `OnDecline`。完成后设置 `*open=false`。
+
+## 键盘操作
+
+默认焦点为拒绝；Tab 循环访问操作；Enter / Space 激活；Escape 拒绝；关闭后恢复焦点。
+
+## 限制
+
+来电数据和通话连接由调用方处理；点击遮罩保持来电显示；禁用关闭时回调保持静默。

docs/components/412-emoji-picker.md

@@ -0,0 +1,39 @@
+# 412 EmojiPicker 表情选择器
+
+## 用途
+
+按分类、搜索与最近使用选择表情，并给支持肤色的表情添加肤色修饰符。
+
+## 最小示例
+
+```go
+var recent []string
+tone := 0
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if r := mujica.EmojiPicker(c, mujica.EmojiPickerOptions{Recent: &recent, Tone: &tone}); r.Picked != "" {
+		_ = r.Picked // insert it
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`EmojiPickerOptions.Recent *[]string` 保存最近选择，选择时去重并保留最新 24 个；`Tone *int` 可选，范围 0–5；`Disabled` 默认 false。返回 `EmojiResult` 的命名字段 `Element` 与 `Picked`。
+
+## 状态
+
+默认、聚焦和悬停状态沿用主题、密度与文字缩放；适用操作在自身或祖先禁用时停止处理。
+
+## 事件
+
+`Picked` 是本帧选择的表情；选择时同时更新 Recent，肤色按钮更新 Tone。
+
+## 键盘操作
+
+Tab 访问搜索、肤色、分类、表情；方向键在组内移动；Enter / Space 选择。
+
+## 限制
+
+内置常用表情子集；对支持肤色的条目应用修饰符。

docs/components/413-pinned-messages.md

@@ -0,0 +1,39 @@
+# 413 PinnedMessages 置顶消息
+
+## 用途
+
+展示虚拟化置顶消息列表，发出跳转和取消置顶事件。
+
+## 最小示例
+
+```go
+pins := []mujica.ChatEntry{{ID: "a", Author: "Sakiko", Text: "Rehearsal moves to nine."}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.PinnedMessages(c, pins, mujica.PinnedMessagesOptions{})
+	if r.Unpinned != "" {
+		pins = pins[:0] // unpin it
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`pins []ChatEntry` 的 ID 与 Author 必填。`Height` 默认 320 DIP，必须 ≥ 0；`Disabled` 默认 false。返回 `PinnedMessagesResult`，包含命名字段 `Element`、`Jump`、`Unpinned`。
+
+## 状态
+
+默认、聚焦和悬停状态沿用主题、密度与文字缩放；适用操作在自身或祖先禁用时停止处理。
+
+## 事件
+
+`Jump` 和 `Unpinned` 返回本帧操作的消息 ID；调用方更新消息定位和置顶数据。
+
+## 键盘操作
+
+Tab 访问跳转与取消置顶；方向键移动；Enter / Space 激活。
+
+## 限制
+
+调用方维护置顶消息；列表行只构建可见部分。

docs/components/414-thread-panel.md

@@ -0,0 +1,40 @@
+# 414 ThreadPanel 话题侧栏
+
+## 用途
+
+在侧栏展示原消息与虚拟化回复列表，提供回复输入、发送和关闭。
+
+## 最小示例
+
+```go
+open := true
+root := mujica.ChatEntry{ID: "r", Author: "Sakiko", Text: "Set list for Friday?"}
+var replies []mujica.ChatEntry
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if r := mujica.ThreadPanel(c, &open, root, replies, mujica.ThreadPanelOptions{}); r.Sent != "" {
+		replies = append(replies, mujica.ChatEntry{ID: r.Sent, Author: "Me", Text: r.Sent, Own: true})
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`open *bool` 控制显示；`root ChatEntry` 提供原消息，`replies []ChatEntry` 提供回复。`Width` 默认 360 DIP并受窗口宽度约束；`Disabled` 默认 false，禁用时关闭面板。回复 ID 必须稳定唯一。
+
+## 状态
+
+默认、聚焦和悬停状态沿用主题、密度与文字缩放；适用操作在自身或祖先禁用时停止处理。
+
+## 事件
+
+`Sent` 返回本帧发送的非空回复，发送后清空输入；关闭时设置 `*open=false`。
+
+## 键盘操作
+
+Tab 访问关闭、回复和发送；Enter 发送回复；Escape 关闭面板。
+
+## 限制
+
+回复发送和持久化由调用方完成；原消息区限高滚动，回复列表独立滚动。

docs/components/415-mail-list.md

@@ -0,0 +1,39 @@
+# 415 MailList 邮件列表
+
+## 用途
+
+展示虚拟化邮件列表，包含未读粗体、星标、附件计数、多选与打开事件。
+
+## 最小示例
+
+```go
+var s mujica.ListState[string]
+mails := []mujica.MailItem{{ID: "1", From: "Sakiko", Subject: "Second act", Unread: true, Attachments: 1}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if r := mujica.MailList(c, &s, mails, mujica.MailListOptions{}); r.Starred != "" {
+		mails[0].Starred = !mails[0].Starred
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`ListState[string]` 保存滚动与选择；`MailItem` 包含必填 ID、`From`、`Subject`、`Snippet`、`Time`、`Unread`、`Starred`、`Attachments`。`Height` 默认 420 DIP，必须 ≥ 0；`Disabled` 默认 false。
+
+## 状态
+
+默认、聚焦和悬停状态沿用主题、密度与文字缩放；适用操作在自身或祖先禁用时停止处理。
+
+## 事件
+
+`Changed()` 表示选择变化；`Opened` 返回打开的邮件 ID；`Starred` 返回请求切换星标的 ID。调用方更新数据。
+
+## 键盘操作
+
+上下方向键、Home / End 移动选择；Enter 或双击打开；S 请求星标；Cmd/Ctrl+A 全选；Cmd/Ctrl 点击切换单项，Shift 点击选择范围。
+
+## 限制
+
+星标、已读更新、邮件下载与打开由调用方处理；列表只构建可见行。

docs/components/416-mail-reader.md

@@ -0,0 +1,39 @@
+# 416 MailReader 邮件阅读器
+
+## 用途
+
+展示邮件头、纯文本或安全 Markdown 子集正文，以及附件操作。
+
+## 最小示例
+
+```go
+m := mujica.Mail{From: "Sakiko", Subject: "Second act", Body: "The score is attached.\n> Can you send it?",
+	Attachments: []mujica.MailAttachment{{Name: "score.pdf", Size: 2048}}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if r := mujica.MailReader(c, m); r.Link != "" {
+		c.OpenURL(r.Link)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`Mail.From`、`Subject` 必填；`To`、`Cc`、`Date`、`Body` 为邮件内容。`Format` 默认 `MailPlain`，也支持 `MailMarkdown`。`Attachments []MailAttachment` 提供名称、字节数和 MIME 类型。
+
+## 状态
+
+默认、聚焦和悬停状态沿用主题、密度与文字缩放；适用操作在自身或祖先禁用时停止处理。
+
+## 事件
+
+`Link` 返回安全链接；`Opened`、`Downloaded` 返回附件索引，无事件时为 -1。
+
+## 键盘操作
+
+Tab 访问链接、引用开关和附件；Enter / Space 激活；正文支持选择复制。
+
+## 限制
+
+MarkdownView 处理安全 Markdown 子集，HTML 展示为文字；链接和附件动作由调用方执行。

docs/components/417-mail-composer.md

@@ -0,0 +1,43 @@
+# 417 MailComposer 邮件编辑器
+
+## 用途
+
+编辑收件人、抄送、密送、主题、正文和附件，将草稿交给调用方保存。
+
+## 最小示例
+
+```go
+draft := mujica.MailDraft{To: []string{"uika@example.com"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.MailComposer(c, &draft, mujica.MailComposerOptions{
+		OnSaveDraft: func(d mujica.MailDraft) {}, // store d
+	})
+	if r.Sent {
+		draft = mujica.MailDraft{}
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`MailDraft` 保存 `To`、`Cc`、`Bcc`、`Subject`、`Body`、`Attachments`。`Contacts` 提供联系人。`OnSaveDraft func(MailDraft)` 必填，收到独立的切片副本；`OnAttach func()` 可选；`Disabled` 默认 false。
+
+## 状态
+
+载入含抄送、密送地址的草稿时自动显示对应字段；点击地址字段标签会聚焦编辑器。
+
+默认、聚焦和悬停状态沿用主题、密度与文字缩放；适用操作在自身或祖先禁用时停止处理。
+
+## 事件
+
+`Sent` 表示发送请求，`Discarded` 表示舍弃请求。编辑后静置两秒调用 OnSaveDraft；手动保存立即回调。
+
+## 键盘操作
+
+Tab 访问字段与操作；Cmd/Ctrl+S 保存草稿；组件内 Cmd/Ctrl+Enter 发送；正文 Enter 换行。
+
+## 限制
+
+邮箱语法由 net/mail.ParseAddress 校验；实际发送、附件选择与存储由调用方处理；保存回调在界面线程运行。

docs/components/418-recipient-input.md

@@ -0,0 +1,37 @@
+# 418 RecipientInput 收件人输入
+
+## 用途
+
+通过标签输入收件人，校验邮箱格式并提供联系人建议。
+
+## 最小示例
+
+```go
+var to []string
+contacts := []mujica.Contact{{Name: "Uika Misumi", Email: "uika@example.com"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.RecipientInput(c, &to, mujica.RecipientInputOptions{Contacts: contacts, Label: "To"})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`recipients *[]string` 保存邮箱标签。`Contacts []Contact` 提供 Name、Email；联系人数据变化时替换切片。`Label` 默认“收件人”；`Placeholder` 默认空；`Disabled` 默认 false。
+
+## 状态
+
+默认、聚焦和悬停状态沿用主题、密度与文字缩放；适用操作在自身或祖先禁用时停止处理。
+
+## 事件
+
+返回 `TagsInputParts`；`Changed()` 表示标签变化，`Input` 可用于焦点控制。
+
+## 键盘操作
+
+Enter 或分隔符提交标签；空输入 Backspace 删除末项；上下方向键移动联系人建议，Enter 选择，Escape 收起建议；Tab 可聚焦建议并显示焦点环。
+
+## 限制
+
+联系人姓名中的逗号和引号按邮件地址语法转义。建议最多显示 6 项；联系人匹配在查询或联系人、收件人数据变化时计算；业务邮箱可达性由调用方验证。

docs/components/419-quoted-text.md

@@ -0,0 +1,36 @@
+# 419 QuotedText 引用文字
+
+## 用途
+
+折叠或展开引用文字，并去掉一层引用前缀。
+
+## 最小示例
+
+```go
+open := false
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.QuotedText(c, "> Can you send the score?", &open)
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`text string` 提供引用文字，`open *bool` 控制展开。`QuoteStrip` 去掉每行一个 `>` 及其后一个空格。
+
+## 状态
+
+默认、聚焦和悬停状态沿用主题、密度与文字缩放；适用操作在自身或祖先禁用时停止处理。
+
+## 事件
+
+返回 `ChoiceResult`；`Changed()` 表示折叠状态变化。
+
+## 键盘操作
+
+Tab 聚焦开关；Enter / Space 展开或折叠；展开内容支持选择复制。
+
+## 限制
+
+文本按一层引用规则处理，嵌套引用继续保留标记。

docs/components/420-snooze-picker.md

@@ -0,0 +1,38 @@
+# 420 SnoozePicker 稍后提醒
+
+## 用途
+
+选择快捷提醒时间，或通过日期时间输入设定自定义提醒。
+
+## 最小示例
+
+```go
+var until time.Time
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.SnoozePicker(c, &until, mujica.SnoozePickerOptions{}).Changed() {
+		_ = until // hide the mail until then
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`until *time.Time` 保存提醒时间。`Location` 默认 `time.Local`；`MorningHour` 默认 9，允许 0–23，其中 0 使用默认值；`Now` 默认使用当前帧时间，可传固定时间；`Disabled` 默认 false。`SnoozeChoices` 的 morning 参数直接接受 0–23。
+
+## 状态
+
+默认、聚焦和悬停状态沿用主题、密度与文字缩放；适用操作在自身或祖先禁用时停止处理。
+
+## 事件
+
+返回 `ChoiceResult`；`Changed()` 表示提醒时间改变。
+
+## 键盘操作
+
+Tab 进入；上下方向键选择快捷项；Enter / Space 激活；自定义时间沿用 DateTimePicker 的输入、确认和取消操作。
+
+## 限制
+
+组件返回时间，提醒调度与邮件隐藏由调用方处理；本地日期按日历构造以保留夏令时后的早晨时刻。