Photo by Julian Hochgesang on Unsplash

I started the day thinking I’d commit a little ActiveSpace polish and maybe write a post about something gentle. Instead I spent the afternoon untangling three different ways macOS 26.5 (Tahoe) had quietly broken two different apps. 26.5 shipped earlier this month. I’d done my post-upgrade checks. I’d run my standard test suite. All seemed to be in order. But there were OS-level changes that broke a couple of the Jorvik apps, subtle changes, innocuous, devoid of headlines, but carrying a cost.

This is the tax. Every major macOS upgrade comes with a bill, and you sometimes get it months later, payable in WTFs.

Rainy Day stopped hiding the cursor

The setup: when the Rainy Day screensaver activates, the cursor needs to disappear. I had two mechanisms running, both of which used to work.

One was a CSS rule — * { cursor: none !important; } — inside the WKWebView that hosts the raindrop effect. WebKit honours this when it processes mouseMoved, so as long as the window has keyboard focus, the cursor inside the WebView is hidden.

The other was a fallback for the dual-display case, where only one of the two screensaver windows is ever key. An .activeAlways NSTrackingArea on the container view, calling NSCursor.set() on a 1x1 transparent NSCursor on every mouseEntered / mouseMoved. macOS delivers mouseMoved to non-key windows when the tracking area opts in, so the cursor gets hidden on every display regardless of key status.

Both mechanisms had been bulletproof since I shipped the dual-display fix. Today’s report from the user: cursor visible on laptop-only, on single-external, on dual-external. Every configuration tested.

The laptop-only case is the one that didn’t make sense. One window, that window is key, WebKit’s CSS rule should fire. It didn’t.

I don’t know exactly what Tahoe changed. The symptom is consistent with WebKit no longer honouring cursor: none at .screenSaver window level, or honouring it only when an element has explicit input focus, or some other shift in policy. I didn’t try to find out. I added a third path instead.

Three mechanisms layered, none bulletproof on its own:

1. resetCursorRects() + addCursorRect() on the container view. The window-server-level cursor mechanism. The window server tracks the mouse independently of which window is key; if a view says “use this cursor in this rect,” that’s what the user sees. Works on every display.
2. The existing tracking area, with one fix: NSImage(size:) alone doesn’t create a bitmap representation. NSCursor materialises a fallback when you hand it an image with zero reps, and that fallback may not be transparent. Drawing into the image with lockFocus() + a clear fill guarantees a transparent bitmap rep exists.
3. CGDisplayHideCursor(CGMainDisplayID()) in the activate path, preceded by NSApp.activate(ignoringOtherApps: true). Rainy Day is LSUIElement — not a regular foreground app — and CGDisplayHideCursor requires the caller to be frontmost. NSApp.activate is allowed for accessory apps, even briefly, even invisibly. The hide call ref-counts, and the saver is covering the screen at the same instant as the activation, so nothing flickers.

The user tested. All three paths fired in the log. Cursor hidden across every configuration.

I left the diagnostic logging in until the fix was confirmed and stripped it after. The three-path stack stays.

Rainy Day couldn’t lock the screen on dismiss

Same app, different bug, found by reading the log while I was diagnosing the first one.

Rainy Day has a “lock on dismiss” option: when the saver tears down because of user input, the screen locks instead of revealing the desktop. The implementation synthesised the standard Lock Screen shortcut, controlcommandQ, by posting a CGEvent at the session event tap. This is the same path AppleScript uses under the hood when it asks System Events to fire a keystroke. It had worked since I added the feature.

The log told a much louder story. Thirteen LockScreen.lock() calls in ONE millisecond. Then four seconds of nothing. Then the safety-net timeout fired and tore the saver down without locking anything.

Two bugs at once.

The first was the burst. Each screensaver window has an NSEvent.addLocalMonitorForEvents watching for .mouseMoved, .keyDown, etc. When the user moves the mouse to dismiss, mouseMoved fires repeatedly — it’s per-pixel-of-motion. The monitor closure called onDismiss, which called dismissWindows, which called LockScreen.lock() and armed the lock observer. The monitor itself wasn’t removed until full teardown, which the lock path defers to the unlock observer. So every mouseMoved during the dismiss burst re-armed the whole flow. Thirteen attempts in a flick of the cursor.

Classic anti-pattern. Event monitor that triggers a one-shot teardown has to disarm itself before invoking the callback, not after. Fixing it took five lines of code.

The second bug is the Tahoe regression: none of those thirteen synthesised keystrokes reached loginwindow. The CGEvent was consumed by the session tap and went nowhere. Whether Tahoe is rejecting synthesised system shortcuts at a finer-grained policy layer, or whether controlcommandQ has been moved behind a new permission, I don’t know. It doesn’t work.

What does work is SACLockScreenImmediate, a private symbol in /System/Library/PrivateFrameworks/login.framework. It’s the IPC path Apple uses internally and what every other menu-bar lock app (Hammerspoon, Bear, etc.) actually calls. It doesn’t synthesise a keystroke — it just tells loginwindow to lock. No Accessibility permission required, because there’s no keystroke to require permission for.

Private API. Could be removed in a future macOS. I verified it’s alive in 26.5 via dlsym before committing to it, kept the existing 4-second safety-net timeout so a future removal degrades to “saver tears down without locking” rather than “user stuck in saver forever,” and moved on.

BrowserNotes put the note on the wrong screen

Different app, different shape of bug, same OS.

BrowserNotes shows a small panel listing the notes you have for the current page. The panel is positioned at the top-right of the browser viewport — not the top-right of the screen, the top-right of the browser. To do that it queries the Accessibility API for the focused browser window’s frame, converts those coordinates to AppKit’s coordinate space, and sets the panel’s origin.

The user reported: with the browser on the second display, the panel appears on the first.

The Accessibility API reports coordinates in a global space whose origin is at the top-left of the primary display (the one with the menu bar), y-down. AppKit reports coordinates in a global space whose origin is at the bottom-left of the primary display, y-up. The conversion is one flip about the primary display’s height. The math is simple if you use the right pivot.

The code used NSScreen.main.frame.height as the pivot. Sonoma documented NSScreen.main as “the screen containing the window with keyboard focus.” If the browser is the focused app on display 2, NSScreen.main is display 2, and — assuming both displays are the same height, which they were in the report — the math accidentally works out.

Tahoe changed the semantics. NSScreen.main now returns the primary display (display 1) regardless of where the focused window is.

Even that wouldn’t have been fatal on equal-height displays, because the y math still gave the right answer. The y-flip bug was hiding. The actual visible bug was a different line: a min() clamp to keep the panel from spilling past the right edge of the display, using NSScreen.main.visibleFrame.maxX. On Tahoe that maxX is display 1’s, so the clamp dragged any x past display 1’s right edge back onto display 1. Browser on display 2 at x=2900, panel target x=3540, clamp pulls it back to 2200. The panel lands on display 1.

Two bugs, one symptom, one Tahoe regression masking the other.

The fix is a helper — axRectToAppKit(_:) that pivots on NSScreen.screens.first.frame.height (the actual anchor of the AX coord space, always, no matter what NSScreen.main reports), and screenContaining(_:) to find the NSScreen whose frame actually contains a given point. The page-highlights HUD now finds the browser’s real screen and clamps against its visible frame. The same y-flip bug existed in two other panels in BrowserNotes; I fixed both defensively.

The point

Two apps. One OS upgrade. Three completely different shapes of breakage:

• Tahoe changed the cursor-visibility policy at screensaver window level.
• Tahoe stopped delivering synthesised system shortcuts to loginwindow.
• Tahoe changed the semantics of an AppKit API I depend on for AX coordinate math.

None of these would have shown up in a feature test. Each one needs the specific combination of: this app, this OS version, this user setup. The cursor bug was easy because the user has dual displays so I had a lot of surface. The BrowserNotes bug was invisible until the user happened to drag the browser onto the second screen. The lock-screen bug was hidden behind a 4-second safety-net timeout that tore the saver down without anyone noticing it had never actually locked.

You don’t find these by running tests. You find them by being the user, or by having a user who tells you. Today I had both. Thank you, dual-screen setup and the user who pays attention.

This is what shipping a suite means. Every major macOS release is N small regressions in N different corners of N different apps, and you pay the bill in afternoons like this one.

Tahoe 26.5 was supposed to be a quiet release. It mostly is. The work is in finding the “mostly.”

I could be wrong

It’s entirely possible that I have misinterpreted things. I am not, by any reasonable measure, a macOS/Swift/SwiftC expert. I’m learning as I go. I may have misread or not understood the documentation. I use Github sources as inspiration/guidance for much of my code — I may well have copy-pasted code without fully understanding it. I own the bugs in my code. OS upgrades just surface issues that are already there.

In fairness

If you’ve read more than one of my posts you might come away thinking I have it in for macOS. I don’t.

Software evolves. APIs deprecate. Documentation drifts. That’s true of every platform with this much surface area, and complaining about it would be like complaining that the tide comes in. I’m not. I’m just writing down what I find when I trip over it, because the tripping-over is where the interesting detail lives.

The blog is a logbook. The wins go in too — they just don’t write themselves up as easily as the breakages, because “thing worked exactly as documented” isn’t much of a story.

I like macOS. I enjoy building for it. Posts like this one are notes from the field, not complaints from the cheap seats. If they ever read otherwise, that’s on me, not on Apple.

Photo by Sergey Sokolov on Unsplash

Last week I needed to copy a column out of an HTML table in an email.

That sentence describes about ten seconds of intention and fifteen seconds of work. The intention: take this column of values, paste it into a spreadsheet, get on with my day. The work, as anyone who has tried it will know: select the whole table (because Mail doesn’t do columns), paste it into a scratch document, manually trim it back to just the column I wanted, and then paste from the scratch document. Easy enough. Daft enough.

The problem isn’t the tax of any one of those steps. It’s that the steps exist at all — that the obvious operation, “I want this column”, has to be expressed as a circuitous series of operations because the only verb available is select-the-text-flow. Text flows in reading order. Reading order doesn’t know about columns. A column, visually, is a rectangle. The verb that matches a rectangle is “draw a rectangle around it.”

That’s CopyLens.

The verb is drawing

The idea is small enough to fit in one sentence. Hit a hotkey; drag a rectangle around the thing you want; release; the thing is on your clipboard. The hotkey defaults to hyper\, which pairs with HyperCaps and lives on the same hand as commandv. Drawing a rectangle has the property that block-select doesn’t: it doesn’t care about reading order, document structure, or where the text “wants” to be. It cares about the rectangle.

For a column out of a table, that’s perfect. Draw a thin rectangle from the top of the column to the bottom; release; paste. The column appears on the clipboard, top to bottom, one line per row, plain text. Mail had no idea what just happened. The browser tab next to it had no idea either. Whatever app is showing the table is uninvolved; CopyLens is reading pixels, not poking at the DOM.

For a column out of a PDF, same gesture, same result. For a column out of an image that’s a screenshot of a PDF, also same gesture, same result. The thing on screen doesn’t need to be selectable text in any conventional sense. It just needs to be visible.

Two outcomes, one gesture

Here’s the part I’m pleased with.

Sometimes the rectangle you draw doesn’t contain text. You wanted a chart, a piece of a diagram, a panel of a UI mockup. The naive design has two hotkeys: one for “copy text from this region”, one for “copy image from this region”. The user picks the right one each time. That’s how every cropping tool I’ve ever used works.

CopyLens doesn’t ask. You draw the rectangle. If there’s text, the text lands on the clipboard. If there isn’t, the cropped image does — as PNG and TIFF, ready to paste into Notes or Keynote or wherever else takes images. The gesture is the same. The output adapts to the content.

Under the hood, the rectangle is captured at native pixel density via ScreenCaptureKit, Apple’s Vision framework runs over the image, and the result either is or isn’t a list of recognised text strings. If it is, they’re joined in reading order and written to the pasteboard as text. If it isn’t, the image is written to the pasteboard. A small HUD confirms which path ran — “Copied 247 chars” or “Copied image 320x180” — and you can paste immediately.

The win isn’t the OCR; it’s the missing mode switch. You don’t have to know, ahead of time, whether the region you’re looking at is text or pixels. You just draw, and the right thing happens.

Full disclosure

Here’s the part I should be honest about.

I built CopyLens in an afternoon. Most of the credit doesn’t belong to me. The engine — ScreenCaptureKit one-shot capture, Vision OCR with language picking, reading-order sort, the image-fallback decision, the multi-display overlay, the lot — I had Claude Code write. One reasonably plain prompt: “build a macOS app that lets the user draw a rectangle on the screen with a hotkey, captures it via ScreenCaptureKit, runs Vision over it, copies text to the clipboard if Vision finds any, otherwise copies the cropped image”. A few back-and-forths to nail the multi-display behaviour and the reading-order sort. A few minutes, give or take.

What I added is the chrome:

• JorvikKit. The About modal, the Settings frame, the menu bar item, the window helper — the same scaffold every Jorvik utility uses, dropped into a new bundle.
• The hotkey recorder. The user-facing thing in Settings, where you click into a field and press the combination you want, and the app re-registers a Carbon hot-key under the covers. That code is older than CopyLens.
• The Sparkle integration. Appcast URL, EdDSA-signed updates, the “Check for Updates” menu item, the once-a-day background poll. Standard issue across the suite.
• The HUD toast. “Copied 247 chars.” Small thing, big difference to whether you trust the app.

