Notch UI Window System
Relevant source files
The following files were used as context for generating this wiki page:
The Notch UI Window System is the core architectural component of Buddi responsible for managing and rendering the application's unique "notch-based" interface on macOS. It leverages a custom windowing strategy to anchor interactive elements to the top of the display, simulating or augmenting the hardware notch found on modern MacBooks. The system manages window lifecycle, positioning across multiple displays, and smooth transitions between "closed" (minimal activity) and "open" (expanded detail) states.
The system is designed to provide non-intrusive status monitoring for Claude Code sessions, media playback, and system utilities. It utilizes specialized NSWindow subclasses and high-level layout management to ensure the interface remains accessible even over full-screen applications or the lock screen.
Core Architecture and Lifecycle
The system is managed by the AppDelegate, which orchestrates the creation and destruction of notch windows based on display configuration and user preferences.
Window Management Logic
Buddi supports both single-display and multi-display setups. In multi-display mode, the application maintains a dictionary of windows and view models mapped to specific screen UUIDs.
Window Creation*: Windows are initialized with a specific NSRect at the top-center of the target screen. They use a style mask consisting of .borderless, .nonactivatingPanel, .utilityWindow, and .hudWindow to achieve a floating, non-stealing-focus behavior. Sources: buddi/buddiApp.swift:233-238
- Space Management: The
NotchSpaceManagerensures windows operate at the highest possible window level (2147483647), allowing the notch to appear over almost all other system elements. Sources: buddi/managers/NotchSpaceManager.swift:15-18 - SkyLight Integration: Specialized windows (like
BuddiSkyLightWindow) handle rendering on the lock screen by enabling SkyLight support when the system notificationcom.apple.screenIsLockedis received. Sources: buddi/buddiApp.swift:94-115
Key Window Components
| Component | Description | File Reference |
|---|---|---|
BuddiSkyLightWindow | A specialized NSPanel subclass that supports rendering over the macOS lock screen. | buddi/buddiApp.swift:236 |
NotchSpaceManager | Manages the CGSSpace and high-level window layering to ensure visibility. | buddi/managers/NotchSpaceManager.swift |
FirstMouseHostingView | A specialized NSHostingView that ensures the window accepts the first click even when inactive. | buddi/buddiApp.swift:42-44 |
Layout and States
The system transitions between different visual states based on user interaction and background activity (e.g., Claude Code events or music playback).
State Transitions
The system primarily toggles between two states defined in NotchState:
- Closed: A minimal "pill" or "bar" anchored to the top of the screen.
- Open: An expanded panel showing detailed tabs (Buddy, Home, Shelf).
Adaptive Chin Width
A unique feature of the ContentView layout is the "computed chin width." When the notch is in the .closed state, its horizontal footprint expands dynamically to accommodate "Live Activity" indicators, such as Claude processing icons or music visualizers.
Sources: buddi/ContentView.swift:54-73
Interaction Systems
The Notch UI Window System employs several methods for user interaction that do not require standard window focus.
Gesture Control
The system implements custom pan gesture recognizers for "Down" (to open) and "Up" (to close) movements.
- Sensitivity: User-adjustable via
Defaults[.gestureSensitivity]. - Haptics: Triggers sensory feedback on successful gesture completion if enabled.
Sources: buddi/ContentView.swift:156-172, buddi/components/Settings/SettingsView.swift:214-228
Hover and Drag Detection
- Hover Delay: The notch can be configured to open automatically when the mouse hovers over the closed area for a specific duration (e.g., 0.0 to 1.0 seconds). Sources: buddi/components/Settings/SettingsView.swift:245-255
- Drag Sensing: The system uses a
DragDetectorto monitor file dragging. When a file enters the "notch region" at the top of the screen, the system can automatically expand the "Shelf" view to accept the drop. Sources: buddi/buddiApp.swift:162-185
Configuration and Sizing
The system's dimensions are highly configurable to match different hardware profiles (Notch vs. Non-Notch displays).
| Setting | Options / Range | Default Behavior |
|---|---|---|
notchHeightMode | matchRealNotchSize, matchMenuBar, custom | Matches hardware notch (~38px) |
nonNotchHeight | 0 - 40 px | Matches menubar (~24px) |
showOnAllDisplays | Boolean | If false, only appears on preferred/main screen. |
extendHoverArea | Boolean | Increases the hit-test area for easier interaction. |
Sources: buddi/components/Settings/SettingsView.swift:105-155, buddi/components/Settings/SettingsView.swift:850-865
Live Activity Rendering
When "Closed," the window renders "Live Activity" modules within its minimal footprint. These include:
- Buddy Activity: Shows the current state of Claude (Processing, Waiting for Approval, or Ready). Sources: buddi/ContentView.swift:440-465
- Music Activity: Renders a tiny album art thumbnail and an optional audio spectrum visualizer. Sources: buddi/ContentView.swift:302-340
- System HUDs: Replaces macOS system HUDs for volume and brightness with an inline indicator within the notch area. Sources: buddi/components/Settings/SettingsView.swift:430-460
Conclusion
The Notch UI Window System provides the foundation for Buddi's fluid user experience. By operating at the highest system layers and implementing custom gesture and drag detection, it creates a persistent yet unobtrusive command center that bridges the gap between terminal-based AI tools and the macOS desktop environment.