CodexBar 是一个 macOS 菜单栏应用,用于查看本机 Codex 账号状态、额度、Token 用量、详细统计信息
Swift appkitcodexcodex-clideveloper-toolsmacosmacos-appmenu-bar-appopenai-codexproductivityswiftswiftuiusage-tracker
fix: 修复隐藏面板内存增长与侧边窗口恢复
Bob50ab93f57e59
diff --git a/CLAUDE.md b/CLAUDE.mdindex 17b5b1c..ce18cb6 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -264,7 +264,9 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev- 菜单栏按钮左键切换主面板;右键或 Control+点击打开上下文菜单;`⌘,` 打开自定义设置窗口,菜单面板打开时 `⌘L` 打开日志窗口;默认全局快捷键 `⌘⇧W` 由 `GlobalHotKeySettings` 与 `GlobalHotKeyController` 管理- 主面板是锚定 status item 的 `NSPopover` 弹窗,锚点不可信时回退到 `FallbackPanelController` 提供的屏幕顶部居中 `NSPanel` 面板,处理快捷键、屏幕选择和焦点时要保留这两个分支-- 关闭逻辑统一由 `MenuSurfaceDismissMonitor` 管理;`MenuSurfaceFadeCoordinator` 同时调整内容视图和窗口透明度,淡入 0.24 秒、淡出 0.18 秒,只保留一个完成任务,新动画取消旧任务+- `MenuSurfaceDismissMonitor` 将鼠标、键盘和激活事件汇总为关闭请求,`StatusItemController.popoverDidClose` 接收 AppKit 实际关闭回调;主动关闭容器前将 `activeMenuSurface` 设为 `none`,回调只对仍为当前容器的 popover 执行完整收尾+- `MenuSurfaceFadeCoordinator` 同时调整内容视图和窗口透明度,淡入 0.24 秒、淡出 0.18 秒,只保留一个完成任务,新动画取消旧任务+- popover 和备用面板分别持有 `MenuSurfaceAnimationState`,展示前允许动画,淡出期间保持开启,实际关闭后禁用;根视图在禁用时设置 `transaction.animation = nil` 和 `transaction.disablesAnimations = true`,后台刷新继续执行- 主面板的热力图详情、重置次数和任务中心使用 `borderless nonactivating child panel`;设置窗口的主面板布局、通知、自动重置和防睡眠选项使用可获得键盘焦点的 `borderless child panel`- 设置窗口的子面板占同一位置,展开一个必须先 `hide(immediate: true)` 收掉其余的;动作走 `SettingsOptionsPanelAction` 并带上目标 `SettingsOptionsPanel`,互斥与 `closeAll` 都只写在 `SettingsWindowController.handleOptionsAction` 一处,新增面板不会漏配对- 面板控制器只在首次展开时构造,收起动作走 `existingOptionsPanelController` 而不触发构造:`NSHostingController` 与动态面板订阅会常驻到 App 结束,而用户可能一次子面板都没开过@@ -279,7 +281,8 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev- 自动重置或防睡眠的子面板入口条件失效时,`AppSettingsView` 会发送对应的 `close` 动作收起已展开面板;关闭开关时对应设置行不显示状态说明- 四个设置子面板都只由滑杆按钮展开;单个面板的展开和条件失效收起分别使用 `toggle` 与 `close`,切换分页时使用 `closeAll`,开启主开关不自动弹出- 设置子面板收起时,`SidePanelSupport.orderOut` 只有在被关闭面板仍是 key window 时才把焦点还给父窗口;如果焦点已经转移到主面板或其他窗口,不得主动抢回-- 侧边面板公共能力集中在 `Controllers/SidePanelSupport.swift` 里,含 `SidePanelDrawerPresenter`、`SidePanelContentHost`、`SidePanelDrawerAnimator`、panel 工厂和定位夹紧;挂在主面板上的那三个面板优先复用 `SidePanelDrawerPresenter` 这一层,不要另起一套+- 侧边面板公共能力集中在 `Controllers/SidePanelSupport.swift`,重置次数、任务中心和设置子面板复用 `SidePanelDrawerPresenter`;热力图详情独立处理切边和延迟隐藏,复用 `SidePanelContentHost`、`SidePanelDrawerAnimator`、panel 工厂和定位夹紧+- 热力图详情和共享抽屉在立即关闭或窗口已不可见时,重置动画并执行 `orderOut`、移除父子窗口关系;任务中心已结束逻辑展示时,立即关闭请求仍传递给 presenter- 设置窗口的子面板直接复用 `Controllers/SettingsOptionsPanelController.swift`,它在 presenter 之上补齐了装配、两套关闭观察者、顶边对齐定位和高度重算;新增设置子面板只要给它内容工厂,动态高度面板再提供内容变化来源,不要另写一层壳- 设置子面板的公共内边距、间距与外观度量从 `SettingsOptionsPanelMetrics` 取;通知、自动重置和防睡眠面板的下拉控件共用 `SettingsOptionsPicker`;主面板布局使用独立的 28 点拖拽行高且不使用下拉控件- 设置子面板的内容工厂必须走 `SettingsOptionsPanelController.makeContentController(_:rebuiltBy:)`,否则首次展开时原生 Switch 只剩一条空轨道;重建信号由它接在内容外面,内容视图不必知道 `SidePanelEntryCue`diff --git a/CodexBar/Controllers/ActivityCenterPanelController.swift b/CodexBar/Controllers/ActivityCenterPanelController.swiftindex 967e0ab..0b5b6b1 100644--- a/CodexBar/Controllers/ActivityCenterPanelController.swift+++ b/CodexBar/Controllers/ActivityCenterPanelController.swift@@ -73,11 +73,12 @@ final class ActivityCenterPanelController {func hide(immediate: Bool = false) {cancelScheduledPresentation()// 热力图 hover 等高频路径会盲调 hide; 已隐藏时跳过 @Published 写入, 避免整个菜单重算- guard presentationState.isPresented || presenter.isVisible else {+ if presentationState.isPresented || presenter.isVisible {+ cancelScheduledPanelUpdate()+ presentationState.isPresented = false+ } else if !immediate {return}- cancelScheduledPanelUpdate()- presentationState.isPresented = falsepresenter.hide(immediate: immediate)}diff --git a/CodexBar/Controllers/HeatmapDetailPanelController.swift b/CodexBar/Controllers/HeatmapDetailPanelController.swiftindex 5960b69..7a7a1e5 100644--- a/CodexBar/Controllers/HeatmapDetailPanelController.swift+++ b/CodexBar/Controllers/HeatmapDetailPanelController.swift@@ -53,11 +53,12 @@ final class HeatmapDetailPanelController {drawerTransition = .idlependingSideSwitchRequest = nil- guard let panel = contentHost.panel, panel.isVisible else {+ guard let panel = contentHost.panel else {return}- guard !immediate else {+ // AppKit 隐藏父窗口后仍保留子窗口关系, 必须移除才能避免重开时恢复旧详情+ guard !immediate, panel.isVisible else {drawerAnimator.resetVisualState(for: panel)orderOut(panel)returndiff --git a/CodexBar/Controllers/SidePanelSupport.swift b/CodexBar/Controllers/SidePanelSupport.swiftindex 5d4fa3b..9691390 100644--- a/CodexBar/Controllers/SidePanelSupport.swift+++ b/CodexBar/Controllers/SidePanelSupport.swift@@ -247,11 +247,12 @@ final class SidePanelDrawerPresenter {}func hide(immediate: Bool = false) {- guard let panel, panel.isVisible else {+ guard let panel else {return}- if immediate {+ // 不可见的子窗口仍可能挂在父窗口上, 收尾不能只依据 isVisible+ if immediate || !panel.isVisible {visibilityGeneration += 1drawerAnimator.resetVisualState(for: panel)isExitAnimationRunning = falsediff --git a/CodexBar/Controllers/StatusItemController.swift b/CodexBar/Controllers/StatusItemController.swiftindex 462a00f..1dc411c 100644--- a/CodexBar/Controllers/StatusItemController.swift+++ b/CodexBar/Controllers/StatusItemController.swift@@ -23,6 +23,8 @@ final class StatusItemController: NSObject, NSMenuDelegate {private let statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)private let popover = NSPopover()private let menuSurfaceVisibility = MenuSurfaceVisibilityState()+ private let popoverAnimationState = MenuSurfaceAnimationState()+ private let fallbackPanelAnimationState = MenuSurfaceAnimationState()private let activityCenterPresentationState = CodexActivityCenterPresentationState()private let heatmapDetailPanelController = HeatmapDetailPanelController()private let resetCreditsPanelController = ResetCreditsPanelController()@@ -36,7 +38,7 @@ final class StatusItemController: NSObject, NSMenuDelegate {}private lazy var fallbackPanelController = FallbackPanelController { [unowned self] in- makeMenuHostingController(usesPreferredContentSize: false)+ makeMenuHostingController(animationState: fallbackPanelAnimationState, usesPreferredContentSize: false)}private lazy var settingsWindowController = SettingsWindowController(@@ -492,14 +494,18 @@ final class StatusItemController: NSObject, NSMenuDelegate {}private func configurePopover() {- let hostingController = makeMenuHostingController(usesPreferredContentSize: true)+ let hostingController = makeMenuHostingController(animationState: popoverAnimationState, usesPreferredContentSize: true)+ popover.delegate = selfpopover.behavior = .applicationDefinedpopover.animates = falsepopover.contentViewController = hostingController}- private func makeMenuHostingController(usesPreferredContentSize: Bool) -> NSHostingController<AnyView> {+ private func makeMenuHostingController(+ animationState: MenuSurfaceAnimationState,+ usesPreferredContentSize: Bool+ ) -> NSHostingController<AnyView> {let rootView = CodexStatusMenuView(viewModel: viewModel,workflowViewModel: workflowViewModel,@@ -509,6 +515,7 @@ final class StatusItemController: NSObject, NSMenuDelegate {syncSettings: syncSettings,keepAliveController: keepAliveController,menuSurfaceVisibility: menuSurfaceVisibility,+ animationState: animationState,activityCenterPresentationState: activityCenterPresentationState,onUsageHeatmapHoverChange: { [weak self] context inself?.updateHeatmapDetailPanel(context)@@ -939,6 +946,7 @@ final class StatusItemController: NSObject, NSMenuDelegate {menuSurfaceState = .openingactiveMenuSurface = .popover+ popoverAnimationState.allowsAnimations = truemenuSurfaceFadeCoordinator.prepareForFadeIn()popover.show(relativeTo: button.bounds, of: button, preferredEdge: .minY)completeMenuSurfaceOpen()@@ -947,6 +955,7 @@ final class StatusItemController: NSObject, NSMenuDelegate {private func openFallbackPanel(on screen: NSScreen?) {cancelMenuSurfaceTasks()+ fallbackPanelAnimationState.allowsAnimations = truefallbackPanelController.prepareForDisplay(on: screen)menuSurfaceState = .openingactiveMenuSurface = .fallbackPanel@@ -1116,6 +1125,8 @@ final class StatusItemController: NSObject, NSMenuDelegate {menuSurfaceVisibility.endPresentation()guard isActiveMenuSurfaceVisible else {+ popoverAnimationState.allowsAnimations = false+ fallbackPanelAnimationState.allowsAnimations = falsemenuSurfaceFadeCoordinator.resetAlpha()menuSurfaceState = .hiddenactiveMenuSurface = .none@@ -1337,13 +1348,16 @@ final class StatusItemController: NSObject, NSMenuDelegate {}private func closeActiveMenuSurface() {+ // 主动关闭先清除宿主身份, 避免同步的关闭回调重入清理流程+ activeMenuSurface = .noneif popover.isShown {popover.performClose(nil)}fallbackPanelController.orderOut()- activeMenuSurface = .none+ popoverAnimationState.allowsAnimations = false+ fallbackPanelAnimationState.allowsAnimations = false}private enum Metrics {@@ -1401,6 +1415,21 @@ final class StatusItemController: NSObject, NSMenuDelegate {}}+extension StatusItemController: NSPopoverDelegate {+ func popoverDidClose(_ notification: Notification) {+ guard notification.object as? NSPopover === popover, !popover.isShown else {+ return+ }++ popoverAnimationState.allowsAnimations = false+ guard activeMenuSurface == .popover else {+ return+ }++ completeMenuSurfaceClose()+ }+}+/// 菜单侧边面板的互斥名册接口; 面板间互斥和点击区域判定统一走名册遍历private protocol MenuSideDetailPanel: AnyObject {func hide(immediate: Bool)diff --git a/CodexBar/Views/Menu/CodexStatusMenuView.swift b/CodexBar/Views/Menu/CodexStatusMenuView.swiftindex daaaa3b..7cff1b1 100644--- a/CodexBar/Views/Menu/CodexStatusMenuView.swift+++ b/CodexBar/Views/Menu/CodexStatusMenuView.swift@@ -21,6 +21,12 @@ final class MenuSurfaceVisibilityState: ObservableObject {}}+/// 每个宿主独立控制动画, 淡出完成前仍保留可见内容的过渡+@MainActor+final class MenuSurfaceAnimationState: ObservableObject {+ @Published var allowsAnimations = false+}+/// 菜单栏弹出面板根视图, 汇总账号; 实时活动; 额度; token; 同步状态和更新时间struct CodexStatusMenuView: View {static let menuWidth: CGFloat = Metrics.padding * 2 + MenuMetrics.panelPadding * 2 + UsageHeatmap.Metrics.totalWidth@@ -35,6 +41,7 @@ struct CodexStatusMenuView: View {// 同 activityMonitor, 交给活动卡片自行观察, 不让 helper 状态变化重算整个菜单树let keepAliveController: KeepAliveController@ObservedObject var menuSurfaceVisibility: MenuSurfaceVisibilityState+ @ObservedObject var animationState: MenuSurfaceAnimationStatelet activityCenterPresentationState: CodexActivityCenterPresentationStatelet onUsageHeatmapHoverChange: (UsageHeatmapHoverContext?) -> Voidlet onResetCreditsTap: (ResetCreditsPanelContext) -> Void@@ -57,6 +64,14 @@ struct CodexStatusMenuView: View {.animation(Metrics.statusAnimation, value: syncSettings.isEnabled).animation(Metrics.statusAnimation, value: syncSettings.isSyncing).animation(Metrics.statusAnimation, value: syncSettings.hasSyncFailure)+ .transaction { transaction in+ // 已关闭的 NSPopover 仍可能绘制数字过渡, 让字体缓存逐轮增长+ guard !animationState.allowsAnimations else {+ return+ }+ transaction.animation = nil+ transaction.disablesAnimations = true+ }}}diff --git a/Config/Version.xcconfig b/Config/Version.xcconfigindex 55568cd..3653356 100644--- a/Config/Version.xcconfig+++ b/Config/Version.xcconfig@@ -1,2 +1,2 @@-MARKETING_VERSION = 3.7.1-CURRENT_PROJECT_VERSION = 85+MARKETING_VERSION = 3.7.2+CURRENT_PROJECT_VERSION = 86diff --git a/Docs/DeveloperGuide/README.md b/Docs/DeveloperGuide/README.mdindex 7122781..e2e5aa3 100644--- a/Docs/DeveloperGuide/README.md+++ b/Docs/DeveloperGuide/README.md@@ -18,6 +18,11 @@| [数据与隐私边界](data-and-privacy.md) | 本地文件、网络访问、云端字段和日志边界 || [开发与验证](development.md) | 工程结构、构建检查、调试和变更验收 |+## 在线资料++- [运行架构](https://codexbar.zabrian.app/architecture)+- [性能报告](https://codexbar.zabrian.app/performance)+## 核心术语| 术语 | 在本项目中的准确含义 |diff --git a/Docs/DeveloperGuide/architecture.md b/Docs/DeveloperGuide/architecture.mdindex 5f0655f..e19a555 100644--- a/Docs/DeveloperGuide/architecture.md+++ b/Docs/DeveloperGuide/architecture.md@@ -2,6 +2,8 @@简体中文 | [English](../en/DeveloperGuide/architecture.md)+进程、数据链路与恢复路径的交互式总览见[运行架构](https://codexbar.zabrian.app/architecture)+## 技术基线CodexBar 是 macOS 15+ 菜单栏应用,使用 Swift 6, SwiftUI, AppKit 和 MVVM。diff --git a/Docs/DeveloperGuide/development.md b/Docs/DeveloperGuide/development.mdindex bbc2b5c..b489529 100644--- a/Docs/DeveloperGuide/development.md+++ b/Docs/DeveloperGuide/development.md@@ -69,6 +69,12 @@ helper 改动还需检查 App 包内可执行文件和 plist 的位置、签名记录验证使用的构建、前置设置、操作序列、实际结果和相关日志,便于复现。+### 性能验证++CPU、内存、唤醒、磁盘活动与采集环境见[性能报告](https://codexbar.zabrian.app/performance)++结果对应报告中记录的构建和测试场景。采集、生成报告和基线对比方法见[性能采集工具说明](../../Scripts/performance/README.md)+## Debug 与 Release| 配置 | App bundle ID | Helper bundle ID |diff --git a/Docs/DeveloperGuide/ui-and-lifecycle.md b/Docs/DeveloperGuide/ui-and-lifecycle.mdindex 9b426f9..918cf5a 100644--- a/Docs/DeveloperGuide/ui-and-lifecycle.md+++ b/Docs/DeveloperGuide/ui-and-lifecycle.md@@ -73,16 +73,9 @@ tooltip 只在存在实时任务持续时间时启动 60 秒计时器,空闲## 主面板-主面板优先使用 `NSPopover`, `behavior` 设为 `applicationDefined`+主面板优先使用 `NSPopover`,`behavior` 设为 `applicationDefined`,`animates` 设为 `false`-CodexBar 自己管理 dismiss,原因包括:--- 主面板可以打开设置、日志和侧边详情面板-- `LSUIElement` 激活切换会制造普通 transient popover 的误关闭-- 侧边面板需要被视为同一个交互表面-- 关闭动画需要统一淡出--[`MenuSurfaceDismissMonitor.swift`](../../CodexBar/Controllers/MenuSurfaceDismissMonitor.swift) 监听全局和本地事件,[`MenuSurfaceFadeCoordinator.swift`](../../CodexBar/Controllers/MenuSurfaceFadeCoordinator.swift) 统一协调关闭动画。+[`MenuSurfaceDismissMonitor.swift`](../../CodexBar/Controllers/MenuSurfaceDismissMonitor.swift) 监听鼠标、键盘和激活事件,通过 `onDismiss` 请求关闭。[`MenuSurfaceFadeCoordinator.swift`](../../CodexBar/Controllers/MenuSurfaceFadeCoordinator.swift) 执行淡入淡出,`StatusItemController` 通过 `NSPopoverDelegate` 接收 popover 的实际关闭回调。### 开合状态机@@ -92,14 +85,16 @@ CodexBar 自己管理 dismiss,原因包括:hidden -> opening -> shown -> closing -> hidden```-它解决快速重复点击产生的中间态:+各状态的操作如下:- `opening` 或 `shown` 时再次 toggle 进入关闭- `closing` 时再次 toggle 先完成旧关闭,再打开新表面- 关闭开始后取消延迟刷新和旧动画-- 非动画关闭会直接完成状态收口,不等待不会发生的 animation completion+- 非动画关闭直接完成状态清理++`activeMenuSurface` 记录当前容器,取值为 `none`、`popover` 或 `fallbackPanel`。主动关闭容器前先将其设为 `none`-只检查 `popover.isShown` 不足以表示 opening 或 fade-out 中的逻辑状态,也无法同时覆盖 fallback panel。+`popoverDidClose` 只处理当前 popover 已关闭的通知,并关闭该宿主的动画许可。当前容器仍为 `popover` 时,它调用 `completeMenuSurfaceClose`,取消待执行任务、收起侧边面板、移除事件监听、结束展示状态并安排辅助窗口焦点恢复。### 关闭事件监听@@ -125,6 +120,14 @@ hidden -> opening -> shown -> closing -> hidden关闭期间设置和日志窗口暂时拒绝 `makeKey()`,关闭完成后约 120 ms 恢复。完成任务弱引用当次窗口,关闭后恢复内容视图和窗口透明度。+### 内容动画与展示状态++popover 和备用面板分别持有 `MenuSurfaceAnimationState`。展示前将 `allowsAnimations` 设为 `true`,淡出期间保持开启,实际关闭后设为 `false`++`CodexStatusMenuView` 在动画许可关闭时,将根视图事务的 `animation` 设为 `nil`、`disablesAnimations` 设为 `true`。后台数据刷新继续执行。++`MenuSurfaceVisibilityState` 在面板展示后开启,在关闭开始时结束。每次展示递增 `presentationGeneration`,额度和用量区域以该值作为视图身份,重新执行入场动画。+## Fallback panel全局快捷键触发时,状态栏按钮的屏幕位置可能不可用或不可信。此时 [`FallbackPanelController.swift`](../../CodexBar/Controllers/FallbackPanelController.swift) 在鼠标所在屏幕显示浮动面板。@@ -154,7 +157,11 @@ fallback panel 在展示前根据 SwiftUI fitting size 和目标屏幕可见区所有详情面板实现 `MenuSideDetailPanel` 并登记在 `sideDetailPanels` 数组。互斥关闭、主表面关闭和 hit testing 都遍历同一份名册。-hover 类型的热力图面板在打开其他面板前可以渐隐,点击类型的面板通常立即关闭旧面板。这是为了避免同一屏幕位置出现两个反向滑动动画叠加。+热力图悬停请求以动画收起其他侧边面板;重置次数和任务中心的点击请求立即关闭其他侧边面板。++主面板关闭时立即清理侧边面板。热力图详情和共享抽屉在立即关闭或窗口已不可见时,重置抽屉动画、执行 `orderOut` 并移除父子窗口关系。任务中心已结束逻辑展示时,立即关闭请求仍传递给共享抽屉。++热力图按格子的列、行位置错开入场。启用入场动画时,每个格子在自身入场延迟加 0.25 秒后接受悬停;关闭入场动画时立即接受悬停。热力图详情面板以包含标题、日期范围和方格矩阵的完整热力图区域作为垂直锚点,因此主面板区域重排后仍优先保持两者顶边对齐。如果详情面板从该位置向下会超过主面板底边,则定位逻辑将它整体上移到与主面板底边对齐。diff --git a/Docs/README.md b/Docs/README.mdindex eeb5b7e..487e363 100644--- a/Docs/README.md+++ b/Docs/README.md@@ -26,3 +26,8 @@- [UI 与应用生命周期](DeveloperGuide/ui-and-lifecycle.md)- [数据与隐私边界](DeveloperGuide/data-and-privacy.md)- [开发与验证](DeveloperGuide/development.md)++## 在线资料++- [运行架构](https://codexbar.zabrian.app/architecture)+- [性能报告](https://codexbar.zabrian.app/performance)diff --git a/Docs/en/DeveloperGuide/README.md b/Docs/en/DeveloperGuide/README.mdindex d72bab1..2dc4d30 100644--- a/Docs/en/DeveloperGuide/README.md+++ b/Docs/en/DeveloperGuide/README.md@@ -18,6 +18,11 @@| [Data and Privacy Boundaries](data-and-privacy.md) | Local files, network access, cloud fields, and logging boundaries || [Development and Validation](development.md) | Project structure, build checks, debugging, and change acceptance |+## Online Resources++- [Runtime Architecture](https://codexbar.zabrian.app/architecture)+- [Performance Report](https://codexbar.zabrian.app/performance)+## Core Terminology| Term | Precise meaning in this project |diff --git a/Docs/en/DeveloperGuide/architecture.md b/Docs/en/DeveloperGuide/architecture.mdindex 9ec69e2..fa3d455 100644--- a/Docs/en/DeveloperGuide/architecture.md+++ b/Docs/en/DeveloperGuide/architecture.md@@ -2,6 +2,8 @@[简体中文](../../DeveloperGuide/architecture.md) | English+Explore the processes, data flows, and recovery paths in the [Runtime Architecture](https://codexbar.zabrian.app/architecture).+## Technical BaselineCodexBar is a menu bar app for macOS 15 and later, built with Swift 6, SwiftUI, AppKit, and MVVM.diff --git a/Docs/en/DeveloperGuide/development.md b/Docs/en/DeveloperGuide/development.mdindex bc26262..ef4822d 100644--- a/Docs/en/DeveloperGuide/development.md+++ b/Docs/en/DeveloperGuide/development.md@@ -69,6 +69,12 @@ Helper changes also require checking executable and plist placement inside the aRecord the build, initial settings, action sequence, actual results, and relevant logs so validation can be reproduced.+### Performance Validation++View CPU, memory, wakeups, disk activity, and the recording environment in the [Performance Report](https://codexbar.zabrian.app/performance). Results apply to the build and workload recorded in the report.++For collection, report generation, and baseline comparisons, see the [performance tool guide (Chinese)](../../../Scripts/performance/README.md).+## Debug and Release| Configuration | App bundle ID | Helper bundle ID |diff --git a/Docs/en/DeveloperGuide/ui-and-lifecycle.md b/Docs/en/DeveloperGuide/ui-and-lifecycle.mdindex 916da22..086c389 100644--- a/Docs/en/DeveloperGuide/ui-and-lifecycle.md+++ b/Docs/en/DeveloperGuide/ui-and-lifecycle.md@@ -73,16 +73,9 @@ Left-click opens the main panel. Right-click or Control-click opens the context## Main Panel-The main panel prefers an `NSPopover` with `behavior` set to `applicationDefined`.+The main panel prefers an `NSPopover` with `behavior` set to `applicationDefined` and `animates` set to `false`.-CodexBar manages dismissal because:--- The main panel can open Settings, Logs, and side detail panels-- `LSUIElement` activation changes cause ordinary transient popovers to close incorrectly-- Side panels must behave as part of one interaction surface-- Closing needs a consistent fade-out--[`MenuSurfaceDismissMonitor.swift`](../../../CodexBar/Controllers/MenuSurfaceDismissMonitor.swift) observes global and local events. [`MenuSurfaceFadeCoordinator.swift`](../../../CodexBar/Controllers/MenuSurfaceFadeCoordinator.swift) coordinates closing animation.+[`MenuSurfaceDismissMonitor.swift`](../../../CodexBar/Controllers/MenuSurfaceDismissMonitor.swift) observes mouse, keyboard, and activation events and requests dismissal through `onDismiss`. [`MenuSurfaceFadeCoordinator.swift`](../../../CodexBar/Controllers/MenuSurfaceFadeCoordinator.swift) performs fades, and `StatusItemController` receives the popover's actual close callback through `NSPopoverDelegate`.### Open and Close State Machine@@ -92,14 +85,16 @@ CodexBar manages dismissal because:hidden -> opening -> shown -> closing -> hidden```-They resolve intermediate states from rapid repeated clicks:+Operations follow these rules:- Toggling in `opening` or `shown` starts closing- Toggling in `closing` finishes the old close, then opens a new surface- Starting a close cancels delayed refresh and old animations-- A nonanimated close converges state immediately rather than waiting for an animation completion that will never occur+- A nonanimated close completes state cleanup immediately++`activeMenuSurface` identifies the current container as `none`, `popover`, or `fallbackPanel`. An explicit container close sets it to `none` before closing the window.-Checking only `popover.isShown` cannot represent logical opening or fade-out state and cannot cover the fallback panel.+`popoverDidClose` handles notifications only for the owned popover when it is closed and disables that host's animations. If the current container is still `popover`, it calls `completeMenuSurfaceClose` to cancel pending tasks, hide side panels, remove event monitors, end presentation state, and schedule auxiliary-window focus restoration.### Dismiss Event Monitoring@@ -125,6 +120,14 @@ Special rules include:Settings and log windows temporarily reject `makeKey()` during closing and regain that ability about 120 ms after completion. The completion task holds a weak reference to that window and restores content and window opacity after closing.+### Content Animations and Presentation State++The popover and fallback panel each hold a separate `MenuSurfaceAnimationState`. `allowsAnimations` is set to `true` before presentation, remains enabled during fade-out, and becomes `false` after the surface closes.++When animations are disabled, `CodexStatusMenuView` sets the root transaction's `animation` to `nil` and `disablesAnimations` to `true`. Background data refresh continues.++`MenuSurfaceVisibilityState` begins after the panel is shown and ends when closing starts. Each presentation increments `presentationGeneration`; the rate-limit and usage sections use that value as their view identity and run their entrance animations again.+## Fallback PanelThe status-bar button's screen position may be unavailable or untrusted when a global shortcut fires. [`FallbackPanelController.swift`](../../../CodexBar/Controllers/FallbackPanelController.swift) then presents a floating panel on the screen under the pointer.@@ -154,7 +157,11 @@ These panels are mutually exclusive. Opening one closes the others. Each adds itAll detail panels implement `MenuSideDetailPanel` and register in the `sideDetailPanels` array. Mutual exclusion, main-surface closing, and hit testing all iterate over this one registry.-The hover-driven heatmap panel may fade before another panel opens; click-driven panels normally close the old panel immediately. This avoids two opposing slide animations at the same screen location.+Heatmap hover requests animate the dismissal of other side panels. Click requests for Reset Credits and Task Center close other side panels immediately.++Closing the main panel immediately cleans up its side panels. For an immediate close or an already invisible window, heatmap details and the shared drawer reset drawer animations, call `orderOut`, and remove the parent-child window relationship. Task Center forwards immediate-close requests to the shared drawer even when its logical presentation has ended.++Heatmap squares enter with staggered delays based on their column and row. With entrance animations enabled, each square accepts hover after its own entrance delay plus 0.25 seconds. With entrance animations disabled, squares accept hover immediately.The heatmap detail panel uses the complete heatmap area, including its heading, date range, and square grid, as its vertical anchor. Reordering main-panel sections therefore still keeps their top edges aligned whenever possible. If the detail panel would extend below the main panel from that position, placement shifts it upward until their bottom edges align.diff --git a/Docs/en/README.md b/Docs/en/README.mdindex 63537df..3ac3de5 100644--- a/Docs/en/README.md+++ b/Docs/en/README.md@@ -26,3 +26,8 @@- [UI and Lifecycle](DeveloperGuide/ui-and-lifecycle.md)- [Data and Privacy Boundaries](DeveloperGuide/data-and-privacy.md)- [Development and Validation](DeveloperGuide/development.md)++## Online Resources++- [Runtime Architecture](https://codexbar.zabrian.app/architecture)+- [Performance Report](https://codexbar.zabrian.app/performance)diff --git a/README.en.md b/README.en.mdindex 8a31527..8b2e4ae 100644--- a/README.en.md+++ b/README.en.md@@ -13,7 +13,7 @@[](https://github.com/bob-zebedy/CodexBar/releases)[](LICENSE)-[Features](#features) | [Installation](#installation) | [Quick Start](#quick-start) | [Documentation](#documentation) | [Privacy](#privacy)+[Features](#features) | [Installation](#installation) | [Quick Start](#quick-start) | [Documentation](#documentation) | [Privacy](#privacy) | [Runtime Architecture](https://codexbar.zabrian.app/architecture) | [Performance Report](https://codexbar.zabrian.app/performance)<img src="Images/preview-en.gif" width="640" alt="CodexBar preview">diff --git a/README.md b/README.mdindex 60717f8..e629abb 100644--- a/README.md+++ b/README.md@@ -13,7 +13,7 @@[](https://github.com/bob-zebedy/CodexBar/releases)[](LICENSE)-[功能](#功能) | [安装](#安装) | [快速开始](#快速开始) | [使用文档](#使用文档) | [隐私](#隐私)+[功能](#功能) | [安装](#安装) | [快速开始](#快速开始) | [使用文档](#使用文档) | [隐私](#隐私) | [运行架构](https://codexbar.zabrian.app/architecture) | [性能报告](https://codexbar.zabrian.app/performance)<img src="Images/preview-zh.gif" width="640" alt="CodexBar 预览">diff --git a/appcast.xml b/appcast.xmlindex 447472c..c901810 100644--- a/appcast.xml+++ b/appcast.xml@@ -7,6 +7,15 @@<link>https://codexbar.zabrian.app/appcast.xml</link><description>CodexBar appcast feed</description><language>zh-CN</language>+ <item>+ <title>CodexBar.app 3.7.2</title>+ <sparkle:version>86</sparkle:version>+ <sparkle:shortVersionString>3.7.2</sparkle:shortVersionString>+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#3.7.2</sparkle:releaseNotesLink>+ <pubDate>Wed, 09 Sep 2026 22:18:59 +0800</pubDate>+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v3.7.2.dmg" sparkle:edSignature="EF3OF2kd1DSWAJzaWdMUCivhmbdqKblquHCKbH//06mM9brPJz53g6LLAbo4UaFC3nbZzmCIdKRkzEuhYD60CQ==" length="7902987" type="application/octet-stream"/>+ </item><item><title>CodexBar.app 3.7.1</title><sparkle:version>85</sparkle:version>