If I’d built the engine myself, it would’ve taken me half a day. Maybe longer. I’d have spent an hour finding the right ScreenCaptureKit incantation for a one-shot capture (the API is built around streams; one-shot is a sub-case you have to coax it into). I’d have spent another hour discovering that Vision’s text observations come back in a coordinate system I’d need to flip before sorting. I’d have spent an unknown amount of time deciding what “reading order” actually means for multi-column text, and getting the sort right. None of it is hard. All of it is fiddly. Claude got the whole pipeline working in a single pass, and I am genuinely impressed with the result.

I reviewed the code. It’s clean, idiomatic, well-factored, the way I’d have written it if I’d had the patience to. I ran it through the standard Jorvik test suite — the one I’ve built up over the last few months to validate every utility before release — and it passed. The shape of the code is the shape I would have produced. The things I didn’t have to invest was the time and the patience.

That’s the trade I’m interested in. Not the trade of “AI does my work for me.” The trade of “I get to spend my attention on the part of the project that actually needs me.” The engine doesn’t need me — it’s well-understood Vision plus well-understood ScreenCaptureKit, glued together in the obvious way. The product needs me. The UX, the settings, the where-does-it-live-in-the-menu-bar, the does-the-hotkey-actually-feel-right — those are the parts that take a finished mechanism and turn it into a thing somebody would use. Those I wrote. Those I wanted to write.

The lens metaphor in the name turned out to be a happy accident. You hold up a viewport over a region of the screen; whatever’s inside the lens becomes portable. The pun on “copy” is fine for product-page purposes. The honest version is that I named it before I’d thought too hard about the metaphor, and it landed.

What it’s actually for

I’ve been using CopyLens for a week. The use cases that have come up, ranked by frequency:

1. Columns out of HTML tables. The original motivation.
2. Code snippets from screenshots people send me on Teams. You don’t realise how often this happens until you can do something about it.
3. Quoted paragraphs from PDFs that are scans rather than text. Scientific papers, government documents, anything older than about 2010.
4. Pieces of diagrams from architecture documents. CopyLens hands you the cropped image, you paste into your own document, no link or reference back to the source — which is what you want when the source is mid-edit.
5. Numbers from charts. You point at the legend, you get the legend text. You point at the chart, you get the chart as an image. Two different outputs, one gesture. An accident of the design, not a deliberate feature, but a lovely one.

There’s a sixth category that I expected to use but haven’t: copying text out of running video. The capture is fast enough in principle, but in practice if I want text out of a video I’d rather scrub to a still frame and use a screenshot tool. CopyLens probably could do it. I haven’t needed it to.

The product page

Standard Jorvik shape: macOS 14 or later, universal binary, free, EdDSA-signed updates via Sparkle, no telemetry, no network traffic beyond the appcast poll. The only permission it asks for is Screen Recording, which it has to have in order to read pixels off your screen. Accessibility isn’t required; the hotkey uses Carbon’s RegisterEventHotKey, which doesn’t need it.

If you’ve installed any other Jorvik utility, you know the drill. Installer or .zip, drag to Applications, launch, grant permission, set your hotkey, done. The whole onboarding fits in three minutes.

Coda

Writing this up, I had a thought about the kind of small utility CopyLens is. It’s the sort of thing that probably exists in a hundred slightly different forms scattered across the App Store and various AI-flavoured startup websites. I didn’t go looking. The whole thing is small enough that finding the right existing one would have taken longer than building this one. And mine is free, source-available, has no subscription, doesn’t ship my screen contents anywhere, and was built to scratch one specific itch.

That last point is the one I keep coming back to. The reason this utility is small and pleasant to use is that I knew exactly what I wanted it to do before I started, because I’d run into the problem the day before. The reason it only took an afternoon is that the engine wasn’t the interesting part, and I got to skip it. The reason it exists at all is that I had a column I couldn’t copy.

Now I can.

Rainy Day shipped this past weekend. It puts photo-realistic rain on your desktop after a few minutes of idle time — the kind of slow, ambient rendering you’d expect a screensaver to do. The product page lists it on the Screensavers shelf. The activation flow, the user mental model, the place it occupies on the website — everything about it says “screensaver.”

The bundle on disk says something else. Rainy Day.app. Regular .app extension. No .saver bundle anywhere. It installs to /Applications like a normal application, registers itself as a login item, and waits in the menu bar until your Mac goes idle. When it activates, it does the screensaver thing. When you move the mouse, it does the dismiss thing. But strictly speaking, macOS doesn’t know it’s a screensaver at all. As far as the operating system is concerned, it’s just an LSUIElement app that happens to put fullscreen windows up sometimes.

This post is about why.

The plan, originally

When I started Rainy Day I assumed it would be a .saver bundle. I’d shipped two screensavers that way already — Reverie and ASCII Saver — and I’d written about why I still think screensavers matter. The .saver route is the orthodox path: subclass ScreenSaverView, override animateOneFrame(), drop the bundle into ~/Library/Screen Savers/, and it appears in System Settings. The OS handles activation, deactivation, hot corners, the preview rendering, the configuration sheet. Your code just draws.

That works fine when your code can actually draw. Reverie’s rendering is roulette curves on a CALayer — standard API, no surprises. ASCII Saver hits the camera through an out-of-process helper agent, but the rendering itself is also boring AppKit: a grid of characters drawn into the view. Neither one needs anything the legacyScreenSaver host process — the system process that loads .saver bundles — refuses to give it.

Rainy Day was supposed to use raindrop-fx, a beautiful WebGL library that renders rain on a transparent canvas with proper light refraction through the droplets. The rendering pipeline is WebKit + WebGL, hosted in a WKWebView, with photographic background images blurred behind the canvas. The first version of Rainy Day was a .saver bundle hosting a WKWebView. It worked perfectly. For about four seconds.

The wall

What I learned over the following session, roughly in the order they bit me:

WebContent suspends within seconds of activation. legacyScreenSaver flags everything it hosts as a background view, and macOS’s memory management aggressively suspends the WebContent process behind any background WKWebView. The rain starts falling, runs for a few seconds while the system is still deciding whether you mean it, and then freezes. Subsequent reactivations get a still frame until WebContent decides to wake up again. Sometimes that’s seconds. Sometimes it’s minutes. There is no API to opt out.

The escape hatch was removed in macOS 26. WebKit has an SPI called _alwaysRunsAtForegroundPriority that, until last year, did exactly what its name implies — tell the system to leave this WebContent alone. It’s still in the headers, you can still set it, and it does nothing. Apple removed the implementation when they overhauled the WebContent lifecycle in macOS 26, presumably because the property always smelled like a hack. The headers haven’t caught up. You can spend an afternoon, as I did, convinced you’ve found the magic switch, before discovering it’s a dead one.

CARenderer returns blank frames for WebKit content. With WebContent suspended, I tried rendering offscreen and pushing the result into the saver view manually. CARenderer can snapshot a Core Animation layer tree into an IOSurface, which I could then paint into the screensaver view at whatever frame rate I liked. Except CARenderer doesn’t follow remote layer hosting into WebContent’s GPU process. It captures the local layer backing store, sees nothing there, and returns black.

WKWebView.takeSnapshot returns blank for WebGL. Same problem, same root cause. The snapshot API grabs whatever’s in the layer backing store. For 2D content (text, images, Core Graphics) that works fine. For WebGL, the actual pixels live in a GL framebuffer that’s never composited into the layer backing — the compositor reads it directly. takeSnapshot doesn’t know how to ask the GPU process for those pixels, so it returns black for the canvas region.

ScreenCaptureKit hits an occlusion edge case. Right, I thought, fine. I’ll spawn a separate non-saver helper window off-screen that hosts the WKWebView, let that render at full priority, and use ScreenCaptureKit to capture the helper window into the saver view. This nearly worked. The helper rendered correctly. SCK happily streamed frames from it at sixty hertz. Then the saver activated, covered every display, and SCK’s occlusion logic kicked in — because the helper window was now fully covered by the saver, SCK classified it as occluded and stopped delivering frames. There’s no flag for “capture this even if it’s covered.” SCK at desktopWindow level zero-frames any window the saver covers, by design, because the assumption is you’re capturing things the user can actually see.

Multi-instance lifecycle thrash. System Settings doesn’t just preview a .saver — it spawns several instances of your view class at once. There’s the small thumbnail in the saver list. There’s the larger preview when your saver is selected. There’s a separate instance per display when you click Preview. Each one calls init, then deist, in whatever order the framework feels like. For a stateless drawing saver, that’s fine. For anything that owns a helper process, a capture stream, or any expensive resource, you spend each transition fighting the previous instance’s teardown to make sure your new instance can set up cleanly. The bug surface here is enormous and most of it is invisible until a user opens System Settings.

Ad-hoc signing breaks TCC grants every rebuild. During development I rebuild dozens of times a day. The screensaver host process inherits permission grants — accessibility, screen recording — from the parent bundle, indexed by the binary’s code signature. Ad-hoc signing produces a new hash on every rebuild, which macOS interprets as a new app, which means every rebuild starts with all permissions revoked. You can paper over this with a stable team signing identity during dev, but the friction is real and the failure mode is silent. You launch the saver, the screen capture doesn’t work, and you waste twenty minutes wondering why your code broke before you remember to re-grant the permission.

That’s the list. Each one took a session to discover, a session to understand, and a session to admit there was no workaround that would survive contact with real users. Cumulatively, several days of work, none of it leaving anything behind but a slightly deeper understanding of where the .saver sandbox stops.

The pivot

I sat with this for a while. The honest summary was: legacyScreenSaver’s sandbox is fine for a saver that does standard 2D drawing into an NSView. The moment you want to host a serious rendering pipeline — WebKit, WebGL, Metal, a video decoder, anything with its own process or its own GPU context — you’re asking legacyScreenSaver to do things it was never designed to do, against a system that is actively trying to keep background processes from burning power.

You can fight the system, lose, and ship something that limps. Or you can stop pretending the constraints don’t exist and build the thing as what it actually wants to be: a regular application.

That’s where Rainy Day ended up. The architecture is mundane:

• A regular .app, signed with the team Developer ID.
• LSUIElement=YES in Info.plist, so it’s an accessory app with no Dock icon and no menu bar of its own.
• Registered as a login item via SMAppService.mainApp.register() on first launch.
• A menu-bar status item with About / Activate Now / Settings / Check for Updates / Quit.
• A 1Hz timer polling CGEventSource.secondsSinceLastEventType(.combinedSessionState, …) for idle time.
• When idle exceeds the user’s threshold, the app opens one fullscreen NSWindow per connected NSScreen, at NSWindow.Level.screenSaver, hosting a WKWebView.
• Any mouse or keyboard event in any of those windows tears them all down.

Every constraint of the .saver path falls away.

WebKit runs at full speed because it’s in my app’s process, not legacyScreenSaver’s. There’s no “background view” classification, no aggressive suspension, no need for an SPI escape hatch that doesn’t work any more. WebGL pixels reach the screen via WindowServer’s normal compositing pipeline, the same way any other browser tab’s WebGL reaches the screen — no SCK, no IPC shenanigans, no occlusion edge cases. There’s one process and one lifecycle: preview, fullscreen activation, and per-display rendering are all just “open and close some ordinary windows.” TCC grants persist across rebuilds because my team Developer ID signature is stable. Custom UI — settings window, About modal, global hotkey for Activate Now — is trivial because it’s just AppKit and SwiftUI doing what they do in any other app.

The whole pivot took one afternoon. Most of the code was reusable from the failed .saver attempt — the WKWebView setup, the raindrop-fx integration, the photography handling. What I threw away was the entire scaffold around it: the ScreenSaverView subclass, the configuration sheet, the System Settings integration, all the helper-process workarounds I’d been building to escape the sandbox. None of that has any place in an app that is its own host.

The trade-off

There is one. Rainy Day doesn’t appear in System Settings → Screen Saver, because it isn’t a screensaver. If you’ve set the system saver to Aerial and you want to switch to Rainy Day, you don’t do that from System Settings — you launch Rainy Day, set the system saver to Never, and let Rainy Day handle idle activation directly. There’s a paragraph about this on the product page and a sentence in the welcome dialog. It hasn’t generated any user confusion yet, partly because Jorvik’s audience tends to read the docs, and partly because once you’ve set it up you never think about it again.

The upside of not being in System Settings is that I get to provide my own configuration UI, which is dramatically richer than the .saver configuration sheet would have permitted. Rainy Day’s Settings window has an Activation section with idle threshold and global hotkey, an On Dismiss section with options for what happens when you move the mouse (return to desktop / lock the Mac), a Capture section for the “save current frame” feature, a Backgrounds section with full management of the rotating photography library, and the standard Jorvik General section with Launch at Login. That’s around a dozen controls. The .saver configuration sheet would have given me a modal panel with maybe four. I’d have had to fight the sandbox to do half of what’s in there now.

For users who like keyboard control: every action has a global hotkey, including Activate Now, which means you can trigger Rainy Day at any time with control option command R (or whatever you remap it to). The .saver path can’t do that — global hotkeys require either Carbon’s RegisterEventHotKey from an active process, or accessibility-client status, neither of which fits the saver model.

The wider observation

The interesting thing isn’t the technical detail of any individual friction point. It’s the pattern.

