| summary | Review PeekabooCore Service API Reference guidance | ||
|---|---|---|---|
| read_when |
|
This document provides a comprehensive reference for all services available in PeekabooCore. These services are used by both the CLI and Mac app to provide consistent functionality with optimal performance.
- ScreenCaptureService
- ApplicationService
- WindowManagementService
- UIAutomationService
- MenuService
- DockService
- ProcessService
- DialogService
- FileService
- SnapshotManager
- ConfigurationManager
- EventGenerator
Handles all screen capture operations including windows, screens, and areas.
Captures a screenshot of a specific window.
func captureWindow(
element: Element,
savePath: String,
options: CaptureOptions = .init()
) async throws -> CaptureResultParameters:
element: The window element to capturesavePath: Path where the image should be savedoptions: Capture options (format, quality, etc.)
Returns: CaptureResult containing capture metadata
Example:
let result = try await service.captureWindow(
element: windowElement,
savePath: "~/Desktop/window.png"
)Captures a full screen or specific display.
func captureScreen(
displayIndex: Int = 0,
savePath: String,
options: CaptureOptions = .init()
) async throws -> CaptureResultCaptures a specific rectangular area of the screen.
func captureArea(
rect: CGRect,
savePath: String,
options: CaptureOptions = .init()
) async throws -> CaptureResultCaptures all windows for a specific application.
func captureAllWindows(
for app: RunningApplication,
savePath: String,
options: CaptureOptions = .init()
) async throws -> [CaptureResult]Manages application lifecycle and information.
Lists all running applications.
func listApplications() -> [RunningApplication]Returns: Array of running applications with metadata
Finds an application by name or bundle ID.
func findApplication(identifier: String) throws -> RunningApplicationParameters:
identifier: App name or bundle identifier
Throws: ApplicationError.notFound if not found
Launches an application.
func launchApplication(identifier: String) async throws -> RunningApplicationQuits an application gracefully or forcefully.
func quitApplication(_ app: RunningApplication, force: Bool = false) async throwsHides an application.
func hideApplication(_ app: RunningApplication) async throwsShows a hidden application.
func unhideApplication(_ app: RunningApplication) async throwsHandles window manipulation and queries.
Lists all windows for an application.
func listWindows(for app: RunningApplication) throws -> [WindowInfo]Finds a specific window by title or index.
func findWindow(
app: RunningApplication,
title: String? = nil,
index: Int? = nil
) throws -> ElementCloses a window.
func closeWindow(_ window: Element) async throwsMinimizes a window.
func minimizeWindow(_ window: Element) async throwsMaximizes a window.
func maximizeWindow(_ window: Element) async throwsMoves a window to a specific position.
func moveWindow(_ window: Element, to position: CGPoint) async throwsResizes a window.
func resizeWindow(_ window: Element, to size: CGSize) async throwsBrings a window to the front and focuses it.
func focusWindow(_ window: Element) async throwsProvides UI element interaction and automation.
Finds UI elements matching criteria.
func findElement(
matching criteria: ElementCriteria,
in container: Element? = nil,
timeout: TimeInterval = 5.0
) async throws -> ElementClicks on a UI element.
func clickElement(
_ element: Element,
at point: CGPoint? = nil,
clickCount: Int = 1
) async throwsTypes text into an element.
func typeText(
_ text: String,
in element: Element? = nil,
clearFirst: Bool = false
) async throwsScrolls within an element.
func scrollElement(
_ element: Element,
direction: ScrollDirection,
amount: CGFloat
) async throwsPerforms a drag operation.
func dragElement(
from startPoint: CGPoint,
to endPoint: CGPoint,
duration: TimeInterval = 0.5
) async throwsPerforms a swipe gesture.
func swipeElement(
_ element: Element,
direction: SwipeDirection,
distance: CGFloat
) async throwsHandles menu bar and context menu interactions.
Clicks a menu item by path.
func clickMenuItem(
app: RunningApplication,
menuPath: [String]
) async throwsExample:
try await service.clickMenuItem(
app: app,
menuPath: ["File", "Save As..."]
)Lists all menu items for an application.
func listMenuItems(app: RunningApplication) throws -> [MenuItemInfo]Opens a context menu at a specific location.
func openContextMenu(at point: CGPoint) async throwsManages Dock interactions.
Lists all items in the Dock.
func listDockItems() throws -> [DockItem]Clicks a Dock item.
func clickDockItem(identifier: String) async throwsRight-clicks a Dock item to show its menu.
func rightClickDockItem(identifier: String) async throwsManages system processes and shell commands.
Executes a shell command.
func runCommand(
_ command: String,
arguments: [String] = [],
environment: [String: String]? = nil,
currentDirectory: String? = nil
) async throws -> ProcessResultTerminates a process.
func killProcess(pid: Int32, signal: Int32 = SIGTERM) throwsChecks if a process is running.
func checkProcessRunning(name: String) -> BoolHandles system dialogs and alerts.
Finds a dialog by title.
func findDialog(
withTitle title: String? = nil,
timeout: TimeInterval = 5.0
) async throws -> ElementClicks a button in a dialog.
func clickDialogButton(
_ buttonTitle: String,
in dialog: Element
) async throwsDismisses a dialog using keyboard shortcuts.
func dismissDialog(_ dialog: Element) async throwsHandles file selection dialogs.
func handleFileDialog(
_ dialog: Element,
path: String
) async throwsProvides file system operations.
Cleans files matching criteria.
func cleanFiles(
at path: String,
matching criteria: CleanCriteria,
dryRun: Bool = false
) async throws -> CleanResultLists files in a directory.
func listFiles(
at path: String,
recursive: Bool = false
) throws -> [FileInfo]Creates a directory.
func createDirectory(at path: String) throwsPersists UI automation snapshots created by peekaboo see so follow-up commands (click, type, scroll, …) can resolve element IDs and reliably refocus the same window.
Snapshots are stored under ~/.peekaboo/snapshots/<snapshot-id>/ and typically include:
snapshot.json(the serializedUIAutomationSnapshot, includinguiMap+ window metadata)raw.png(the stored screenshot copied into the snapshot)annotated.png(optional, when annotations are generated)
Creates a new empty snapshot and returns its ID.
func createSnapshot() async throws -> StringReturns the most recent valid snapshot ID (if any).
func getMostRecentSnapshot() async -> String?Stores a raw screenshot in the snapshot directory and records basic window metadata.
func storeScreenshot(
snapshotId: String,
screenshotPath: String,
applicationName: String?,
windowTitle: String?,
windowBounds: CGRect?
) async throwsStores an annotated screenshot as annotated.png inside the snapshot directory (optional companion to raw.png).
func storeAnnotatedScreenshot(
snapshotId: String,
annotatedScreenshotPath: String
) async throwsPersists detected UI elements into snapshot.json.
func storeDetectionResult(
snapshotId: String,
result: ElementDetectionResult
) async throwsLoads the persisted snapshot and returns a reconstructed ElementDetectionResult (if present).
func getDetectionResult(snapshotId: String) async throws -> ElementDetectionResult?Fetches a single UIElement from the snapshot’s uiMap.
func getElement(snapshotId: String, elementId: String) async throws -> UIElement?Searches the snapshot’s uiMap for elements matching a query string.
func findElements(snapshotId: String, matching query: String) async throws -> [UIElement]Returns metadata for all snapshot directories.
func listSnapshots() async throws -> [SnapshotInfo]Deletes a specific snapshot directory.
func cleanSnapshot(snapshotId: String) async throwsDeletes all snapshot directories and returns the number removed.
func cleanAllSnapshots() async throws -> IntManages application configuration.
static let shared: ConfigurationManager
var currentConfiguration: Configuration { get }Loads configuration from disk.
func loadConfiguration() -> ConfigurationSaves configuration to disk.
func saveConfiguration(_ config: Configuration) throwsResets configuration to defaults.
func resetToDefaults() throwsLow-level event generation for automation.
Creates mouse events.
static func createMouseEvent(
type: CGEventType,
at point: CGPoint
) -> CGEvent?Creates keyboard events.
static func createKeyboardEvent(
keyCode: UInt16,
down: Bool
) -> CGEvent?Types text using keyboard events.
static func typeText(_ text: String) async throwsAll services throw typed errors for better error handling:
enum ScreenCaptureError: Error {
case permissionDenied
case invalidWindow
case captureF ailed
case fileWriteError(Error)
}
enum ApplicationError: Error {
case notFound(String)
case ambiguousIdentifier([RunningApplication])
case launchFailed(Error)
}
enum UIAutomationError: Error {
case elementNotFound
case interactionFailed
case timeout
}Here's a complete example showing how to use multiple services together:
import PeekabooCore
// Initialize services
let appService = ApplicationService()
let windowService = WindowManagementService()
let captureService = ScreenCaptureService()
let uiService = UIAutomationService()
// Find and focus Safari
let safari = try appService.findApplication(identifier: "Safari")
let windows = try windowService.listWindows(for: safari)
if let firstWindow = windows.first {
try await windowService.focusWindow(firstWindow.element)
}
// Capture the window
let result = try await captureService.captureWindow(
element: firstWindow.element,
savePath: "~/Desktop/safari.png"
)
// Click on a button
let criteria = ElementCriteria(role: .button, title: "Reload")
let button = try await uiService.findElement(matching: criteria)
try await uiService.clickElement(button)- Services are designed to be lightweight and efficient
- They eliminate process spawning overhead compared to CLI invocations
- All async operations use Swift's native concurrency
- Services maintain minimal state for optimal performance
- The Mac app sees 100x+ performance improvement using services directly
- All services are thread-safe and can be used from any thread
- UI operations are automatically dispatched to the main thread
- Async methods use Swift's concurrency model for safety
- Shared state is protected with appropriate synchronization