1# Haven23A lightweight macOS menu bar app for finding, setting, and managing desktop4wallpapers. Browse [Wallhaven](https://wallhaven.cc) without leaving the menu5bar, set any image as your wallpaper with a click, and keep a local library of6the ones you download.78## Features910- **Explore** — search Wallhaven with live filtering by category11 (General / Anime / People), purity (SFW / Sketchy), resolution, and aspect12 ratio. Infinite scroll loads more as you go.13- **Outage aware** — when Wallhaven's own servers are down, the Explore tab14 explains that where the grid would be, links to Wallhaven's status page, and15 offers a retry, so an upstream outage never reads as Haven failing.16- **Set instantly** — click a wallpaper to set it on your active display.17- **Local library** — wallpapers you download are saved to a folder of your18 choice and browsable offline. Unreadable or broken image files are skipped19 automatically so they never clutter the view.20- **Favorites & History** — keep the ones you love and revisit anything you've21 set recently.22- **Launch at login** — optionally start Haven automatically.2324## Requirements2526- macOS 13 (Ventura) or later27- Swift 6.1+ toolchain (Xcode or the Swift command-line tools)2829No Wallhaven API key is required — Haven uses the public search API and browses30SFW and Sketchy content only.3132## Build & Run3334Build a signed `.app` bundle and launch it:3536```sh37./bundle_app.sh38open Haven.app39```4041Or run directly during development:4243```sh44swift build45swift run46```4748Run the full test suite and the checked-in 100% physical source-line coverage gate:4950```sh51bash coverage.sh52```5354The coverage command combines `swift test --enable-code-coverage` with a55smoke run of the executable so the real entry point is measured. Its physical56source-line gate excludes blank, comment-only, and structural brace lines;57the LLVM aggregate report printed above it also includes compiler-generated58SwiftUI mappings and can therefore be lower.5960Haven lives in the menu bar (it has no Dock icon). Click the menu bar icon to61open the popover.6263## Usage6465| Tab | What it does |66| --- | --- |67| **Explore** | Search and browse Wallhaven. Use the slider icon to filter. |68| **Local** | Browse wallpapers saved to your local folder. |69| **Favorites** | Wallpapers you've hearted. |70| **History** | Recently set wallpapers. |71| **Settings** | Launch at login, local-save toggle, and save-folder location. |7273By default, downloaded wallpapers are saved to `~/Pictures/Haven`. Change this74in **Settings → Storage → Location**.7576## Project Layout7778```79Sources/Haven/80 API/ Wallhaven client and response models81 Managers/ Wallpaper, local library, favorites, history, autostart, cache82 UI/ AppState, menu bar controller, and SwiftUI views83 main.swift Entry point84```8586## License8788Haven is free software: you can redistribute it and/or modify it under the89terms of the **GNU General Public License as published by the Free Software90Foundation, either version 3 of the License, or (at your option) any later91version**. See [`LICENSE`](LICENSE) for the full text.9293```94Haven — a macOS menu bar app for browsing, setting, and managing wallpapers.95Copyright (C) 2026 Asha Software96```