legacyScreenSaver is a system service that Apple ships, maintains in the sense of “keeps compiling,” and clearly hasn’t actually developed in years. The framework around it — ScreenSaverView, the configuration sheet API, the hot-corner activation path — assumes a 2002 rendering model where your saver draws into an NSView with Quartz primitives. Everything that’s been added to macOS since — remote layer hosting, separate GPU processes, aggressive background suspension, TCC, SCK’s occlusion logic — was bolted onto the rest of the system without anyone updating the saver framework to coexist with it. The result is that the API still works for the cases it was built for, and falls down for everything that requires a modern graphics stack.

That isn’t unique to screensavers. There’s a thread of this through several corners of macOS: subsystems that Apple keeps alive but no longer thinks about, where the documented path remains the documented path because nobody has felt strongly enough to deprecate it, but the surrounding system has moved on and the path no longer leads anywhere useful. Login items used to mean a list of .app paths in System Settings; the modern, well-supported way is SMAppService, but the old LSSharedFileList API still compiles. CGSession’s -suspend mode used to lock the screen from code; in macOS 26 the implementation is gone, only the header remains, and you have to drive osascript and trigger an Accessibility prompt to do what one syscall used to do. The seams between “the part Apple still cares about” and “the part Apple maintains but doesn’t love” are everywhere if you go looking.

For an independent developer, the practical question is recognising which side of that seam you’re on early enough to stop wasting time. With Rainy Day the answer came after about three days of fighting the sandbox. If I’d known what I know now I’d have skipped to the .app architecture on day one. That’s what conventions are for — I wrote one up the day after Rainy Day shipped, “Screensaver as standalone app”, and the next two products in the rendering-heavy screensaver pipeline will start there rather than re-litigating the question.

Coda

I still believe screensavers are an interesting and underused canvas. I said as much in the last post on the subject, and shipping Rainy Day hasn’t changed my mind. What’s shifted is my view of the bundle format. The .saver extension is a packaging detail. The user experience — an ambient full-screen thing that activates when you step away — doesn’t require the OS to host you. It just requires you to behave correctly when the user goes idle, which any application can do.

Rainy Day calls itself a screensaver on the product page because that’s what users want it to be. The bundle calls itself an app because that’s what macOS will let it actually be. Both labels are correct for their audience. The mismatch is fine. The rain falls either way.

Photo by Mike Smith on Unsplash

The fortnight that’s just ended started with one of the smallest possible problems: commandspace, “screenlock”, return, and the wrong version of ScreenLock launched. An older build. The settings layout was a previous iteration’s. The pill toggle wasn’t there. I’d been certain I’d installed the new build into /Applications, but here was Spotlight handing me something that contradicted that, looking otherwise indistinguishable from the right answer.

I said “huh” out loud, restarted the app from /Applications directly, finished the test I was doing, and tried to forget about it. Then a few hours later I caught myself doing the same wrong thing with HyperCaps. And after that, with the Notes Editor.

That’s the moment my week stopped being about whatever I’d planned to do and started being about housekeeping. Two weeks later I’ve fixed every known bug across the suite, shipped two new products and a top-level Apps section on the website, rebuilt Release Manager into a thin Swift dispatcher around a shared Make include, delivered on every user feature request that was queued, and reclaimed roughly nine and a half gigabytes of accumulated cruft from disk along the way. I want to write down what the audit-and-cleanup half of that effort looked like, because it’s the part where the most was learned per hour spent.

The audit I should have built earlier

I run about seventeen tiny macOS utilities. They sit in the menu bar and they do their thing and I largely forget they exist — which is, by design, exactly how they’re supposed to work. ClipMan watches the clipboard. ActiveSpace shows my current space. QuitProtect intercepts accidental quits. RainbowApple draws a stripey Apple logo over the Apple in the menu bar — because life is short. They’re invisible infrastructure.

The problem with invisible infrastructure is that you stop checking it. You assume it’s running. You assume it’s running from the right place. You assume the version installed locally is the version you released to GitHub, and that the version you released to GitHub is the version that’s in your repository, and that all of those are in agreement with each other. You assume things are consistent, because why wouldn’t they be? You’re the only person touching them.

The Spotlight thing was the moment I noticed that several of those assumptions weren’t actually being verified by anyone. My pipeline had been producing releases for months, but nothing in the system was checking the releases afterwards. I was solo developer, solo reviewer, solo QA, solo ops. The checks I forgot to write were the checks that didn’t happen.

So I built a system audit. The first version was a Sunday afternoon’s work. I added a button to Release Manager’s toolbar. It opens a table with one row per app and three columns: version, path, source. Each cell is green, red, or amber. The whole table fits on one screen. The audit completes in about four seconds for the whole catalogue.

The three checks each answer a different question, and together they cover the dimensions of deployment consistency I cared about.

Version: is what I have what I shipped? The installed app has a CFBundleShortVersionString stamped in its Info.plist. The Release Manager catalogue has the version of the latest GitHub release. If the two match, green. If they don’t, red — with both numbers shown, so the direction of the mismatch tells me which kind of problem I’m looking at.

Path: is it running from where it should be? This is where ps came in. ps -eo pid,args returns one line per process with the full path to the executable. The audit captures the output, finds processes whose path contains the app’s product name, and checks whether the path begins with /Applications/. If yes, green. If no, the audit categorises where it actually is — AppTranslocation, DerivedData, the source tree’s build output, somewhere unexpected.

Source: is the repository in sync with the release? A git tag --sort=-v:refname finds the highest semantic-version tag, then a commit count between that tag and HEAD tells me whether there’s unreleased work sitting in the repo. Zero commits ahead is green. Anything else is amber: a reminder to release.

The whole audit engine is about 190 lines of Swift, shells out to four commands (ps, git, gh, PlistBuddy), uses no frameworks beyond Foundation, makes one network request (the GitHub API call to refresh the release-version cache). It’s the smallest thing I’ve added to Release Manager in months, and it might be the most useful.

What the first run found

The very first time I ran the audit, three things were wrong.

Release Manager itself showed N/A for the path check, even though I was obviously running it. After a few minutes of thinking I’d coded the path check incorrectly, I realised it was actually working perfectly — my naming was off. The audit was searching for JorvikReleaseManager.app (the build name) in the process paths, but the installed bundle is Jorvik Release Manager.app with spaces (the install name). String.contains() returned false, so the search couldn’t find its own host process. A correct negative from incorrect assumptions. An audit that finds its own bugs has a certain charm; I fixed the lookup to consider both names and moved on.

Notes Editor showed Running from AppTranslocation. I’d been running it for weeks, editing and deploying blog posts, with no indication that anything was wrong. The Dock icon showed the right name. The About window showed the right version. The app itself had no idea it had been silently relocated to a randomised directory deep inside /private/var/folders/ by macOS’s anti-tampering machinery. ps knew. None of the rest of my workflow did.

I’d installed Notes Editor by downloading the zip from GitHub in a browser, extracting it, and dragging it to /Applications. The browser had attached com.apple.quarantine to the download. macOS’s App Translocation feature had silently relocated the app on first launch. Every subsequent launch had been finding the translocated copy. The version in /Applications/Jorvik Notes Editor.app was, in some technical sense, not the version I’d been running.

This is the kind of finding that makes you question everything you thought you knew about your own machine. The app is in /Applications. You launched it from /Applications. But it’s not running from /Applications. macOS performed a silent redirect, and the only way to know is to ask the process table.

The third finding was a small but real bug in my source check. I’d originally implemented the “latest tag” lookup with git describe --tags --abbrev=0, which sorts by commit ancestry rather than by semantic version. On a couple of repos where I’d cherry-picked commits between tags, the nearest tag by graph distance was an older release than the highest tag by version number. The check was answering a slightly different question than the one I was asking. I rewrote it to use git tag --sort=-v:refname | head -n 1 and the answers became right.

Three checks, three problems, on the very first run. The audit paid for itself before I’d finished writing this paragraph.

And then the disk

If the apps were in disagreement with the catalogue, what else was? I ran a one-line mdfind query against my whole machine:

mdfind 'kMDItemCFBundleIdentifier == "cc.jorviksoftware.*"'

The output was longer than I’d expected. Forty-something .app bundles whose identifiers started with cc.jorviksoftware., scattered across:

• /Applications/ — the canonical install for each app, fine.
• ~/Desktop/Jorvik Software/<App>/ — live build outputs from every ./build.sh I’d ever run, fine.
• ~/Desktop/Jorvik Software/<App>/_BuildOutput/ — Release Manager intermediate builds, fine.
• And — less fine —
• ~/Library/Mobile Documents/com~apple~CloudDocs/Desktop/Jorvik Software/ — an iCloud Drive clone of the entire source tree, weighing in at 4.2 GB. I’d once briefly enabled Apple’s “Sync Desktop & Documents to iCloud” feature, then disabled it, and the OS had left behind a phantom copy of every file that had been synced at the moment of disable. The cleanup never quite happened.
• ~/backups/Desktop/Jorvik Software/ — a separate, older 4.2 GB backup, dating to early April. This one I genuinely don’t remember making. It contains apps with names that no longer exist — a long-defunct BrowserMCP, a similarly defunct BrowserMarker, a deprecated WindowRecall that was superseded by SpaceMan a few weeks ago. Some kind of system snapshot from before that consolidation, presumably.
• A handful of stray Xcode build directories: ActiveSpace/build/, ActiveSpace/_DebugBuild/, CalendarUpcoming/build/, Notes Editor/_build/. Total combined: 1.27 GB. Build artefacts from earlier build setups that don’t get touched by anything any more.

So the situation Spotlight had been facing wasn’t “two ScreenLock bundles.” It was “five copies of every Jorvik app, two-thirds of them old, all of them indexed, and a heuristic algorithm trying to pick one.” The wonder isn’t that it occasionally picked the wrong one. The wonder is that it ever picked the right one.

The Spotlight cache trap

I dropped a .metadata_never_index marker into the source tree. macOS supports this convention for any directory you want Spotlight to ignore. Empty file, unambiguous semantics, takes about a second to create:

touch "/Users/jonathanhollin/Desktop/Jorvik Software/.metadata_never_index"

Then I deleted the iCloud clone, the ~/backups/ tree, and the four stray build directories. Total reclaimed: about 9.6 gigabytes. Not enormous in modern terms — a single Xcode install is bigger — but the amount wasn’t the point. The point was that none of those gigabytes were doing any work. They were silently confusing search results, populating duplicate matches, and (in the iCloud case) forcing me to reason about a parallel-universe copy of every file I edited.

I tested Spotlight again. The wrong copy of MouseCatcher was still being returned.

This was the bit I learned the hard way. .metadata_never_index stops future indexing. It does not retroactively flush the cache. macOS still knew about MouseCatcher.app because it had indexed the file sometime last week, before the marker existed; the marker tells the indexer “don’t visit this path again,” but the entry already in the index just sits there. Cached entries normally age out as the indexer revisits the volume — but for a directory under a .metadata_never_index marker, the indexer doesn’t revisit. So the cached entries can persist indefinitely.

This produced a fairly perfect bit of self-trolling. I’d marked the directory. I’d deleted the dead trees. I’d stripped 9.6 GB of files I shouldn’t have had. The world was tidier than it had ever been. And Spotlight was lying about it.

The fix is, as Apple-fix things tend to be, hidden in plain sight: System Settings → Spotlight → Privacy. Drag a folder into that pane. macOS treats the addition as “immediately drop everything you have for paths under here.” This is materially different behaviour from the marker file — Privacy is an active flush, the marker is a passive don’t-index instruction. You can use both together: drag the source tree into Privacy, watch the cache get flushed within seconds, leave it there or remove it again afterwards (the marker keeps it from being re-indexed regardless). I went with leave-it-in-Privacy — belt and braces, plus a permanent indication in System Settings that this path is intentionally excluded.

After all of that, mdfind 'kMDItemCFBundleIdentifier == "cc.jorviksoftware.*"' returned exactly one result per app: the canonical install in /Applications/. Spotlight launches the right app every time, because there is no wrong app on the system any more.

The other strands

While the audit was teaching me things, the rest of the fortnight kept happening alongside it. I want to mention the work briefly because each of these strands fed into the same arc: making the estate easier to live in.

Release Manager itself got rebuilt — the part of the codebase that was the audit’s sibling rather than its subject. The 1,600-line Swift pipeline that built, signed, notarised, and packaged every Jorvik app became a 770-line dispatcher around a shared Make include. The build/sign/notarise/staple/package work moved out into shell, where every tool involved natively lives, and the Swift app kept the pieces that genuinely benefit from being Swift. That migration alone was ten days’ work, but it’s its own post.

A handful of long-standing user feature requests landed during the same window. The Web Editor’s file browser learned to refresh on focus, so files added in another tool stop requiring an editor restart. The Daily News reader gained a per-feed health pill (green / amber / red) and a real OPML import-time dedup, both of which were necessary to manage a 300-plus-feed collection without losing your mind. Release Manager’s Prod-status indicator stopped lying when the source had been pushed to GitHub but not actually deployed to Cloudflare Pages. The Web Editor’s commit dialog stopped having a single-line text field with no visible cursor (a small bug that I had been silently working around for six weeks while telling myself I’d fix it next time).

Two new product pages went up on jorviksoftware.cc — one for Daily News, one for Reverie — and a new top-level “Apps” section was added to the navigation, with the homepage and every static page updated, the build script updated to propagate the change to every regenerated note page, the sitemap updated, the Cloudflare deploy refreshed. About sixty files touched in one commit, and not a single visual regression on the homepage.

