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

