# Haven

A lightweight macOS menu bar app for finding, setting, and managing desktop
wallpapers. Browse [Wallhaven](https://wallhaven.cc) without leaving the menu
bar, set any image as your wallpaper with a click, and keep a local library of
the ones you download.

## Features

- **Explore** — search Wallhaven with live filtering by category
  (General / Anime / People), purity (SFW / Sketchy), resolution, and aspect
  ratio. Infinite scroll loads more as you go.
- **Set instantly** — click a wallpaper to set it on your active display.
- **Local library** — wallpapers you download are saved to a folder of your
  choice and browsable offline. Unreadable or broken image files are skipped
  automatically so they never clutter the view.
- **Favorites & History** — keep the ones you love and revisit anything you've
  set recently.
- **Launch at login** — optionally start Haven automatically.

## Requirements

- macOS 13 (Ventura) or later
- Swift 6.1+ toolchain (Xcode or the Swift command-line tools)

No Wallhaven API key is required — Haven uses the public search API and browses
SFW and Sketchy content only.

## Build & Run

Build a signed `.app` bundle and launch it:

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

Or run directly during development:

```sh
swift build
swift run
```

Run the full test suite and the checked-in 100% physical source-line coverage gate:

```sh
bash coverage.sh
```

The coverage command combines `swift test --enable-code-coverage` with a
smoke run of the executable so the real entry point is measured. Its physical
source-line gate excludes blank, comment-only, and structural brace lines;
the LLVM aggregate report printed above it also includes compiler-generated
SwiftUI mappings and can therefore be lower.

Haven lives in the menu bar (it has no Dock icon). Click the menu bar icon to
open the popover.

## Usage

| Tab | What it does |
| --- | --- |
| **Explore** | Search and browse Wallhaven. Use the slider icon to filter. |
| **Local** | Browse wallpapers saved to your local folder. |
| **Favorites** | Wallpapers you've hearted. |
| **History** | Recently set wallpapers. |
| **Settings** | Launch at login, local-save toggle, and save-folder location. |

By default, downloaded wallpapers are saved to `~/Pictures/Haven`. Change this
in **Settings → Storage → Location**.

## Project 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 free software: you can redistribute it and/or modify it under the
terms of the **GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version**. See [`LICENSE`](LICENSE) for the full text.

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