I rewrote a clutch of stale KB documents, deleted three pieces of memory that were no longer accurate, and added two new conventions (one for keyboard-shortcut style on the website, one for catalogue/Makefile drift in the build pipeline). The KB grew. The misinformation in it shrank.

Each of those strands looked like its own thing while it was happening. Looking back from this end of the fortnight, they were all the same thing: every place where the estate was a bit out of square got squared up.

The principle

The audit, the cleanup, the RM rebuild, the feature requests, the KB hygiene — if there’s a single thread tying them together, it’s this: trust, but verify, and make verification cheap enough that you actually do it.

I trust my pipeline. I built it. I know what it does. But trust without verification is faith, and faith is a poor foundation for engineering. The audit exists so that I can trust the pipeline and confirm that my trust is justified, routinely, without effort. Four seconds and one button is cheap enough.

The same principle applied to the disk. I trusted that /Applications was canonical. mdfind verified that it wasn’t, because the iCloud clone, the backups directory, and the build dirs were all populating the same answer in different shapes. I trusted that Spotlight reflected reality. The cache verified that it didn’t, until I forced it to. Each of these was an assumption I’d held for months without ever testing — and each of them turned out to be wrong in some interesting way.

The same principle applied to the Release Manager rebuild. I trusted that putting the build pipeline inside a Swift host app was the right shape, because Swift is what I write Mac apps in. The audit-style framing of “but does the structure match the work?” revealed that the answer was no — the build pipeline was shell-shaped work, and putting it in a Swift host had been adding one bug per new project type for over a year. Verification told me what habit had been hiding.

I think this is the lesson of the fortnight, more than any of the individual cleanups. The estate runs better when the assumptions underneath it are routinely checked. Most of the time the checks come back green and you proceed. Occasionally one comes back red, and you find a thing that’s been quietly wrong for weeks — possibly months — and that you’d never have found through normal use because it was nowhere your normal use looked.

A small confession

The pleasure of finishing this fortnight isn’t the disk space, although the disk space is nice. It isn’t even the RM line count, although that’s also nice. The pleasure is the correlation between the system as I understand it and the system as it actually is.

After the cleanup, when I ask “where is ScreenLock,” there is one answer. Before, there were five. Five is too many. One is the right number. After the audit, when I ask “is the version I’m running the version I shipped,” the table shows me green for every app and I believe the green. After the RM rebuild, when I ask “why did this build behave this way,” the answer lives in 430 readable lines of release.mk rather than 1,600 lines of Swift across thirteen interlocking pipeline stages.

Anyone who’s spent time in a kitchen knows the feeling. Half the joy of a clean countertop isn’t the cleanliness; it’s that you can put a thing down without first having to move three other things out of the way. The countertop is in correspondence with itself.

A clean filesystem is a clean countertop. A clean catalogue is a clean drawer. A clean release pipeline is a clean cooker hood. None of it is glamorous, but if you’ve ever sat down to start work and realised that the workspace itself is in your way, you’ll know the feeling I mean. Today, mine isn’t. Tomorrow I get to start something new on a workspace that won’t fight me when I do.

Two weeks of housekeeping, paid for by the small dignity of asking my own tools to be honest with me about themselves. I’d do it again. I will do it again, periodically, because that’s the deal. Estates don’t stay tidy on their own.

But not tomorrow. Tomorrow, I think, I’m going to build something.

Photo by Oleg Solodkov on Unsplash

I wrote Release Manager because I needed something to build, sign, notarise, package, and ship every Jorvik app from one window. I wrote it in Swift because Swift is what I write Mac apps in, and Release Manager is a Mac app. I wrote it as one big pipeline because pipelines are sequential and Swift is good at sequential. By the time it was working end-to-end it was about a thousand lines long, and I felt entirely justified.

A year and change later it was 1,600 lines and I wasn’t justified anymore.

I want to be careful about how I describe what changed, because it’s tempting to write this as “the old code was bad and I made it good,” and that isn’t honest. The old code was fine. It worked. It shipped real software for a year. The thing that changed is that I came to understand which parts of the job belonged in Swift and which parts I had only put there because Swift was the language I happened to be holding.

How the pipeline got fat

The Release Manager pipeline started simple. Eleven stages, sequenced in order: preflight checks, build, verify the build, sign the bundle, verify the signature, submit to Apple’s notary service, staple the ticket, verify notarisation, package as .zip (or .pkg, for things like the screen savers), sign the zip with Sparkle’s EdDSA key, push to GitHub. Each stage was a Swift function. They called Process with a list of arguments, captured stdout via Pipe, parsed the result, and either passed or failed.

This was clean architecture for the original suite, which was almost entirely menu-bar utilities built with one of two patterns. xcodebuild for the apps that lived in Xcode projects, swift build for the ones using Swift Package Manager. The pipeline branched on buildSystem at one point, ran the right shell-out, and continued.

Then I started adding apps that didn’t fit the pattern.

The first wobble was apps that were neither full Xcode projects nor SPM packages — little single-file utilities I’d written with a direct swiftc invocation in a build.sh. Adding swiftc as a third build mode meant a new branch in the build stage. Then I started embedding Sparkle.framework for auto-update, which meant the sign stage had to walk the framework’s nested code in dependency order — XPC services, the updater app, the framework binary itself — and codesign each leaf before sealing the outer bundle. That’s a recursive shell helper in any sensible world. In Release Manager it became a hundred lines of Swift that walked Contents/Frameworks/ with file enumerators.

Then I added a screen saver. ASCII Saver isn’t a single bundle — it’s a .saver plus a helper .app that handles camera access, distributed as a multi-component installer. That meant the package stage had to know about productbuild, Distribution.xml, multiple inner packages combined into an outer package, with the helper pre-signed differently from the main bundle. More Swift, more branches, more hardcoded if app.id == "ASCIISaver" paths I told myself I’d clean up later.

Then Reverie came along. Reverie is a screensaver too — a meditative roulette-curve thing that I’d been wanting to build for ages — and on its first release through Release Manager it surfaced six distinct bugs in five distinct places.

The Reverie bugs

I want to walk through these because they’re what convinced me. Each one, looked at in isolation, was a small thing. Looked at together, they were a pattern.

The build stage for swiftc apps was missing -emit-library for .saver bundles. (Screen savers are dylibs, not executables, because legacyScreenSaver loads them.) The package stage had a hard-coded reference to ASCIISaver-Installer.pkg in the asset upload path that I’d forgotten about. The install location was hard-coded to /Applications even for .saver bundles, which actually go to /Library/Screen Savers. The swiftc source-discovery method had a wildcard that didn’t recurse sub-directories, missing Reverie’s Sources/ layout. Process’s FileHandle.nullDevice for stdin wasn’t actually propagating to grandchild processes when I shelled out via a wrapper script, causing notarytool to hang waiting for input. And the inner .saver inside the produced pkg was being signed with the ad-hoc certificate by the first nested build, then the outer pkg was getting Developer ID Installer signing — so the package signature was right but the bundle inside it was wrong, and the user’s install would fail Gatekeeper.

I sat with that list for a while. None of these were architecture problems. They were details — little factual things about how codesign and notarytool and pkgbuild actually work, accumulated as Swift conditionals because every time I’d met one I’d added a branch. But the cumulative weight was an architecture problem. The reason these bugs kept appearing wasn’t that I was a careless coder. It was that I was reimplementing, in Swift, a domain that already had a perfectly good native vocabulary.

Shell tools belong in shell

Here’s the thing I should have admitted years earlier: codesign and xcrun notarytool and pkgbuild and ditto and stapler are shell tools. Their inputs and outputs are designed for a shell. Their stdin handling is designed for a shell. Their exit codes are designed for a shell. Their timeout semantics, their environment variable conventions, their output formats — all of it assumes you’re calling them from a shell, not from a process spawning library inside a host language.

Calling them from Swift via Process/Pipe isn’t wrong, exactly. It works. But it’s a layer of indirection between the tool and the natural way to use the tool, and every layer of indirection is a place where bugs can live. The stdin-not-propagating-to-grandchildren bug, in particular, isn’t something a shell user would ever even meet. They’d redirect stdin from /dev/null once at the top of the script and the matter would be settled. In Swift, I’d been carefully constructing FileHandle.nullDevice objects and passing them as standardInput, which works for the immediate child but doesn’t inherit the way an honest < /dev/null redirect would, and Apple’s notarytool happens to launch a daemon that needs to inherit a real stdin descriptor or it hangs forever. I’d burned a literal day on that one.

There’s a version of this argument that goes “use the right tool for the job, ya numpty” and feels obvious in retrospect. There’s another version that’s subtler and worth dwelling on: I’d been treating “Swift is the native macOS language” as if it meant “Swift is the right tool for everything you do on macOS.” Those aren’t the same statement. Swift is wonderful for building the user-facing app — the window, the buttons, the catalogue, the audit reports, the settings. It is not particularly suited to orchestrating a sequence of shell-shaped tasks where every task already has a battle-tested shell idiom. I had been using it for both because it was the language I’d started in.

The split

Once I’d framed the problem that way, the design wrote itself.

Release Manager would stay a Swift app. It would keep the user interface, the catalogue of apps and their configurations, the preflight checks (which need consistent reporting in the UI), the verification stages (which earn their keep precisely by being independent of the build), the EdDSA signing of the produced zip (which yields structured metadata that goes back into the catalogue), and the GitHub release upload. All of that is real Swift work, with state and UI and structured outputs that benefit from a real type system.

The build, signing, notarisation, stapling, and packaging would move out. Out into a Make include — one shared file called release.mk — that every project in the suite would include from its own minimal Makefile. The project Makefile would declare identity (bundle name, build system, frameworks, entitlements, embedded frameworks like Sparkle) and that’s it. release.mk would do the work, in shell, where every tool involved natively lives.

This was a non-trivial commitment. I had twenty-three apps in the catalogue. Each would need a Makefile. The shared release.mk would need to handle three build systems, single-target and multi-target installers, with-and-without embedded Sparkle, optional install-name renaming (JorvikReleaseManager.app → Jorvik Release Manager.app at install time, that kind of thing), alsoShipPkg dual-shipping, helper apps with their own entitlements. None of that complexity was new — it all already existed, in Release Manager, in Swift — but I’d be retranslating it to shell. With migration mistakes likely.

So I phased it. Phase 1: build the shared infrastructure with Reverie as the test subject — the simplest case, single-target, no embedded frameworks, no install-name rename. If release.mk could ship Reverie cleanly through the terminal end-to-end — produce a signed, notarised, stapled .pkg — the foundation was sound.

Phase 1.5: validate against MenuTidy. MenuTidy is a swiftc app with embedded Sparkle and alsoShipPkg-driven dual-ship. It was the next-hardest case, and I deliberately put it before any Release Manager wiring. The Sparkle leaves-first signing recursion is the part of the recipe with the most opinionated detail; if it didn’t work for MenuTidy there was no point continuing. I ran it in shadow-mode — the existing Swift pipeline in Release Manager and the new gmake release target, side by side — and diff’d the produced bundles modulo timestamps and signature randomness. They matched. That was the moment I knew the rest was just typing.

Phase 2: add the dispatcher to Release Manager, gate it on a per-app boolean. Apps with the flag use the new path; everything else stays on the legacy Swift code, untouched. This let me migrate one app at a time without holding the entire suite’s release cadence hostage to the rewrite.

Phase 3: roll through the suite. Twelve menu-bar utilities first, then the news reader, then the calendar app, then the Xcode-based internal tools, then ASCII Saver as the final boss. Each migration took thirty minutes and surfaced precisely zero new bugs in release.mk after MenuTidy. That itself was a quiet vindication: the cases I’d been adding hardcoded Swift branches for had all been varieties of the same handful of orthogonal questions (build system × framework embedding × package format × multi-target). Once those were composable variables in a shared file, nothing was special anymore.

ASCII Saver did need new shape in release.mk, because its multi-component productbuild flow with the camera-agent helper had no analogue in the simpler cases. I added a HELPER_TARGETS variable that’s a list of colon-delimited records (one per helper: target name, product name, entitlements file, package identifier, package filename) and let the Make include loop over them in build, stamp, sign, notarise, staple, and pkgbuild. That was the only real extension. The fact that I needed to add it for one app and zero others did make me wonder, briefly, whether ASCII Saver was just structurally weird — but the answer is that screen savers with helpers are a real pattern (any future saver that needs camera or microphone access will need the same shape), and the variable now exists for the next one.

Phase 4: delete the legacy Swift code. This is the part I’d been looking forward to.

The number

Phase 4 took out roughly 1,100 lines from PipelineEngine.swift — buildXcode, buildSPM, buildSwiftc, buildMake, the entire executeSign framework-recursion loop, executeNotarise, executeStaple, executePackage, packageZip, packagePkg, buildSingleAppPkg, the shared notariseAndStaple helper that had been factored out at one point. Plus the orphaned helpers that had only ever been called from those (bundleInstallRoot, SwiftcSourceResolution, the swiftc source drift detector). And then a follow-up pass took out the catalogue fields the Swift code had been the only consumer of (xcodeProject, xcodeScheme, xcodeTarget, swiftcSourceFiles, swiftcFrameworks) along with the catalogue editor sections that used them.

Release Manager went from about 1,600 lines of pipeline code to about 770. The shared release.mk is around 430 lines. The per-project Makefiles are 15 to 30 lines each. Net: less code, more capability.

