# Conjure A native macOS application launcher. Open it normally or activate it with a configured global shortcut, search for an application, and press Return to open it or bring its existing instance forward. ## Build, run, and install Requires macOS 14 or later and a Swift 6 toolchain (Xcode 16 or later). ```sh make run ``` This builds a release executable, assembles an ad-hoc-signed application at `.build/Conjure.app`, gracefully quits any running instance of that exact development bundle, and launches a fresh process through Launch Services. This ensures rebuilt code is loaded; simply opening an already-running app in Finder does not reload its executable. Other copies of Conjure are left running. The local signature is for development, not notarized distribution. ```sh make build # Build the application without opening it. make install # Install the application at /Applications/Conjure.app. make test # Run behavior and installation safety tests. ``` `make install` rebuilds the signed bundle and installs it without launching it. To install for your user only, or if `/Applications` is not writable: ```sh make install INSTALL_DIR="$HOME/Applications" ``` Installation verifies a temporary copy before replacing the entire existing bundle, so removed resources do not linger. Quit the app at the destination before reinstalling; other running copies are left alone. Unrelated apps and symbolic-link destinations are not replaced. Installation does not request administrator privileges, and the signature remains local/ad-hoc rather than notarized. Open `Package.swift` in Xcode to edit the project. Use the bundled app above to run it with its application identity and metadata. ## Controls - Type to filter applications; the first match is selected automatically. - Up/Down or Control-K/Control-J changes the selection without leaving search or modifying its text. - Return, keypad Enter, the Open Application button, or a double-click opens the selection. - Escape or Command-W dismisses the launcher and restores the previously active application. Switching focus away dismisses it without stealing focus back. - Reopen from Finder or the Dock to show it again with an empty search. Dismissal leaves the process running; Command-Q quits it. - Standard macOS text-editing shortcuts work in the search field. - Command-comma opens the native Settings window. - Drag the panel background to move it. ## Global shortcut Open **Conjure → Settings…** (`⌘,`), click **Record Shortcut…**, and press a combination containing Command, Option, or Control. Shift can be added. The shortcut is saved locally and restored when Conjure starts. No shortcut is claimed until you choose one; **Clear** disables it. For Command-Space, click **Use ⌘Space**. If it conflicts, open **System Settings → Keyboard → Keyboard Shortcuts** and disable or change the conflicting Spotlight or Input Sources binding, or another app's shortcut, then try again. The Settings window includes an **Open Keyboard Settings…** button. Conjure reports conflicts rather than modifying macOS preferences, and a failed change preserves your working shortcut. The global shortcut shows the launcher with an empty query and search focused. Press it again while the launcher is focused to dismiss it and return to the previously active app. If Conjure is running in the background, the shortcut brings it forward. Recording temporarily pauses global activation; Escape, moving focus out of the recorder, or closing Settings cancels recording and restores the saved binding. Activation uses the native macOS hotkey API, without an Accessibility permission or a global keyboard monitor. It works only while Conjure is running; it does not launch a quit app or enable launch at login. ## Discovery and search Applications are discovered in `/Applications`, `/System/Applications`, `/System/Library/CoreServices/Applications`, and `~/Applications`, including nested folders. Discovery runs off the UI thread and refreshes whenever the launcher is presented. Hidden items, invalid bundles, and helpers inside application packages are excluded; symlinked applications are deduplicated by their canonical paths. Search is case- and accent-insensitive. Ranking is exact name, full-name prefix, word prefix, ordered word initials, substring, then ordered-subsequence fuzzy matches. Fuzzy matches favor smaller gaps and earlier starts. Ties are alphabetical. Hover over a result to see its path. Launch failures appear in a native alert without dismissing the launcher. Words are runs of letters or numbers separated by spaces, punctuation, or symbols. For example, `settings` matches the second word of System Settings, `gc` matches Google Chrome, and `ss` matches System Settings. Initials must occur in order but can skip words: both `vsc` and `vc` match Visual Studio Code. With an empty search, applications are ordered by successful launch count, then most recent launch, then alphabetically. Usage is stored locally in the app's preferences and survives restarts. Only launches through Conjure count; failed launches do not. Applications without history remain alphabetical. Background discovery preserves the selected application even if its row changes. If that application disappears, the first remaining result is selected. Changing the query or reopening the launcher selects the first result. Applications with identical display names show a muted containing-folder hint beside the name. Copies sharing the same folder show their full application bundle paths instead. Home paths abbreviate to `~`, and long hints truncate in the middle. Unique names have no hint; locations are recalculated whenever discovery refreshes. ## Native UI The launcher keeps its Raycast-inspired 750 × 474-point, titlebar-free rounded panel, large borderless search field, compact icon rows, right-aligned application labels, and bottom-right launch pill. Its Sunset palette uses a dark brown background, soft amber and rust glows, warm cream text, and orange accents on the caret, selection, and action outline. The brown tint is 35% opaque over an active, behind-window `NSVisualEffectView` using the native HUD material. This exposes macOS's blurred backdrop while retaining the warm palette and glows; the system material supplies an opaque fallback when Reduce Transparency is enabled. Both the panel and launch pill use native rounded alpha masks alongside layer clipping, keeping material inside its rounded outline and making the window shadow follow the same shape. AppKit still provides text editing, table navigation, scrolling, application icons, controls, menus, fonts, and visual-effect materials. The background uses cached native radial gradients that fade to transparent: static soft blobs, without animations, timers, image assets, blur filters, or third-party UI dependencies. Decorative drawing does not intercept clicks. Increased-contrast settings strengthen the selection outline, and text colors are tuned for readability across the glows and selection. - `Sources/Conjure`: application lifecycle, launcher and Settings windows, and application launching. - `Sources/ConjureKit`: filesystem discovery, search ranking, launch history, and global shortcut registration. - `Tests/ConjureKitTests`: deterministic discovery, ranking, history, shortcut validation, and installation safety checks. The launcher uses Apple's [visual-effect materials](https://developer.apple.com/documentation/appkit/nsvisualeffectview), [table row selection drawing](https://developer.apple.com/documentation/appkit/nstablerowview/drawselection(in:)), [application launching](https://developer.apple.com/documentation/appkit/nsworkspace/openapplication(at:configuration:completionhandler:)), and [reopen lifecycle](https://developer.apple.com/documentation/appkit/nsapplicationdelegate/applicationshouldhandlereopen(_:hasvisiblewindows:)).