fix: recover the status item when the menu bar parks it under the notch

[maxmilian]

TL;DR

When a crowded menu bar pushes the status item under the MacBook notch, OpenUsage becomes invisible and unclickable while its log reports "Status item ready". This PR detects that state and recovers: it moves the item back into the visible menu bar, falls back to a small surrogate button if the move doesn't stick, and anchors the panel beside the notch instead of under it.

Closes #993 (opened first per the issue-first flow; measurements and dead-end analysis live there).

What was happening

• macOS lays status items right-to-left; when the right-of-notch area fills up, the leftmost third-party item overflows under the notch (measured: text strip at x 767–937, bars glyph at x 902–938, notch 791–1012 — zero to 24 pt visible).
• The app keeps running and logs Status item ready (button: true, …), so to the user OpenUsage "never launched", and relaunching lands it in the same spot.
• Shrinking the item cannot help: its right edge is pinned by its neighbors, so narrower styles are more hidden. There is no public API to reposition an NSStatusItem.
• Opening the panel (e.g. via the global shortcut) anchored it below the hidden button — a window materializing centered under the notch.

What this changes

• NotchGeometry (new, pure) — computes the notch rect from auxiliaryTop*Area, how much of the button it hides (occluded at ≥75%), and the fallback panel anchor. Mirrors the PanelGeometry pattern; unit-tested with the real measured fixtures.
• Self-rescue (primary) — StatusItemController.repositionStatusItemRightOfNotch() rewrites the item's remembered position (the same NSStatusItem Preferred Position default that ⌘-dragging maintains) and bounces autosaveName so AppKit re-reads it; the item re-lands just right of the notch. Verified live on macOS 26.5.2: a 99%-hidden item moved to the visible menu bar.
• StatusItemOcclusionMonitor (new) — checks after launch, on screen-parameter changes, and on a slow 30 s poll. One rescue per occlusion episode; it re-measures afterwards and only if the item is still hidden shows a surrogate button (borderless non-activating panel, icon-only) just below the menu bar at the nearest visible notch edge — click opens the dashboard, drag to move, right-click → Hide Until Relaunch. Hidden while the dashboard is open, and removed automatically the moment the real item is visible again.
• Panel anchoring — showPanel() anchors at the nearest visible notch edge whenever the button is effectively hidden, so the panel never opens centered under the notch.
• Docs — docs/menu-bar.md gains a short "The notch" section.

Heads-up

• The rescue leans on the undocumented-but-long-stable preferred-position defaults key (it is how every item's position persists). If a future macOS stops honoring it, the post-rescue re-measure catches that and the surrogate button takes over — behavior degrades to "still reachable", never back to "invisible".
• The rescue is zero-sum: re-landing right of the notch nudges a neighbor leftward. Deliberate — the user is trying to reach OpenUsage.
• Non-notched Macs: auxiliaryTop*Area is nil, every new path is inert, zero behavior change.
• An earlier IUO footgun is documented in-code: interpolating statusItem.autosaveName directly writes a key literally named … Optional("Item-0") that AppKit never reads.

Tests

• NotchGeometryTests (8 cases) — fixtures are the real AX measurements from the reproducing machine (screen 1800×1169, notch 791–1012, item frames 767×170 / 902×36).
• Full suite: the only failures are the 4 Codex tests that already fail on a clean main checkout.
• Live verification on macOS 26.5.2 (notched 14"): rescue moves the item into view (screenshot below); with the rescue defeated, the surrogate button appears and opens the panel anchored at the notch edge (anchoring the panel at x=1012 in the log).

Screenshots

Status item rescued back into the visible menu bar (Claude/Codex/Z.ai strip, right of the notch):

Surrogate button (fallback path) below the menu bar at the notch's right edge:

🤖 Generated with Claude Code

https://claude.ai/code/session_019dpF8491eHK8reiuJ8vMxB

[cursor]

Thanks for the PR! OpenUsage reviews external PRs only when they implement an issue a maintainer has already approved with the approved label. Please open an issue, wait for approval, then reopen this (or open a focused PR) linking it with Fixes #<issue>. Happy to take a look once it's linked to an approved issue.

Powered by Cursor Automations

  

_{Sent by Cursor Automation: OpenUsage PR Gatekeeper}