But honestly the line count isn’t the part I care about. The part I care about is what kind of code it is.

The code that’s left in Release Manager is the code that earns its keep by being Swift. The catalogue is a typed model with structured persistence. The verification stages run independent inspections of the produced artefacts and catch lies the build path might tell — if release.mk somehow shipped a bundle with the wrong bundle ID, Verify Build would reject it before anything got pushed to GitHub. The EdDSA signing produces structured metadata that flows back into the catalogue, where the appcast generator reads it. The release stage prompts the user to confirm GitHub repo creation if needed, integrates with gh’s output for asset uploads, writes back to the catalogue. All of that benefits from a real type system, async/await, and SwiftUI. None of it would be better in shell.

The code that left is the code that was always shell-shaped. It’s now in a place where it can use shell idioms freely. set -eu -o pipefail. .DELETE_ON_ERROR. Quoting paths once, at the recipe level, instead of escaping them inside Swift string interpolations. Real < /dev/null redirects that work the way they’re documented to work. for FW in $(EMBEDDED_FRAMEWORKS); do ... done instead of a SwiftUI-style enumerator over a Sequence<String>.

It feels appropriate, in a way that’s hard to describe without sounding mystical about it. The right tool for the job, sitting in the place where it’s most natural to read.

The bigger structural win

The line-count thing is satisfying. The structural thing is more important.

When I find a bug or an edge case in release.mk now, I fix it in release.mk, push, and it’s live across all twenty-three apps on the next build. No Release Manager rebuild. No notarisation. No reinstall. No fan-out to twenty-three repositories. One commit to the shared Make include, and every project benefits.

This sounds obvious when stated. In the old monolithic-Swift architecture, every release-pipeline fix required a Release Manager rebuild and reinstall, because the fix lived inside the Mac app. If the fix was the kind of thing that surfaces during a release attempt — which most are — you’d be in the awkward position of trying to ship a fixed Release Manager with the broken Release Manager. I’d become accustomed to the dance: notice the bug, fix it, ship a Release Manager point release, install it, retry the original release. Half my release-related bugs took a multi-rebuild loop to land.

That’s gone now. I felt the shape of the change most acutely when I was migrating ASCII Saver and discovered four separate edge cases in release.mk — nested helper signing, bare Mach-O signing for ActiveSpace’s switch_helper, stale _BuildOutput cleanup, install-name copy-not-rename. All four were release.mk patches, pushed within fifteen minutes of each other. None of them required Release Manager to be touched. They just worked, on the next build, for every app at once.

I think this is the structural lesson of the whole exercise. Not “Swift is the wrong tool for orchestration,” though I do believe that. The deeper one: give the rapidly-iterating part of a system the freedom to iterate. The build pipeline is the part of any release toolchain that picks up the most edge cases over time, because every new app you add brings new edge cases. Putting it inside the Mac app you ship through that very pipeline created an iteration loop that was at minimum a Release Manager rebuild long. Putting it in a Make include cloned alongside every project shrunk that loop to whatever git push takes.

What I should have known sooner

I think I would have arrived here faster if I’d been less attached to the idea of Release Manager as “a Mac app.” The user-facing parts — the catalogue browser, the per-app status, the verify stages, the audit dashboard, the Build & Release / Finalise two-button workflow — absolutely are a Mac app. The pipeline plumbing isn’t. It just lived inside the Mac app because it had nowhere else to go, and once it was there, it was easier to keep adding to it than to extract it.

The temptation to keep adding to a monolith is strong, especially when the monolith is yours. Every new branch you add feels like progress — another case handled, another app supported — even when each branch is making the whole structure more brittle. The signal that you’ve crossed the line isn’t any single bug; it’s the pattern of bugs. If the same kind of bug keeps coming up in different shapes, your abstraction is wrong.

Six bugs in one Reverie release was that pattern. It just took me a while to recognise it as a pattern rather than as bad luck.

What’s left

The pipeline ships every app in the suite cleanly. Release Manager is smaller, simpler, and visibly does less. The shared release.mk does most of the actual work and lives in a sibling repository — PerpetualBeta/jorvik-release, public, open source, available to anyone whose Mac app distribution flow has the same shape as mine. I’m honestly not expecting many takers; the audience for “a shared Make include for orchestrating macOS code signing and notarisation” is small. But it’s there. And when I add the next Jorvik app, its release pipeline will be a fifteen-line file that says “here’s my identity, please ship me,” and the rest will happen automatically, in shell, where it always belonged.

Sometimes the most useful thing you can do for a piece of software is give some of its responsibility to a different piece of software, written in a language better suited to that responsibility. The total amount of work being done is the same. The amount being done well goes up.

That Damn Notch!

I’d filed MenuTidy as “done.” That’s an embarrassing thing to admit about your own app, but it’s the truth. It’s a tiny utility — you click a chevron in the menu bar and the third-party icons to its left collapse out of sight; click again, they come back. It does that one job, it does it well (or so I thought), it’s been shipping for months without complaints. So in my head it sat in a folder marked “maintenance only,” and I’d been quietly working on shinier things instead.

Today I went back to it because of a feature I’d been postponing.

If you have a MacBook Pro with a notch — any 14” or 16”, plus the notched Airs — you’ve probably noticed that when you accumulate enough menu bar icons, the leftmost ones don’t just get squeezed; they vanish. The notch sits in the middle of the menu bar, and macOS treats it as an exclusion zone. Status items live to the right of it, growing leftward as more apps add their icons. When the queue gets too long, the items at the front of the line stop being rendered. They’re still there in the system — the apps still own them — but you can’t see them, and you can’t click them. They’re behind the notch in every functional sense.

Bartender users have been able to deal with this since the very first notched Mac shipped. I haven’t. The MenuTidy approach — collapse the entire row of third-party icons behind a chevron — sidesteps the problem rather than solving it: if your icons are collapsed, none of them are visible, so the notch doesn’t matter. But that’s not always what you want. Sometimes you specifically want certain icons available, and you’ve carefully arranged them to be the right of the spacer (always visible), and the notch then chooses one or two of those favourites to eat anyway.

So today: I added a feature called Reveal Hidden Icons. Right-click MenuTidy’s chevron, choose the menu item, get a little floating panel listing every status icon that’s currently behind the notch. Left-click an entry, the corresponding app behaves as if you’d clicked its icon directly. Right-click, it behaves as if you’d right-clicked. That was the design.

The implementation took rather longer than the design suggested it should.

What the notch actually is, technically

I want to spend a moment on the geometry, because I had a wrong mental model for most of the morning.

I’d been thinking of the notch as a visual clip — the menu bar extends across the whole screen, and the notch is just a black rectangle drawn on top, hiding whatever’s behind it. If that were true, you could click in the notch area and the click would still land on the icon underneath; it just wouldn’t be visually obvious where the cursor was.

That isn’t how it works. The notch is a physical hole in the screen — that’s why it exists, the camera and Face ID hardware sit in there — and macOS knows it. The system menu bar is laid out around the notch, with two distinct rectangular regions, one to its left and one to its right. NSScreen exposes them as auxiliaryTopLeftArea and auxiliaryTopRightArea. The space between them is the notch, and the menu bar isn’t there in any meaningful sense. There’s no menu bar pixel to render onto. There’s no menu bar event-handler to receive clicks. It’s a gap.

When status items overflow the right region, macOS doesn’t reflow them into the left region or scroll them or compress them — it just stops rendering them. The AX tree still includes them, and they still report a frame, but the frame they report is the position they would occupy if the menu bar continued through the notch — which it doesn’t. So an item that’s “behind the notch” reports an X coordinate inside the notch’s horizontal range, where there’s nothing but air.

I figured this out the slow way.

The first attempt: AXPress works, then doesn’t

The Accessibility API can enumerate every running app’s status items via AXExtrasMenuBar, an attribute on each application’s AX element that returns a kind of meta-menu-bar containing exactly that app’s status items. Walking NSWorkspace.runningApplications and asking each for its AXExtrasMenuBar children gave me, on a typical run, around forty status items across thirty apps. I filtered them to ones whose frame X-centre fell inside the notch range, which gave me four: the icons currently being eaten.

Showing them in a panel was easy. Activating them was the hard part.

For the first attempt I used AXUIElementPerformAction with kAXPressAction — the canonical “simulate a click on this element” call. AX bypasses the normal hit-testing path and goes straight to the receiving app’s event handlers, which is exactly what I needed. I tested with Browser Notes, which had been getting eaten by my notch all week.

The menu opened.

I moved my cursor toward it.

The menu closed.

That happened reliably. Click the row in MenuTidy’s panel, BrowserNotes’ menu would pop into view at the icon’s logical position, and the moment I started moving the cursor toward the menu, the menu would dismiss as if I’d clicked outside it.

I knew immediately what was probably happening, because I’d seen this once before with a different app. NSStatusItem-attached menus track the cursor: when the menu opens, it reads the current cursor position and starts watching for movement. If the cursor is far from the icon when the menu opens (because the user clicked some panel mid-screen, say), the very first mouseMoved event reads as “moved away from the icon, dismiss.” The menu’s tracking model assumes you’re drag-selecting from the icon; if you’re not, the model decides you’re leaving.

The fix should have been to warp the cursor onto the icon’s position before the AXPress call, so the menu’s tracking model would see a consistent origin. CGWarpMouseCursorPosition takes a point and moves the system cursor there. I added a pre-warp.

The menu still closed.

The CGEvent detour

Now I was less confident in my mental model. If pre-warping didn’t fix it, maybe AXPress was opening the menu in some weird half-tracking mode that any subsequent mouse-move would dismiss regardless. So I tried a fundamentally different approach: synthesise a real mouse-down + mouse-up pair via CGEvent, posted at the icon’s frame centre. That should make the click look exactly like a real user click — cursor warps to the click position naturally, mouse-down fires, mouse-up fires, status item button receives the standard event sequence, menu opens in proper click-and-stay mode.

I removed the AXPress call, swapped in CGEvent, rebuilt, tested.

The cursor warped.

No menu appeared.

This was, briefly, baffling. The CGEvent click was definitely being posted — the cursor jump was visible — but the icon wasn’t responding. After a couple of minutes of staring, I realised what should have been obvious from the start: the icon’s frame is behind the notch, and the click is being posted at coordinates inside the notch. The CGEvent system doesn’t care that I think there should be a status item there. It posts the event into the global event stream at the given coordinate; macOS’s window-server hit-tests that coordinate against rendered windows; nothing renders there; the event goes nowhere.

The notch is a hardware clip. CGEvent is a software click. They don’t meet.

Why AX worked when CGEvent didn’t

This was the moment the geometry clicked into place properly. AX isn’t just a fancier version of CGEvent — it’s a fundamentally different interaction model. CGEvent posts events into the OS’s event stream, where they’re dispatched by hit-testing against windows. AX talks directly to the application’s accessibility hierarchy, asking the app to perform an action on a specific element by reference, with no hit-testing involved. AXPress on an element doesn’t need the element to be on-screen, or visible, or even unobscured. It just asks the app to behave as if its primary action had been triggered.

That’s why my first attempt worked — the menu opened — and that’s why the CGEvent attempt couldn’t. Behind the notch, CGEvent has nothing to hit. AX bypasses the entire question.

So the right answer was AXPress, plus — I returned to my pre-warp theory, but more carefully. Maybe my earlier pre-warp hadn’t worked because I’d combined it with a post-warp: I’d been warping the cursor onto the icon, calling AXPress, then warping the cursor below the menu bar onto the freshly-opened menu. I’d been assuming both warps would help. What if the second warp was the thing dismissing the menu? Cursor warping generates a mouseMoved event; what if that event — happening 60 milliseconds after the menu opened — was the very thing the menu’s tracking interpreted as “user moved off the icon”?

I dropped the post-warp. Just AXPress, with the cursor pre-warped to the icon’s position.

The menu opened. I physically moved the mouse downward. The cursor — which was warped to the icon position, behind the notch, invisible to me — moved with my physical input, descending out from below the notch onto the menu’s drop area. The menu tracked normally. I clicked “Settings…”.

It opened.

I sat there for a moment, slightly dazed by how thoroughly the simpler version had been the right answer all along.

The right-click case

Right-clicks have a different complication. AX doesn’t have a standard “right-press” action; AXPress always simulates a primary click. For apps that distinguish left and right click (Jorvik apps sometimes do — left opens a popover, right shows the menu), I needed a way to fire a right-click specifically.

For right-clicks I fall back to CGEvent — rightMouseDown + rightMouseUp at the icon’s frame centre — with the same caveat as before: if the icon is currently behind the notch, the click goes into the notch’s coordinate space and finds nothing. For visible icons elsewhere on the menu bar, it works perfectly. For behind-notch icons, right-click won’t register without AX support. That’s a documented limitation of the feature, and an honest one: I can’t reach behind the notch for right-click without AX cooperation that doesn’t exist as a standard interface.

In practice this matters less than you’d think, because most apps use left-click to open their menu, with right-click as a redundant alternative. If you’ve got an app that only responds to right-click on the icon, you’ll need to wait for it to drift out from behind the notch by quitting something else. I’m not aware of any such app, but I won’t pretend they don’t exist.

Making it feel instant

The first version of the reveal panel was correct but sluggish. Every time you opened it, MenuTidy walked all forty-or-so running apps, asked each for its AXExtrasMenuBar, walked the children, computed frames, filtered to the notch range. That took roughly half a second on a quiet system; with a busier process list and a few apps that were slow to respond to AX queries, longer.

