r/macosprogramming • u/BirnenHans • 11h ago
Building a live Earth wallpaper: desktop-level NSWindows, a WKWebView renderer and a frame rate that follows the motion
I've been working on a hobby project, a macOS app that puts a live 3D Earth behind the desktop icons (real sun position, city lights at night, satellite clouds). It's open source and I thought some of the implementation details might be interesting here. I'd also really like feedback on a few decisions.
How it's put together:
- One borderless NSWindow per screen at CGWindowLevelForKey(.desktopWindow), with collectionBehavior [.canJoinAllSpaces, .stationary, .ignoresCycle, .fullScreenNone] and ignoresMouseEvents = true. That keeps it under the icons on every Space and lets clicks through to Finder.
- The Earth itself is a three.js (r160) page in a WKWebView. It's loaded through a custom WKURLSchemeHandler (earth://app/...) because ES modules don't load from file:// URLs.
- The subsolar point uses the low-precision formulas from the Astronomical Almanac, which are good to about 0.01°. That's plenty for a wallpaper.
- Frame rate: the renderer works out how many pixels per second the image actually moves (from zoom, pitch and the motion mode) and schedules frames accordingly, down to one frame every 5 seconds. Camera moves still get the full 30 fps. It pauses on NSWindow.didChangeOcclusionStateNotification and NSWorkspace.screensDidSleepNotification.
- Place search uses MKLocalSearchCompleter, Open at Login uses SMAppService.mainApp.
- No Xcode project. build.sh calls swiftc per architecture and lipo's them into a universal binary. GitHub Actions builds the DMG and also launches the real app to take the README screenshots.
Where I'd like opinions:
Is a WKWebView + WebGL renderer a reasonable choice here, or would you go Metal/SceneKit directly? WebGL made the shaders easy to iterate on and also let me reuse the renderer on the website, but I'm curious about the overhead others have seen.
Is there a more reliable signal than occlusionState for "nobody can see the desktop right now"? It works for me, but I'd like to know if there are cases where it lies.
Anything you'd watch out for with desktop-level windows on newer macOS versions?
It's MIT licensed and macOS 13+. I built it with some help from AI, and I'm happy to go into detail on any part.
https://github.com/Hensobo/earth-now
Short demo video: https://youtu.be/Ov-Rup8pm14

