MacSpatialKit

MacSpatialKit is a small Swift package for building native macOS overlays that understand spatial system features such as the MacBook notch and the inferred Dock region.

It packages the reusable pieces behind a few experimental apps:

• Dock-aware hover drawers, like a task capture surface above the Dock.
• Notch-aware panels, like a small surface that unfolds from the MacBook notch.
• Full-screen transparent overlays, like a Dock runway landing game.

What Is Included

• MacNotch: detects the built-in display and returns the notch rectangle using NSScreen.auxiliaryTopLeftArea and NSScreen.auxiliaryTopRightArea.
• DockGeometry: predicts the bottom Dock span from Dock preferences and screen geometry.
• SpatialOverlayPanel: a transparent, borderless, non-activating panel base for overlay surfaces.
• HoverRevealState: framework-agnostic dwell/reveal/collapse state logic.
• DockRunwayExample: a SwiftPM example app that treats the Dock as a runway.

Installation

Add the package to a SwiftPM project:

.package(url: "https://github.com/nithish6541/MacSpatialKit.git", from: "0.1.0")

Then depend on the library:

.product(name: "MacSpatialKit", package: "MacSpatialKit")

Usage

import MacSpatialKit

if let screen = NSScreen.main {
    let dock = DockAreaPredictor.predictedDockArea(for: screen)
    print(dock.x, dock.width, dock.topY)
}

if let notch = MacNotch.rect {
    print(notch)
}

For production UI, prefer DockGeometry.activeDockArea() because it rejects non-bottom Dock layouts and fullscreen spaces.

Examples

Build the package and Dock Runway example:

swift build
swift run DockRunwayExample

The Examples folder also includes notes from two companion apps:

• DockTodo: a local-first task drawer above the Dock.
• NotchTodo: a compact to-do surface anchored to the MacBook notch.

Limitations

• Dock geometry is predicted. macOS does not provide a public Dock frame API.
• The current Dock predictor supports bottom Dock layouts only.
• Notch APIs require macOS 12 or later and a built-in notched display.
• Spatial UI should be tested on real hardware because display scaling, Spaces, auto-hide Dock behavior, and external monitors all affect geometry.

Attribution

The notch geometry notes in Docs/NotchDetection.md reference ideas from Adam Lyttle's MIT-licensed notchy project. MacSpatialKit's implementation is kept small and focused on the public macOS APIs needed for notch rect detection.