Half a second isn’t catastrophic, but it doesn’t feel right for a panel that’s meant to drop down instantly when you click a menu item. So I added a live cache. The cache populates on launch, refreshes whenever NSWorkspace fires didLaunchApplicationNotification or didTerminateApplicationNotification (with a small delay so the launching app has time to actually create its status item), and gets read instantly when the panel opens. There’s a background refresh on every panel open too, just in case something drifted between events — the panel doesn’t wait for that, but the next open will reflect any changes.

The result is that opening the reveal panel feels responsive. Click the menu item; it’s already there. Which, for a feature you might use a dozen times a day, is the difference between “tolerable” and “feels native.”

And, while we’re here, the position-memory bug

This part is much shorter, mostly because the bug was much smaller, but I want to mention it because it’s the kind of thing you only notice when you’ve been quietly tolerating it for a long time.

MenuTidy creates two NSStatusItems: a chevron (visible) and an invisible spacer that you can drag around to define which icons get hidden when collapsed. Both items have autosaveName set, which means macOS persists their menu bar positions across launches in the standard NSStatusItem Preferred Position UserDefaults keys. If you command+drag the spacer to a new position, that position should be remembered next time you launch the app. The README has been claiming so since the first release.

The README was lying. Not deliberately — I’d genuinely intended for positions to persist — but the actual code did this in applicationDidFinishLaunching:

UserDefaults.standard.set(150, forKey: "NSStatusItem Preferred Position MenuTidyChevron")
UserDefaults.standard.set(300, forKey: "NSStatusItem Preferred Position MenuTidySpacer")

Setting the autosave keys, on every launch, to fixed values, before the NSStatusItems were created and could read them. Whatever the user had dragged the spacer to last session was overwritten with 300 before macOS got a chance to use it. The spacer would dutifully appear at position 300 every time, and the user’s carefully-arranged divider would silently reset, week after week.

The fix is a one-shot flag:

if !UserDefaults.standard.bool(forKey: didSeedDefaultPositionsKey) {
    UserDefaults.standard.set(150, forKey: "NSStatusItem Preferred Position MenuTidyChevron")
    UserDefaults.standard.set(300, forKey: "NSStatusItem Preferred Position MenuTidySpacer")
    UserDefaults.standard.set(true, forKey: didSeedDefaultPositionsKey)
}

Seed the initial positions once, on the first ever launch, then never touch the keys again. Autosave handles the rest. The README isn’t lying anymore.

I’m a little embarrassed this had been wrong since the first release. Nobody had reported it as a bug, presumably because the symptom — “the spacer keeps reverting to where it always was” — reads, to a casual user, as just how the app works. They were dragging it back into position every Monday and treating that as part of the experience. That’s not a feature; that’s a tax. I’m glad it’s gone.

What changed today, really

The code change is bounded: a single Swift file, a few hundred lines of new logic, one bug fix that’s not even thirty lines including the comment explaining it. The conceptual change is bigger.

I’d treated MenuTidy as a small, simple utility that did its small simple thing. Today I treated it like an app that ought to meet users where they actually are, which means dealing with the Mac they actually own — the one with the notch. The notch is ugly, both literally and as an engineering problem. It’s easier to pretend it’s not your concern when your app has a different focus. But it absolutely is the user’s concern, every single day, and a tool that lives in the menu bar can’t reasonably ignore the menu bar’s most distinctive feature.

I’d also been treating the position-memory bug as a small thing. It wasn’t. It was the README saying one thing and the app doing another, every launch, for months. The fact that nobody had noticed loudly enough to file an issue isn’t because it wasn’t real; it’s because users had absorbed the cost.

There’s a thing that happens in long-running software where you stop seeing it the way users do. You know how it works, you know its quirks, you mentally route around them, and after a while you’re no longer experiencing the friction. That’s how an app gets filed in your head as “done” while still containing several rough edges that users encounter daily and patiently work around because what else are they going to do. The only real cure is to use your own software the way a stranger would, every now and again, and let the friction surprise you.

MenuTidy 1.3.0 ships today — .pkg and .zip, signed and notarised as always. The reveal feature is opt-in (only appears in the menu when you have a notched display, which I’m happy about because half my readers are on Studio Displays where it would just be visual noise). Position memory works the way the README has always claimed it did. The Settings panel grew a Permissions section so the AX requirement is upfront, not surprising.

I no longer think of MenuTidy as the “also-ran” app in our collection. It’s funny how much of that change was actually about how I was thinking, rather than what the app does.

I shipped one of those bugs across eleven apps yesterday. Then I un-shipped it across nine of them today. Some of you may have caught it. If you didn’t, the relevant detail is that the menu-bar icons in your Jorvik utilities briefly grew an opinionated grey pill background, then went back to looking the way they always had. I owe you the explanation.

The convention, briefly

Every Jorvik menu-bar utility has an optional grey background “pill” that sits behind the status-bar icon. Some users like it — it improves contrast against busy or wallpaper-tinted menu bars, and it gives the icon a discrete bounding box that can be useful in dense bars. Other users prefer the plain glyph. So it’s a setting. Right-click the menu-bar icon, choose Settings, find Show background pill, toggle to taste.

Yesterday I did a big rollout: standardising the pill design across every app in the suite, replacing an older user-coloured variant that didn’t look right against macOS 16’s wallpaper-tinted menu bars. The new pill is fixed grey, drawing-handler-composed, and behaves correctly on every menu-bar background I’ve thrown at it. It’s a clear win.

The KB convention I wrote a few weeks ago, when the new pill design first emerged in ActiveSpace and CalendarUpcoming, said this:

Settings exposes a single “Show background pill” toggle; default ON for fresh installs via UserDefaults.register(defaults:).

I read that line as the design intent and followed it across the eleven apps in the rollout. Each of them gained the line:

UserDefaults.standard.register(defaults: ["menuBarPillEnabled": true])

at the top of applicationDidFinishLaunching. This tells UserDefaults to use true as the value for menuBarPillEnabled when no value has been set explicitly. Fresh installs see the pill turn on by default; users can switch it off if they don’t like it.

That all sounds reasonable. It is, in fact, almost reasonable. The one wrinkle is what fresh install means.

What “fresh install” doesn’t mean

UserDefaults.register(defaults:) is sometimes described in tutorials as “set defaults for new users.” It isn’t. What it actually does is provide a fallback value for any key that has not been explicitly set. The fallback is in-memory; it is consulted by UserDefaults.bool(forKey:) whenever the on-disk preference store has nothing to say about that key.

This is subtly different from “new users.” Specifically, it doesn’t distinguish between:

1. A genuinely fresh install where the user has never run the app before.
2. An existing install where the user has run the app many times — but never explicitly toggled this particular setting.

For the menu-bar pill, almost everyone falls into category 2. The pre-rollout pill code did this:

let enabled = UserDefaults.standard.bool(forKey: "menuBarPillEnabled")
guard enabled else { return }

with no register(defaults:) call. A user who never touched the setting had no value stored on disk. UserDefaults.bool(forKey:) returned false (the default for missing booleans), and the pill stayed off. That’s how it had been, quietly, for as long as the toggle had existed.

When I added register(defaults: ["menuBarPillEnabled": true]) to every app and shipped, every existing user who had never touched the toggle suddenly experienced this on the next launch:

• App reads UserDefaults.bool(forKey: "menuBarPillEnabled").
• No value on disk, but register has provided true as the fallback.
• Function returns true. Pill turns on.

The user had not asked for the pill. The user had not changed any setting. The user had simply opened their utility one day and found that their menu bar icon now had a grey blob behind it. For all they knew, the developer had unilaterally redesigned their app.

And — this is the part that bothered me — they were right.

The thing the convention paper didn’t say

Re-reading our conventions document with this in mind, I notice something. It says “default ON for fresh installs.” It doesn’t say “default ON for fresh installs and not for upgraders who haven’t yet expressed a preference.” It can’t say that, because the implementation it specifies — UserDefaults.register — has no way to distinguish those two cases. There’s no “first launch ever” hook in UserDefaults. There’s no “this app has been run before” flag. There’s just the absence of a key, which two different users can produce for two completely different reasons, and to which the API responds identically.

You could build that distinction yourself. On first launch, write a sentinel like didInitDefaults = true. The next launch checks the sentinel; if absent, treat as fresh and set the user-facing default; if present, leave the absence of menuBarPillEnabled as it was. That works, but it adds a one-shot guard to every app and a small amount of state to every preference store, and it has its own subtleties. (What if the user resets their preferences? What if their preferences file has been lost in an iCloud sync? Are they fresh, or upgrading?)

The simpler answer was waiting all along: don’t change the default. The pre-rollout behaviour of “off until the user toggles it on” was correct in every relevant sense. Users who wanted the pill turned it on — once — and the value was persisted forever. Users who didn’t want it never had to think about it. New users got a clean install with no pill, which is an entirely defensible default for an optional visual decoration.

So I dropped the register line everywhere. Ten commits later (the eleven affected apps minus ScreenLock, where it had already been reverted as part of the original spot-fix), and I updated our conventions doc to say:

Default OFF. Do not register ["menuBarPillEnabled": true]. UserDefaults.bool(forKey:) returns false for missing keys, which is the correct default — the pill is opt-in.

With a brief note explaining why. Default ON via register-defaults silently turned the pill on for upgraders who’d never set the key explicitly, surprising users on every Jorvik app’s update day. Reverted.

The harder question

There’s a slightly uncomfortable question buried inside this: when is it OK to ship a setting as default-ON?

The honest answer is: when the change is genuinely better for everyone, and when users have an obvious way to discover and revert it. Auto-update being on by default is one of those — most users want updates, and the few who don’t can find the toggle in Settings. macOS’s “Open at Login” being off by default is the inverse — most users don’t want background processes piling up, and the few who do can opt in.

The pill failed both halves of that test. It’s not genuinely better for everyone — it’s a visual choice, and a noticeable one, and many users have spent considerable time arranging their menu bars to look exactly the way they want them to. And the discovery mechanism for “why did my menu bar suddenly grow a grey blob” isn’t intuitive — most users would not, on their own, think to right-click the icon and look for a Settings entry. They’d assume it’s some new system thing, or a glitch, and either tolerate it or close the app.

The right test isn’t “would I want this as a user?” It’s “would a user who didn’t ask for this notice and resent it?” The pill change failed that test silently. It’s the same failure mode as software that auto-enables analytics, or auto-enrols you in newsletters, or quietly turns on a feature you’d previously declined. Each individual case is small. The aggregate is the reason people don’t trust software.

The mechanics of reversal

Reversing across ten repos in one sweep was easier than I’d expected, mostly because I’d been disciplined about putting the offending line in exactly the same place in each app’s applicationDidFinishLaunching. A simple string match (register(defaults: ["menuBarPillEnabled": true])) found every instance. Each removal was a one-line diff. Build, sign, push, repeat.

The interesting question was which apps to include. The eleven from yesterday’s rollout, obviously. CalendarUpcoming, which had been the canonical reference for the new pill — it had also picked up the register line (I’d literally copied it from there originally). And Lookout, the new app I’d shipped two days earlier with the convention baked in from v0.1.0.

Thirteen apps in total, ten of which got new commits today (three already had it reverted as part of earlier spot-fixes). Each commit message says the same thing, give or take:

Drops the UserDefaults.register(defaults: [menuBarPillEnabled: true]) line. The pre-rollout behaviour was default-off — users who never explicitly toggled the pill in Settings had no pill — and the register-default-true silently turned it on for those upgraders.

UserDefaults.bool(forKey:) returns false for missing keys, so removing the register restores the legacy default without any migration logic. Users who explicitly enabled or disabled the toggle keep their stored preference.

The “users who explicitly enabled or disabled the toggle keep their stored preference” line is the bit I want to draw attention to. The fix doesn’t blow away anyone’s preferences. If you actively turned the pill on yesterday because you liked it, you still have it. If you turned it off because you didn’t, that also still applies. Only the people who never expressed a preference are affected, and they revert to the original “no pill” default.

That’s the cleanest possible reversal: it touches state only for the population that didn’t have state in the first place.

What I learned

Three things, in order of importance.

The first is technical and fairly mechanical: UserDefaults.register(defaults:) is a fallback, not a default for new users. Every Apple-provided documentation page I’ve ever read on it treats the two as interchangeable. They’re not. If you ship a register call in an existing app, every user who hasn’t touched that key gets the new behaviour silently.

The second is a habit shift: when reviewing a convention document, ask “what happens to existing users who didn’t pick a value?” Not “what happens on a fresh install?” The fresh-install case is rare in any mature product. The “user with no preference set” case is the entire installed base the first time a feature is introduced.

The third is the thing I keep relearning, in slightly different shapes, every few months: the difference between making the right choice and changing the user’s choice is enormous, and software does the second far more often than it knows. Every flag, every setting, every bit of saved state is a tiny contract with the user. They picked it; you respected it. The moment your code starts changing values silently — even values it set itself, even values that “the user never explicitly chose” — you’ve broken the contract, and the user is right to notice.

The pill change wasn’t malicious. It was a clean technical implementation of what looked like a clean convention. It still produced a small unwanted change for everyone, and the only honest fix was to back it out.

