Build and verify

A change is done when four things are true:

1. ./build.sh finishes with no errors.
2. You looked at the light and dark snapshots of every page you touched.
3. The snapshots match what the user story or reference screenshot asks for.
4. The grid checks pass (layout-grid skill).

App not made from the new-mac-app template (Xcode, XcodeGen, a menu bar utility, Swift 5)? Map the commands below with existing-app.md first.

Do not report a UI change as done from the code alone. SwiftUI code that compiles can still render an empty sidebar, clipped text, or unreadable dark mode.

1. Build

./build.sh            # release build, installs ~/Applications/<AppName>.app
./build.sh --debug    # faster build while iterating
./build.sh --open     # also restarts the app so the user sees the new build

Read the errors, fix them, and build again. Fix the first error first: later errors often come from it. If a new file is "not in scope" right after you created it, run swift package clean --scratch-path ~/Library/Developer/<AppName>/build.

2. Snapshot

Run the installed binary directly with a test database and a folder for the images. The app opens, walks through every sidebar page and every Settings tab in light and dark mode, saves one PNG per page and mode, and quits.

tools/snap.sh
# SNAPSHOT /tmp/<AppName>-shots/all-light.png
# ...
# SNAPSHOT done /tmp/<AppName>-shots

tools/snap.sh deletes the old test store (with its -wal and -shm files) and the saved window state first, then runs with sample data (APP_SEED=1). Without that, seed data goes stale, and one crashed run leaves a "reopen windows?" alert that hangs every later run.

Use APP_SNAPSHOT_PAGES=today,inbox to limit the pages. Add settings to include the Settings tabs.