esc

The launcher

The search bar that drops out of the notch on ⌥Space. Ledge draws it and opens what's chosen; one add-on finds the rows as the person types, and can answer questions in it. The Store's Launcher is that add-on. Needs Ledge 0.1.0 Beta 7; there's no new LedgeKit API.

Filling the launcher

Add "launcher" to surfaces. While your add-on runs, Ledge sends it a launcher request each time the search changes, with the text as query, and draws the rows you return. When the person picks a category, the request also carries scope: apps, files or settings (Clipboard is Ledge's own), and comes even with an empty query, so Files can offer recent files. Ledge before 0.1.0 Beta 8 sends no scope. When more than one installed add-on declares it, the first one running fills the launcher.

struct LauncherQuery: Codable, Sendable { var query: String; var scope: String? }

handlers.on("launcher") { (request: LauncherQuery) async throws -> [LauncherResult] in
    [LauncherResult(id: "notes", title: "Notes", kind: "Application",
                    iconPath: "/System/Applications/Notes.app", open: "file:///System/Applications/Notes.app")]
}

Define LauncherResult in your add-on with these fields; Ledge reads them by name. Answer within 2 seconds, or the launcher shows no rows for that search.

FieldWhat it is
idUnique among the rows
titleThe row's name, up to 300 characters. A row without one isn't drawn
subtitleA grey line under it, up to 500 characters. Optional
kindWhat it is, shown on the right, like “Application” or “Calculator”
symbolAn SF Symbol, when there's no file to take the icon from. Optional
iconPathA file or app whose Finder icon to show. Optional
openWhat Return opens: a file, http, https or x-apple.systempreferences URL. Anything else is copied instead
copyWhat Return copies when there's nothing to open, and what ⌘C copies. The title if nil
askA question. Choosing the row asks it, as below

Answering questions

When the person chooses a row with ask, Ledge sends a launcher.ask request with that question as query, and shows the answer in the launcher. Return an object with the answer's text (inline Markdown, up to 20,000 characters) and who answered as from, like “Claude”. Ledge waits up to 75 seconds.

struct LauncherAnswer: Codable, Sendable { var text: String; var from: String }

handlers.on("launcher.ask") { (request: LauncherQuery) async throws -> LauncherAnswer in
    guard let key = Keychain.key("claude") else  // your own Keychain helper { throw AddOnError("Add your Claude key in Settings.") }
    return LauncherAnswer(text: try await claude.ask(request.query, key: key), from: "Claude")
}

Throw an AddOnError to say why there's no answer: Ledge shows its message, up to 300 characters, in place of one. Any other failure shows a general message.