I’m pretty sure no one will notice the reversal. The pill goes from “uninvited to absent,” and absent is what users had before. The change won’t trigger any hot takes; nobody’s going to write a thinkpiece about The Day The Pills Disappeared. Which is, in a way, the lesson: the right default is the one users don’t have to think about, because nothing changed underneath them.

That sounds boring. Boring is correct.

Photo by Saad Jameel on Unsplash

I lost my mouse pointer at one in the morning.

I was dogfooding the latest ActiveSpace build — running it on my own machine for a few days before declaring it shipped — and I’d just woken the screen from lock. I went to do something with my mouse, and there was no pointer anywhere in sight. Just a desktop, sitting there, with all the unhurried indifference of any inanimate object.

Pointer invisibility is one of those things you can almost feel as much as see. The pointer isn’t at the centre of your attention — it’s the thing that directs your attention — so its absence registers as a kind of low-grade vertigo before you consciously notice it’s gone. You move the mouse a bit. Nothing. You move it more emphatically. Still nothing. You start the mental triage: did the screen freeze? Is the mouse unresponsive? Battery exhausted? You tap a key and the menu bar clock ticks; the system isn’t hung. So it’s the pointer specifically. It’s gone somewhere.

I had a strong suspicion about where.

The 640×480 black hole

If you’ve read the third instalment of the stars-align trilogy, you’ll know that ActiveSpace, on single-monitor setups, creates an invisible 640×480 virtual display 6,000 points off-screen to the right. It exists for a structural reason — macOS’s single-display identifier of “Main” breaks the Dock’s gesture handling, and a second display forces the OS into proper UUID-based identifiers, which fixes everything — but it has a side effect: the OS treats the virtual as a perfectly valid place for the pointer to live.

The fence I built into ActiveSpace catches the pointer when it tries to enter the virtual’s space and warps it back to the inside edge of main. It’s a session-level CGEventTap on mouseMoved and the *MouseDragged events, fast, arrangement-aware, and reliable… ninety-nine and a bit per cent of the time. There’s a small window during park-and-unpark of the virtual display — specifically when the screen wakes from lock, while the fence is briefly disarmed because the virtual display it’s policing is mid-move — where a fast pointer throw can slip past. About 750 milliseconds, in practice. Hard to hit deliberately. Easy to hit by accident if you’ve moved your mouse at the wrong moment of waking.

So at 1am, my pointer was at (7000, 240) or thereabouts, sitting peaceably on the virtual where I couldn’t see it. The good news: I knew the bug. The bad news: I’d run out of mouse to use to fix the bug.

What I did about it (the wrong way)

I knew exactly how to recover. CGWarpMouseCursorPosition. Three lines of Swift. I just needed to run it.

I opened Terminal. I typed… commandspace for Spotlight, “terminal”, return. Terminal opens to the focus of the front-most application, which depending on what was up could be helpful or not. I typed in:

echo 'import CoreGraphics; CGWarpMouseCursorPosition(CGPoint(x: 200, y: 200))' | swift -

The pointer reappeared, near the top of the menu bar, exactly where I’d aimed it. Crisis averted. I went to bed at 1.20am, having added the recipe to ActiveSpace’s README under “If your mouse pointer disappears.” A documentation fix, I told myself. The cursor fence catches almost everything; in the rare case it doesn’t, here’s a one-liner.

The next morning I read the README again with a fresher pair of eyes. Two things made me immediately uncomfortable.

First: the recipe asks the user to open a Terminal. To open a Terminal, our user needs to either know the keyboard incantation for Spotlight (which most users do) and the keyboard incantation for opening apps via Spotlight (which most users do) and not have a configuration where Spotlight opens to a focus that interferes with typing (which is mostly fine), and then once Terminal is open, our user needs to paste a Swift one-liner into it. None of which is impossible without a pointer. All of which is meaningfully harder than it would be with one.

Second: the recipe lives on a web page. The web page lives on jorviksoftware.cc. Our user, in order to read the recipe, needs to… navigate… to it… in a browser…

The README was inviting users to play a deeply unfair version of the game where every standard recovery action assumed the precise capability they’d just lost. It read fine; it was useless.

Introducing MouseCatcher

The fix is so obvious that I felt slightly stupid for not having reached for it the night before. What I needed was a tiny app — not a panel, not a setting, not an option somewhere in ActiveSpace itself — an app that repositions the pointer and exits. Spotlight is keyboard-only. commandspace, type mousecatcher, return. If the app is in /Applications, Spotlight finds it. The whole recovery becomes three keystrokes and a twelve-letter word.

Building it

The interesting thing about an app that does one fixed thing and exits is that it has almost no architecture. Here is the entire implementation, give or take:

import Cocoa
import CoreGraphics

_ = CGAssociateMouseAndMouseCursorPosition(1)
let bounds = CGDisplayBounds(CGMainDisplayID())
CGWarpMouseCursorPosition(CGPoint(x: bounds.midX, y: bounds.midY))
exit(0)

CGAssociateMouseAndMouseCursorPosition(1) is defensive: if for some reason the cursor has been detached from mouse motion (rare, but cheap insurance — you don’t want to have warped it to a visible position only to find that wiggling the mouse doesn’t move it), this re-associates the two. CGMainDisplayID() returns the display owning the menu bar, which under normal circumstances is always a real display; the virtual sits off-screen and is never main. CGWarpMouseCursorPosition does the actual warping, in absolute global coordinates that bypass display-edge confinement. The exit is honest about what kind of program this is: a single function call dressed in an .app bundle.

The bundle has LSUIElement = true and the activation policy never escalates, so there’s no Dock flash on launch. The whole thing runs in a few tens of milliseconds and is gone before macOS would have time to draw an icon for it. Spotlight launches it; you don’t see anything happen except the cursor reappearing, near the centre of your main display. Then nothing else, because there is nothing else.

It’s a few lines of Swift, an Info.plist, a build script, and a generated icon. About forty-five minutes of work, including the icon. I have written longer commit messages.

How to ship it

The interesting question wasn’t how to write MouseCatcher; it was how to distribute it. The Jorvik convention is one repo per app, one Release Manager entry per app, one GitHub release per app. MouseCatcher could’ve been all of those things. Three new files in a new repo, an entry in the catalogue, a release page. Done.

It would have been over-engineered. The whole point of MouseCatcher is that it’s a partner of ActiveSpace — you wouldn’t need it without ActiveSpace’s virtual display, you wouldn’t install it without ActiveSpace, and asking users to chase a separate download for the recovery utility for their other utility seemed ridiculous. So MouseCatcher rides in ActiveSpace’s release. One .pkg, one .zip, two .apps.

The implementation is what Apple sometimes calls a helper-app architecture. MouseCatcher.app is built by a Run Script build phase inside ActiveSpace’s Xcode project, then copied into ActiveSpace.app’s Contents/Helpers/ directory. Both bundles get signed, both get notarised, both get stapled. The outer ActiveSpace bundle is what users download; MouseCatcher rides inside, invisible, unseen.

Then, on every launch, ActiveSpace runs a tiny self-deploy step. It reads the version of MouseCatcher embedded inside its own bundle. It reads the version of MouseCatcher (if any) at the deployed location. If they match, it does nothing. If the deployed copy is missing or older, it copies the embedded one across. The result: when ActiveSpace updates and the new release contains a newer MouseCatcher, the deployed copy refreshes silently the next time you launch ActiveSpace. No installer, no permissions prompt, no user action.

Mostly.

The /Applications/Utilities trap

I had originally planned to deploy MouseCatcher to /Applications/Utilities/. Conceptually it’s a utility; conceptually that’s where utilities go; macOS has had that subfolder since approximately the dawn of time. It felt right.

I shipped a build with that target path. ActiveSpace launched. Nothing appeared at the deployed location.

The aslog file showed nothing. The deploy code is wrapped in a do-catch that logs the error description on failure. The error description was… not in the log. Which is interesting because that meant either the deploy hadn’t run at all (likely, given a race condition I’d been worried about), or the deploy had thrown silently somewhere I wasn’t catching (unlikely, given how the code was structured), or the deploy had run, the catch had fired, and the log line had ended up somewhere I wasn’t looking.

It was the third one. The launchd handoff path that ActiveSpace uses on first launch was draining the run loop and exiting before any log writes finished flushing. So the catch fired, but the message was lost. I’d been blind-firing into the void.

The actual cause turned out to be embarrassingly simple. Type this:

ls -lde /Applications/Utilities

And you get something like this:

drwxr-xr-x  5 root  wheel  160 10 Apr 06:23 /Applications/Utilities

Mode 755, owner root, group wheel. The wheel group, not admin. Even an admin user can’t write into /Applications/Utilities without elevation — without a sudo, or an Authorisation Services prompt, or a privileged helper. macOS reserves the folder for system utilities. I’d been quietly blocked every time the deploy ran, and the launchd-related log loss had hidden the evidence.

This is the kind of thing where you find out the assumption you’ve been making for a decade is wrong. /Applications, the parent, is drwxrwxr-x root admin: any admin user can write there. So can the user-driven Mac App Store, drag-from-DMG, .pkg installers from any developer the user trusts. /Applications/Utilities is a different beast. Apple owns it, even on your own machine.

The fix is the path nobody had any reason to feel strongly about: /Applications/MouseCatcher.app, sibling of /Applications/ActiveSpace.app, exactly where every other Jorvik utility installs. The deploy works. The cursor is recoverable. Spotlight finds it.

I’ll concede that aesthetically I’d still prefer it under /Applications/Utilities/. But there is no point in fighting the OS’s permission model for a tiny one-shot application, and inviting users to type their password to install this utility is the kind of UX that makes the cure worse than the disease.

The Spotlight cache plot twist

One last thing. Even after the deploy started working, Spotlight kept surfacing the wrong copy of MouseCatcher.

I’d done a Spotlight cleanup the day before — deleted an iCloud Drive clone of the entire Jorvik source tree (the long-overdue purge of a path that had been causing me headaches for weeks), deleted a backup folder full of stale apps, deleted a few stray Xcode build directories. Reclaimed about ten gigabytes. Dropped a .metadata_never_index marker at the root of ~/Dev/Jorvik Software/ so Spotlight would stop indexing build artefacts in there going forward. Going forward. The cached entries from before the marker was added were still in the index.

What that meant practically: commandspace → “MouseCatcher” and Spotlight returned /Users/<username>/Dev/Jorvik Software/ActiveSpace/MouseCatcher/MouseCatcher.app — the build artefact in the source tree — because that path had been indexed before the marker existed. The marker stops new indexing; it doesn’t flush old entries.

The way to flush is to add the path to System Settings → Spotlight → Privacy. macOS treats that as “immediately drop everything you have for paths under here.” You can then optionally remove the path from Privacy afterwards (the marker file keeps it from being re-indexed even when removed from Privacy, so the source tree stays Spotlight-invisible either way).

I added it. Cached entries vanished. Spotlight returned only /Applications/MouseCatcher.app. The recovery flow worked, end to end, in three keystrokes.

The bigger question, briefly

I want to be honest about what kind of utility MouseCatcher is. It’s the workaround to a known limitation of a workaround. ActiveSpace’s virtual display is itself a workaround for an OS bug; the cursor fence is a workaround for the virtual display’s side effects; MouseCatcher is the recovery flow for the rare case where the fence misses.

That’s a tower of mitigations, and I notice I’ve been building a lot of those lately. I can defend this because the OS bug is real, the virtual is the smallest workaround that solves it, the fence covers the secondary issue cleanly, and MouseCatcher is a few hundred bytes of recovery for the residual edge case.

Each layer has a clear reason to exist. The user, on a single-display Mac running a recent macOS, gets instant space switching with no visible cost — and on the rare day the rent does come due, the recovery is a quick Spotlight search away.

That feels like an acceptable bargain.

It also feels like the kind of bargain you only notice you’ve struck when you’re sitting in front of a Mac at one in the morning, and your mouse pointer is gone, and you realise the recovery instructions on your own website assume the one capability you don’t currently have.

Now they don’t.

Photo by Alexander Andrews on Unsplash

This is the third post in what I now realise is a series. When the Stars Align was the triumph — instant space switching, about six hours before we found out it was broken on single-monitor setups. When the Stars Align (Redux) was the fix — an invisible 640×480 virtual display to force macOS off its “Main” display identifier and onto proper UUIDs, restoring the Dock’s ability to composite correctly.

“The user never knows it’s there,” I wrote then. In fairness to April-11-me, I had just spent the better part of twenty hours convinced the compositor was a sealed black box, and arriving at a working solution at 5am does tend to produce overconfident prose.

As it turns out, the user does know it’s there. Not because the display is visible — it isn’t — but because the 640×480 rectangle of coordinate space that macOS thinks the virtual display occupies is emphatically not inert territory, no matter what the word “virtual” might suggest.

The cracks

For about a week after the Redux, ActiveSpace felt fine. Instant space switching, intact menu bars, working compositor. Every now and then I’d notice my Dock had briefly disappeared. Always in the same kind of moment — waking from sleep, plugging in an external monitor, switching back to laptop-only — and always self-healing within a few seconds. I put it down to general macOS wake flakiness.

Then one Saturday morning, with ActiveSpace freshly running in a debug build, the Dock didn’t come back. I ran killall Dock and it returned, but by that point the pattern had clicked into place. The Dock went missing when the virtual display was present. Never when it wasn’t.

