# Haven

Haven is a macOS menu bar app for browsing [Wallhaven](https://wallhaven.cc)
and setting your desktop wallpaper. You can also browse images in local
folders, save favorites, and return to wallpapers you've used before.

## Using Haven

Click Haven's menu bar icon to open it. The app has no Dock icon.

| Tab | What you can do |
| --- | --- |
| Explore | Search Wallhaven or browse Latest, Toplist, and Random. Open the slider controls to filter by category, purity, resolution, or aspect ratio. More results load as you scroll. |
| Local | Browse images from your source folders, including when you're offline. Haven skips files it can't read as images. |
| Favorites | Revisit wallpapers you've marked with a heart. |
| History | Find wallpapers you've recently set. |
| Settings | Choose storage and source folders, turn local saving on or off, and enable launch at login. |

Click a wallpaper to set it on your active display. Haven uses Wallhaven's
public search API, so you don't need an API key. Browsing is limited to SFW
and Sketchy content, with General, Anime, and People category filters.

When local saving is enabled, downloaded wallpapers go to `~/Pictures/Haven`
by default. Choose another folder in Settings → Storage → Location. Use
Source folders in Settings to add other folders to the Local tab.

If Wallhaven is unavailable, Explore explains the outage and gives you a
link to its status page and a retry button.

## Building and running

You'll need macOS 13 (Ventura) or later and a Swift 6.1+ toolchain, provided
by Xcode or the Swift command-line tools.

Build an ad-hoc signed `.app` bundle and launch it:

```sh
./bundle_app.sh
open Haven.app
```

To run during development:

```sh
swift build
swift run
```

## Tests and coverage

Run the test suite and the checked-in coverage check:

```sh
bash coverage.sh
```

The script runs `swift test --enable-code-coverage` and a smoke run of the
executable to measure the entry point. It requires 100% coverage of physical
source lines, excluding blank lines, comment-only lines, and structural
brace lines. The LLVM aggregate report also counts compiler-generated
SwiftUI mappings, so its percentage can be lower.

The last recorded coverage run left 27 UI lines uncovered. The coverage
check requires those lines to be covered even when the tests pass.

## Source layout

```
Sources/Haven/
  API/          Wallhaven client and response models
  Managers/     Wallpaper, local library, favorites, history, autostart, cache
  UI/           AppState, menu bar controller, and SwiftUI views
  main.swift    Entry point
```

## License

Haven is licensed under the GNU General Public License, version 3 or any
later version. You may redistribute and modify it under those terms.
See [`LICENSE`](LICENSE) for the full text.

```
Haven — a macOS menu bar app for browsing, setting, and managing wallpapers.
Copyright (C) 2026 Asha Software
```