# Particles & Calendar Desktop

A native macOS desktop layer by Quinn Dyer. The source combines rising particles, a month calendar, an expandable day agenda, task capture and completion, weather, and a timestamped SPY quote strip. SwiftUI draws the interface; AppKit manages the desktop windows and click-through decoration.

This is a source snapshot of a personal desktop project, prepared for public review. It is not a notarized general-purpose app release. The downloadable copy starts with synthetic agenda, task and weather data. The quote request is disabled in sample mode. No account, OAuth client, API key, token, private calendar, task cache, screenshot of live data, or compiled app is included.

## Build and review

Requires macOS 14 or newer, Swift 6, and Apple's command-line development tools. The Swift package has no external package dependencies.

```sh
swift build --product QuinnDesktop
swift run DashboardSelfTests
```

The self-test executable uses mock HTTP transport and in-memory tokens. It does not sign into Google or access a real account. To build an ad-hoc signed sample app locally, run `bash Scripts/build_app.sh`. That script creates an app in `dist`; it does not install or launch it. A plain `swift run QuinnDesktop` starts the sample UI. Default sample mode uses the same real layout and interactions with fictional data.

## Source map

- `Sources/QuinnDesktop`: particles, views, window coordination, sample provider, weather and Google integration.
- `Sources/DashboardCore`: dates, agenda ordering, progressive reveal, task logic, OAuth/Google client and quote decoding.
- `Sources/DashboardSelfTests`: offline behavioral checks and synthetic protocol fixtures.
- `Config/Configuration.example.plist`: placeholder OAuth client configuration; it is not a credential.

## Optional live integration

Live services require an explicit `--live-data` launch flag and your own setup. Search for `sample.user@example.com` and its URL-encoded form to set the expected account consistently. The weather coordinates are a sample city center, not the author's location. Replace them for your own use.

Create your own Google Desktop OAuth client with Calendar read-only and Tasks scopes. The native configuration loader expects `GoogleOAuthClientID` in an owner-only, mode-0600 `Configuration.plist` in `~/Library/Application Support/QuinnDesktopPublic/`. Client credentials and refresh tokens are handled by the app's separate macOS Keychain services; do not paste credentials into source. OpenWeather requires your own key and configuration. No live integration was exercised while preparing this public copy.

The explicit `--import-google-client` command imports a user-provided OAuth client JSON into this copy's Keychain service and removes the transfer file. The app's Connect & Test Google flow asks before creating, completing, reopening and deleting a clearly named temporary task. Review that behavior before enabling it. Sample mode never creates a Google task.

The public app bundle identifier, Keychain service names, cache directory, menu-bar preferences and quick-capture preferences are separated from the author's installed app. Personal installation, rollback, resource measurements and widget-migration scripts are excluded.

## Earlier iteration

[First iteration (2022)](https://www.reddit.com/r/mac/comments/soy24y/my_really_customized_desktop_dynamic_wallpaper/)

The earlier desktop customized existing Übersicht widgets. The source in this download is the later native Swift implementation. [Original explanation](https://www.reddit.com/r/mac/comments/spiim4/explanation_for_my_desktop/).

See `PROJECT-PAGE.md` for concise public page copy and `LICENSE-NOTICE.md` for reuse status.

## Public-copy validation

The app source compiled successfully on the preparation Mac. All 50 existing offline self-tests passed. The app UI and live integrations were not launched. The sample app packaging script is included for convenience but was not run. See `VALIDATION.json`.