I dragged my cursor to the right edge of my main display. It kept going. Off the edge. Into the 640×480 invisible region where the virtual lived. I couldn’t see the cursor any more, but I could watch it come back when I pulled it to the left.

“That’s not as virtual as we thought,” I said out loud, to no-one.

What “virtual” apparently means

CGVirtualDisplay creates a display that has no physical hardware and no surface — but structurally, it’s a real display as far as WindowServer is concerned. It sits in NSScreen.screens. It has an origin, a size, a UUID, an entry in ~/Library/Preferences/com.apple.spaces.plist. The Dock, looking for somewhere to anchor itself when the display arrangement changes, sees a valid display — 640 by 480, adjacent to the main — and sometimes decides that’s a perfectly fine place to render. The cursor, on hitting the right edge of main, does what cursors always do when there’s an adjacent display: it crosses onto it.

What my virtual-display trick actually produces isn’t an invisible display. It’s an uninhabited visible display. macOS doesn’t have a concept of “real display with no framebuffer” separate from “logical display.” Everything it knows about how to treat a display comes from the display list, and our virtual is in the list.

I’d handed the Dock a perfectly plausible second monitor and then been surprised when it took me up on the offer.

Three fixes, in order of cheapness

I won’t dwell on all the intermediate attempts — they’d make this post longer than it deserves — but three specific fixes are worth naming because each resolved a distinct way the virtual display failed to stay out of the user’s way.

The drift reposition. At creation time I was placing the virtual display adjacent to the right edge of the main display, on the theory that macOS wouldn’t reposition a secondary display that was already in the position it naturally wants. Apparently macOS disagrees. On several workflows — particularly the brief window after display reconfiguration — it would silently move the virtual from (2560, 0) (right of main) to (-640, 0) (left of main). That leftward move was what dragged the Dock off with it, because whatever heuristic picks the Dock’s display prefers the leftmost. Fix: after every didChangeScreenParametersNotification, check whether the virtual has drifted, and if so re-apply CGConfigureDisplayOrigin with a rate-limit and a small retry cap to stop us fighting macOS in a loop. In practice one attempt is always enough.

The cursor fence. The drift fix keeps the virtual anchored where I want it, but the cursor can still cross onto it at the contiguous right edge. I spent the best part of a day hunting through the introspection dump of CGVirtualDisplaySettings for a headless or isInternal flag that would mark the display as non-routable for UI. There wasn’t one — the only candidate, isReference, affects nothing useful. So: a session-level CGEventTap watching mouseMoved / mouseDragged, which warps the cursor back to the inside edge of main whenever an event location lands inside the virtual’s rect. The fence is arrangement-agnostic (clamps left or right depending on which side of main the virtual lives on) and fast enough to run on every mouse event without any visible lag.

The restart mechanism that didn’t need to exist. With the drift reposition and cursor fence in place, the virtual was finally behaving like “invisible” was meant to imply. But I’d also convinced myself that ActiveSpace needed a self-restart mechanism for edge-case drift conditions — the app should terminate cleanly on “dock ended up on virtual” or “spaces got reordered by screensaver wake” and let a launchd keep-alive agent respawn it with a fresh slate. I built the whole thing: a six-source reconfiguration observer, a drift classifier, a launchd agent plist with KeepAlive: SuccessfulExit=false and a 30-second throttle, a trigger-class-aware grace window, a post-restart cooldown to prevent loops. It took the better part of a day. I dogfooded it in dry-run mode for two days.

Across those two days of real use — laptop-only, dual-external, screensaver cycles, lid-close sleep/wake, adding and deleting spaces — the classifier fired seven times. In every case the other mitigations (the drift reposition, the cursor fence, SpaceObserver.refresh() re-querying CGS from scratch on every poll tick) had already dealt with the observable problem by the time a restart would have kicked in. ActiveSpace’s in-memory state never became unrecoverably stale. There was no poisoned cache. There was no wedge. A restart wouldn’t have improved anything; it would have just interrupted my work for 300ms and reset my Switcher MRU stack.

So I deleted the restart. The observer and classifier stayed — they’re genuinely useful for logging and future debugging — but the RestartCoordinator became a DriftMonitor that writes drift-observed(…) to ~/Library/Logs/ActiveSpace.log and does nothing else. The launchd keep-alive agent stayed too, for its unrelated benefit: if ActiveSpace ever does crash, launchd respawns it. That’s worth having. But the “self-restart on drift” framing was a sledgehammer for a nail that two smaller hammers had already hit.

Pre-warmed icons, while we’re here

One last thing. The Switcher HUD — the commandtab overlay that lets you cycle between apps on the current space — had a subtle lag. The first time you opened it after launching a new app, the app’s icon took a second or so to appear. Not catastrophic, but noticeable.

NSRunningApplication.icon is lazy. First access goes out to icon services to resolve the bundle’s icon file. Then NSImageView does the scale-down-to-96pt render, on the main thread, during HUD assembly. Both costs were being paid inline. The fix is a small in-memory cache: at app startup, we pre-warm icons for every currently-running regular app by fetching them and pre-drawing into a bitmap at the display size. Then we observe NSWorkspace.didLaunchApplicationNotification and warm newly-launched apps as they come online. In the HUD path, we serve from the cache instead of asking NSRunningApplication every time.

No more lag. A week of small fixes adds up to an app that feels fundamentally different to use.

What “fixed” means

The lesson I keep coming back to across this series is that “I’ve fixed it” is rarely true the first time you say it, and often not the second. The original post was right that instant switching was a real win. The Redux was right that the virtual-display trick made it work on every display configuration. But “works” and “ships cleanly” are not the same thing, and there was a whole week of subtle misbehaviour standing between them that only daily use could surface.

The other lesson is that engineers — me, specifically, in this case — reach for complicated solutions when simple ones would do. The self-restart mechanism was beautiful and correct and completely unnecessary. I enjoyed building it; I enjoyed deleting it rather more. The data showed it wasn’t needed, so it went.

ActiveSpace is shipped. It’s the first version I’m genuinely happy to hand a user who doesn’t know how to debug ~/Library/Logs. The virtual display stays where I put it. The cursor doesn’t wander off. The Dock stays home. The Switcher HUD feels snappy from the first keypress. Space switching is instant in every display configuration I’ve tested.

The stars aligned. Then they fell apart. Then we hung a new one in the sky. Then we discovered the new one had its own orbit, fought with it for a week, and finally got it to sit still.

Third time’s the charm. I hope.

Photo by Clay Banks on Unsplash

I built a screen saver in 2026. Not ironically. Not as a joke. A genuine .saver bundle that installs into System Settings, activates after five minutes of idle time, and does something mildly interesting with your screen while you’re away.

Most people I mention this to react the same way: “macOS still has screen savers?”

It does. And building one is a surprisingly interesting exercise in working with a part of the operating system that Apple seems to have mostly forgotten about.

Why screen savers still exist

The original purpose of a screen saver was to prevent phosphor burn-in on CRT monitors. That problem hasn’t existed for twenty years. Modern displays — LCD, OLED, mini-LED — don’t burn in from static images in any meaningful timeframe (OLED has some susceptibility, but the OS handles that with pixel shifting, not screen savers).

So why does macOS still ship with a screen saver framework?

Partly inertia. The ScreenSaverView API has been part of macOS since the early days of OS X, and Apple doesn’t remove things from the system frameworks unless they have a compelling reason. Partly because screen savers serve a purpose that has nothing to do with screen protection: they’re a visual signal that a machine is idle. In an office, a screen saver means “this person stepped away.” It’s a social convention that happens to be implemented in software.

And partly because they’re fun. Apple clearly thinks so — macOS Sonoma added a set of beautiful slow-motion video screen savers that double as lock screen backgrounds. They don’t prevent burn-in. They’re just nice to look at.

ASCII Saver

My screen saver — ASCII Saver — takes the feed from your Mac’s camera, converts each frame to ASCII art, and renders it as a full-screen grid of characters on a black background. Your face, your desk, your cat, your empty chair — all reduced to a matrix of letters, numbers, and symbols that approximate the light and shadow of the original image.

The effect is somewhere between retro computing aesthetic and security camera footage from a particularly artistic building. It’s recognisably “you” but abstracted enough to be interesting rather than unsettling. The character density is high enough that you can make out shapes and movement, but low enough that the individual characters are visible. It updates at roughly 15 frames per second — fast enough for smooth motion, slow enough that you can actually see the characters changing.

There’s something oddly meditative about watching yourself rendered in monospace text. Your movements become patterns of shifting characters. Raising your hand changes a column of spaces into a cascade of Ms and Ws (the densest ASCII characters). Leaning back dissolves your outline into dots and commas. The mapping from brightness to character is deterministic — the same light level always produces the same character — so the image has a consistency that pure noise wouldn’t have.

I convinced you… you want to build your own screen saver now, don’t you?

The .saver bundle

A macOS screen saver is a bundle with the .saver extension that contains a compiled framework. The entry point is a subclass of ScreenSaverView — an NSView subclass provided by the ScreenSaver framework. You override animateOneFrame(), which the system calls at whatever frame rate you’ve requested, and draw into the view.

import ScreenSaver

class ASCIISaverView: ScreenSaverView {
    override func animateOneFrame() {
        // Capture frame, convert to ASCII, draw
    }
}

That’s the skeleton. The system handles activation, deactivation, configuration sheets, preview rendering in System Settings, and hot-corner triggering. Your code just draws.

Installation is into ~/Library/Screen Savers/ (per-user) or /Library/Screen Savers/ (system-wide). Drop the .saver bundle there and it appears in System Settings under Screen Saver. No registration, no manifest, no app wrapper required.

What Apple forgot

Building a screen saver in 2026 means working with an API that Apple maintains but doesn’t actively develop. The ScreenSaver framework hasn’t had significant updates in years. The documentation is sparse and occasionally wrong. The preview rendering in System Settings is buggy — it sometimes caches old versions of the screen saver, requiring a logout to see changes.

The configuration sheet mechanism — configureSheet() — returns an NSWindow that the system displays as a modal sheet when the user clicks “Options” in Screen Saver settings. This works, but SwiftUI views don’t play nicely inside it. You end up bridging SwiftUI into AppKit with NSHostingController, which adds complexity for what should be a simple preferences panel.

The hot corner activation has a curious behaviour: when triggered by a hot corner, the screen saver starts in a different lifecycle state than when triggered by the idle timer. Some initialisation that happens automatically in the timer path doesn’t happen in the hot corner path. If your screen saver has setup that assumes a particular activation order, hot corners will break it.

And then there’s the code signing. Screen savers need to be signed and notarised like any other distributable macOS binary. But they also need to be signed in a way that the legacyScreenSaver host process trusts. If the signature is wrong — or if the signing identity doesn’t match what the system expects — the screen saver silently fails to load. No error message. It just doesn’t appear in System Settings.

The forgotten platform

Screen savers occupy a strange niche in the macOS ecosystem. They’re not apps — they don’t have their own process, their own Dock icon, or their own lifecycle. They’re plugins hosted by a system process, with all the constraints that implies. They can’t do anything the host process doesn’t allow, they can’t request permissions the host process doesn’t have, and they can’t persist state in the usual ways because they’re loaded and unloaded at the system’s discretion.

And yet they have direct access to the full screen, the GPU, and — through service/agent workarounds — hardware peripherals. They run when the user is away, which means they can do things that would be distracting during active use. They’re a canvas with no UI obligations — no buttons, no menus, no accessibility requirements. Just a rectangle of pixels that you can fill however you want.

I think there’s more to be done with this canvas than we’re currently doing. The Apple-provided screen savers in Sonoma are beautiful, but they’re passive — pre-recorded video. A screen saver has access to real-time data: the time, the date, the weather, the calendar, the camera, the microphone, the network. It could show you your next meeting. It could visualise your currently-playing music. It could render your recent git activity as a contribution graph. It could do anything that a full-screen, always-idle application can do.

Nobody’s building these things, partly because the API is old and the documentation is thin, and partly because screen savers have a branding problem. They sound like a relic. They sound like the flying toasters and maze solvers of the 1990s. They sound unserious.

But a dedicated full-screen display that activates when you step away from your desk? That’s not unserious. That’s a digital photo frame. That’s a dashboard. That’s ambient information design. It’s just wearing the wrong name.

Building one yourself

If you want to build a macOS screen saver, here’s what I wish someone had told me:

Start with a new Xcode project using the Screen Saver template. It gives you the ScreenSaverView subclass and the correct bundle structure. Build it, and copy the .saver to ~/Library/Screen Savers/. It should appear in System Settings immediately, but if it doesn’t, log out and back in.

Keep your first version simple. Override animateOneFrame(), draw something, see it work. The preview in System Settings is small but functional — you don’t need to test with the full screen saver activated until you’re further along.

If you need any hardware access — camera, microphone, location — you need an out-of-process helper. Accept this early and architect for it from the start. Don’t spend hours trying to make camera access work inside the sandbox. It won’t.

Sign everything. The .saver, the helper app, all of it. An unsigned screen saver will silently fail to load on any Mac with the default security settings.

And test with hot corners, not just the idle timer. The activation paths are different, and the differences will find your bugs.

Screen savers are a forgotten corner of macOS. But forgotten corners are where the interesting work happens — where the API is stable because nobody’s changing it, where the competition is thin because nobody’s building for it, and where a small, focused project can produce something genuinely delightful.

Turning your idle Mac into a real-time ASCII art rendering of your office? That’s delightful. I’ll stand by that.