# IDEA.md – a Launchpad of your own for macOS 26 and later This is a brief. Give it in full to Claude Code (or a similar tool) to build your own implementation. It is based on a finished project, Launchpad 27, and contains what turned out to matter during the build. ## 1. What to build macOS 26 removed Launchpad and replaced it with an Apps view in Spotlight, with no folders of your own and no order of your own. Build a replacement: an app that shows every installed app in a grid across the whole screen, with icon and name, for someone who wants to see everything at once and arrange it themselves. It should be possible to: - open the grid from a screen corner (hot corner), with a global shortcut, from a menu bar icon and from the Dock - launch an app with a click, and close the grid with Esc, a click on empty space or by switching apps - move between pages with a two-finger swipe, arrow keys and clicks on the page dots - search right away by typing; arrows choose among the hits, Return launches - rearrange by dragging, also between pages - create a folder by dragging one app onto another, add more apps to it, drag them out again and rename the folder - set the number of apps per row and the number of rows - import the order and the folders from the old Launchpad, if its database is still there - start the app in the background at login, with no icon in the Dock Not included: uninstalling apps, the pinch gesture on the trackpad, badges and download progress on the icons, folders inside folders. ## 2. Stack and architecture - **Swift and AppKit.** No language is required, but the app is almost nothing but calls to macOS's own APIs: a window across all Spaces, app icons, global mouse monitoring, a shortcut. Rust with objc2 works, but then every call goes through bindings. - **Swift Package Manager, no Xcode project.** Two targets: a core with all the logic and no window, and a thin AppKit shell. The app bundle is assembled by a build script: the binary, an `Info.plist` from a template, the icon, and `codesign --sign -` (ad hoc). - **Swift Testing** for the core. Command Line Tools are enough to build. - **No external dependencies.** SQLite is in the system. What matters is the split into core and shell. The language and the build setup can be changed. ## 3. Decisions that turned out to matter **No permission in System Settings.** macOS has no API for adding your own action to a screen corner. Watch the pointer yourself with `NSEvent.addGlobalMonitorForEvents(matching: .mouseMoved)` plus a local monitor. Mouse movement in a global monitor doesn't require Accessibility; only keys do. Use Carbon's `RegisterEventHotKey` for the shortcut, for the same reason. The reason is signing: a permission is tied to the signature, and an ad hoc signature changes with every build, so a granted permission stops applying after the next version. **The rules in the core, not in the view.** Everything that may happen to the layout is a function on a data model: move, drop app on app, take out of a folder, reconcile with installed apps, refill pages. Where the cells are and what a drag is aiming at is also worked out in the core. The view asks and draws. That makes the rules testable without a window. **The grid is a custom view with layers, not NSCollectionView and not SwiftUI.** Every cell is a `CALayer`. The view receives all mouse events itself and works out which cell they hit. The drag has to create folders, change page at the edge and move the neighbours aside while you drag, and that is easiest to control when the drag is your own. **A drag changes a working copy.** The grid shows the copy, and it is saved only when you let go. A cancelled drag then changes nothing. **The drag is read from where the pointer is in the cell.** The middle of another icon means "put in a folder". In the gap, the left half of a cell means "before" and the right half "after". The neighbours move only after the pointer has been still for about 0.2 seconds, otherwise they jump around as you drag past. **The corner is triggered by a state machine with a delay.** The pointer has to rest in the corner for a moment (0.15 s), the corner re-arms only when the pointer has left it, and it doesn't trigger while a mouse button is held. With several screens, only corners where the pointer can't continue onto another screen count. **The window sits just below the Dock.** Then the Dock and the menu bar are visible and usable while the grid is up. Set `collectionBehavior` to `canJoinAllSpaces` and `fullScreenAuxiliary`. **The search field has the keyboard all the time.** Catch arrows, Return and Esc in `control(_:textView:doCommandBy:)`, not in `keyDown`. **Background start with a LaunchAgent.** A plist in `~/Library/LaunchAgents` that starts the app with an argument meaning "don't show the grid", and `KeepAlive` with `SuccessfulExit` false so the app restarts after a crash but not after Quit. Set `LSUIElement` in `Info.plist` so the app starts without a Dock icon, and switch to a regular app at launch if the user chose that. ## 4. Pitfalls - **Read the old Launchpad database with its log.** It lives in `$(getconf DARWIN_USER_DIR)com.apple.dock.launchpad/db/db`, not under Application Support. Copy `db`, `db-wal` and `db-shm` to a temporary directory and read the copy. Without the log the contents look completely different (197 apps on 15 pages instead of 158 on one), and the original must never be touched. - **Include HOLDINGPAGE.** In `items`, type 1 is the root, 2 a folder, 3 a page and 4 an app. After the upgrade the whole layout may sit on the page called `HOLDINGPAGE`. Take all the root's children of type 3. A folder's apps sit under the folder's own pages. - **Don't use Spotlight to find apps.** `mdfind` counts helper apps inside other apps. Walk `/Applications`, `/System/Applications`, `~/Applications` and `/System/Cryptexes/App/System/Applications` (Safari), two levels down, never into an `.app`. - **Don't pick F4 as the shortcut.** A global shortcut takes the key from every other program. Require a modifier. - **Turn off the system's own action in the same corner**, otherwise both trigger. Ask the user; never change the setting without a yes. - **Refill the pages when the grid changes size.** Putting the overflow on a page of its own gives tiny pages when the size changes step by step (35 and 20 slots became 20, 5, 5, 5 and 20). - **Dropping last on a full page should move the neighbour, not the dragged item.** Otherwise the view jumps to the next page. - **Make the open folder's panel opaque.** A translucent panel lets the grid's icons show through between the folder's. - **Give the app an icon in the new format.** macOS 26 puts an `.icns` icon, shrunk, on a light grey plate at 16 and 32 pixels. Make an Icon Composer icon (`AppIcon.icon` with `icon.json` and the artwork as a layer without the plate), compile it with `actool` into `Assets.car`, and set `CFBundleIconName`. Keep the `.icns` for older macOS. - **Don't load the LaunchAgent when the user turns it on.** The app is already running, and that starts a second copy. Let it take effect at the next login, and let a copy quit itself if another is already running. - **Install the service only from `/Applications`.** A service that points at a build directory stops working at the next build. - **Address buttons by name in automated tests, never by index.** A test that clicked "button 1" hit the button that changes a system setting. - **Spell the name right from the start.** The name ends up in the bundle id, the data directory, the service's label and the environment variables. Changing it requires code that carries the user's data over. ## 5. Requirements and measures Benchmarks from the finished project, on a Mac with Apple Silicon: - scanning 161 apps: under half a second - a new or removed app is noticed within five seconds (FSEvents) - no permission in System Settings - dmg: around 2 MB, of which the icon in the new format is 1.5 MB - grids from 3×2 to 14×10; icons at most 128 points - the bottom fifth of the screen is left empty ## 6. How it's verified - **Unit tests for the core**: moves, folder rules (the folder stays with one app and disappears when emptied), refilling pages, reconciling with installed apps, storage, the ranking in search, what a drag is aiming at, the corner's geometry with one and several screens, import from a test database with the same schema. The finished project has 86. - **Screenshots without screen capture**: an environment variable that makes the app draw the window's layers to a PNG and quit. Then none of the user's desktop comes along. - **Real events against the built bundle**: keys through System Events, clicks and drags as `CGEvent` from a small script. Read the result from the app's log and from the saved file. - **A data directory of its own for every test**, through an environment variable. The tests never touch the user's real layout. - **Check the icon against what the system draws** (`NSWorkspace.shared.icon(forFile:)`) at 16 and 32 pixels, not against what's in the file. Done means verified, not written. What can only be judged at the screen – swipe gestures, how the drag feels, starting at login – is left to a person, with exact steps. ## 7. How to work - Start with research: how the old Launchpad worked, how other replacements solved the corner and the window, and what's left on the machine. - Write a plan and get it approved before anything is built. Ask about the real decisions: language, ways to open it, whether apps should be uninstallable. - Split the work into issues on a board, one at a time. Write down what was measured when an issue is closed. - Build the core with tests first, then one view at a time, and try each part before starting the next. - Never change a system setting in a test. ## 8. The prompt ``` Read IDEA.md in full. I want to build my own replacement for Launchpad for macOS [version], as described there. Start with research and a plan, and build nothing until I've approved the plan. Check what's on this machine: installed apps, whether the old Launchpad database is still there, and whether the system has an action in the screen corner I want to use ([bottom right]). Ask me about the decisions that are mine: [language], how the app should be opened, and what should not be included. The app should be called [name] and have the bundle id [reverse domain].[Name]. Split the work into issues, one at a time. Verify each issue against the built app before moving on, and say what you couldn't try yourself. ```