CursorBounds

Precise cursor positioning and contextual information for macOS applications.

Overview

• Cursor positioning - Get precise caret position, text field bounds, or mouse cursor location
• App context - Identify focused application and window
• Browser intelligence - Extract URLs, domains, and page titles (18+ browsers)
• Smart positioning - Calculate optimal popup/overlay placement

Text Caret	Text Field Bounds	Mouse Fallback

Requirements

Requirement	Description
Accessibility Permissions	Required. System will prompt users to grant access.
App Sandbox	Optional for internal use. Must be disabled to track cursors in other apps.

Installation

dependencies: [
    .package(url: "https://github.com/aeastr/CursorBounds.git", from: "1.0.0")
]

import CursorBounds

Usage

Check Permissions

if CursorBounds.isAccessibilityEnabled() {
    // Ready to use
} else {
    CursorBounds.requestAccessibilityPermissions()
}

Get Cursor Position

// Get current cursor origin (caret → text field → mouse fallback)
let origin = CursorBounds.currentOrigin()

// Get specific bounds
let caretBounds = CursorBounds.caretBounds()
let fieldBounds = CursorBounds.textFieldBounds()
let mouseBounds = CursorBounds.mouseBounds()

Smart Popup Positioning

let popupFrame = CursorBounds.smartPosition(
    for: popupSize,
    preferredPosition: .below,
    margin: 8
)

App & Browser Context

let context = CursorContext()

// Focused app info
context.appName        // "Safari"
context.bundleID       // "com.apple.Safari"
context.windowTitle    // "GitHub - Aeastr/CursorBounds"

// Browser-specific
context.currentURL     // "https://github.com/Aeastr/CursorBounds"
context.currentDomain  // "github.com"
context.isSearchField  // true/false

Monitor Cursor Changes

let monitor = CursorMonitor()
monitor.startMonitoring { bounds in
    print("Cursor moved to: \(bounds.origin)")
}

See docs/ for complete API documentation.

Demo App

The included CursorPlayground app demonstrates all features:

Live cursor tracking	Interval-based sampling

Open the Xcode workspace, select CursorPlayground, and run.

Contributing

Contributions welcome. See CONTRIBUTING.md for guidelines.

License

MIT. See LICENSE for details.