Dev

.github/copilot-instructions.md

@@ -1,136 +1,43 @@
-# Copilot Instructions for Psst
+# Copilot Instructions
 
-Psst is a fast, native Spotify client written in Rust, without Electron. This repository contains a Cargo workspace with multiple crates that implement different aspects of the application.
+This is a multi-crate Rust workspace that implements the psst Spotify client, including a GUI (`psst-gui`), CLI (`psst-cli`), shared core library (`psst-core`), and protocol bindings (`psst-protocol`). It supports macOS, Windows, and Linux builds via `cargo` and Cross.
 
-## Project Structure
+## Code Standards
 
-- `/psst-core` - Core library handling Spotify TCP session, audio retrieval, decoding, output, and playback queue
-- `/psst-gui` - GUI application built with [Druid](https://github.com/linebender/druid)
-- `/psst-cli` - Example CLI application for testing and development
-- `/psst-protocol` - Internal Protobuf definitions for Spotify communication
+### Required Before Each Commit
 
-## Technology Stack
+- Run `cargo fmt --all` to keep Rust sources formatted consistently across crates.
+- Run `cargo clippy --all-targets --all-features -- -D warnings` to prevent lints from slipping into main.
+- Ensure `./scripts/run-tests.sh` passes; it drives the standard unit/integration suite across the workspace.
 
-- **Language**: Rust (stable, minimum version 1.65.0)
-- **GUI Framework**: Druid (with GTK and X11 backends on Linux)
-- **Build System**: Cargo
-- **Audio**: Custom implementation using symphonia and libsamplerate
+### Development Flow
 
-## Development Guidelines
+- Build (workspace): `cargo build --workspace`
+- Build (GUI app with release profile): `cargo build -p psst-gui --release`
+- Test (workspace): `cargo test --workspace`
+- Full local verification: `./scripts/run-tests.sh`
+- Run GUI app (dev mode): `cargo run -p psst-gui`
+- Cross-platform release check (optional): `cross build --workspace --release`
 
-### Code Style
+## Repository Structure
 
-- Follow Rust standard formatting using `rustfmt`
-- Configuration in `.rustfmt.toml`:
-  - Use crate-level import granularity
-  - Wrap comments at line boundaries
-- Run `cargo clippy -- -D warnings` to check for linting issues
-- All clippy warnings should be addressed before committing
+- `psst-core/`: Core playback, session, caching, and Spotify protocol logic shared by front ends.
+- `psst-gui/`: GUI application built with Druid; handles controller/data/ui layers and platform integrations.
+- `psst-cli/`: Minimal terminal client demonstrating core playback and session routines.
+- `psst-protocol/`: Generated protocol bindings and protobuf definitions; run `./psst-protocol/build.sh` or `cargo build -p psst-protocol` after editing `proto/`.
+- `scripts/`: Helper scripts such as `run-tests.sh` for unified local CI.
+- `target/`: Cargo build artifacts (ignored by git).
 
-### Building and Testing
+## Key Guidelines
 
-1. **Build the project**:
-   ```bash
-   cargo build
-   # For release builds:
-   cargo build --release
-   ```
+1. Follow idiomatic Rust patterns: prefer `Result` error handling, avoid `unwrap` in production paths, and document `unsafe` usage clearly if unavoidable.
+2. Keep shared abstractions inside `psst-core`; front ends should depend on those APIs rather than duplicating logic.
+3. When touching the GUI, ensure state flows through the controller/data layers to keep UI widgets declarative.
+4. Add tests for new behaviour. Use integration tests for player/session flows and unit tests for isolated components. Wire new suites into `./scripts/run-tests.sh`.
+5. Adopt the branching strategy below before committing changes.
 
-2. **Run tests**:
-   ```bash
-   cargo test --workspace --all-targets
-   ```
+## Branching Strategy
 
-3. **Check formatting and linting**:
-   ```bash
-   cargo fmt --check
-   cargo clippy -- -D warnings
-   ```
-
-4. **Run the GUI application**:
-   ```bash
-   cargo run --bin psst-gui
-   ```
-
-### Platform-Specific Considerations
-
-- **Linux**: Requires GTK-3, OpenSSL, and ALSA development libraries
-  - Debian/Ubuntu: `libssl-dev libgtk-3-dev libcairo2-dev libasound2-dev`
-  - RHEL/Fedora: `openssl-devel gtk3-devel cairo-devel alsa-lib-devel`
-- **macOS**: Standard development tools required
-- **Windows**: Standard development tools required
-
-### Code Organization
-
-- Keep synchronous architecture (no tokio or async runtime currently)
-- Use HTTPS-based CDN for audio file retrieval
-- Separate concerns between protocol, core logic, and UI layers
-- Follow existing patterns in each crate
-
-### Testing
-
-- Write unit tests in the crate's `tests` directory
-- Integration tests should cover cross-crate functionality
-- Test both success and error paths
-- Mock external Spotify API calls when possible
-
-## Pull Request Guidelines
-
-When creating or updating pull requests:
-
-1. Ensure all tests pass: `cargo test --workspace --all-targets`
-2. Verify code style: `cargo fmt --check && cargo clippy -- -D warnings`
-3. Keep changes focused and minimal
-4. Update relevant documentation in README.md or code comments
-5. Reference related issues using "Fixes #issue" or "Towards #issue"
-6. Label pull requests appropriately
-7. For LLM-generated PRs, always indicate this in the description
-
-## Privacy and Security
-
-- **Never commit Spotify credentials** or authentication tokens
-- Use reusable authentication tokens from Spotify (not stored user credentials)
-- Only connect to official Spotify servers
-- Keep local caches user-deletable
-- Follow Spotify's API terms of service
-
-## Common Tasks
-
-### Adding a New Feature
-
-1. Identify which crate(s) need changes
-2. Add necessary dependencies to `Cargo.toml`
-3. Implement feature following existing patterns
-4. Add tests for new functionality
-5. Update documentation
-6. Test on all target platforms if possible
-
-### Fixing Bugs
-
-1. Reproduce the issue
-2. Add a failing test that demonstrates the bug
-3. Fix the issue
-4. Verify the test now passes
-5. Check for similar issues elsewhere
-
-### Performance Optimization
-
-- Profile before optimizing
-- Use `cargo build --release` for benchmarking
-- Consider impact on audio playback quality
-- Test on resource-constrained systems
-
-## Important Notes
-
-- This project does not support Spotify Connect (remote control) yet
-- Audio playback should be glitch-free and responsive
-- UI should remain responsive during network operations
-- Cache management should be memory-efficient
-- A Spotify Premium account is required for testing
-
-## Resources
-
-- Project README: `/README.md`
-- Rust documentation: Standard library docs
-- Druid documentation: https://github.com/linebender/druid
-- Spotify protocol details: See psst-protocol crate
+- Start new feature work from `dev` using a short-lived feature branch (`feature/<slug>`). Keep the branch focused and rebased as needed.
+- Build and test the feature branch locally; once it passes, merge it back into `dev` and delete the feature branch.
+- Periodically (after a batch of features or when a release feels ready), merge `dev` into `main` following the same test/verification checklist.

README.md

@@ -27,6 +27,16 @@ You can download the latest release for Windows, Linux, and macOS from the [GitH
 
 Unofficial builds of Psst are also available through the [AUR](https://aur.archlinux.org/packages/psst-git) and [Homebrew](https://formulae.brew.sh/cask/psst).
 
+### Automatic Updates
+
+Psst includes automatic update checking to keep you informed about new releases. By default, the app will check for updates on startup (no more than once per 24 hours). You can:
+- View available updates in **Preferences > Updates**
+- Manually check for updates at any time
+- Disable automatic checks if preferred
+- Dismiss specific versions you don't want to install
+
+See [docs/UPDATES.md](docs/UPDATES.md) for more information.
+
 ## Building
 
 On all platforms, the **latest [Rust](https://rustup.rs/) stable** (at least 1.65.0) is required.
@@ -130,6 +140,7 @@ cargo bundle --release
   - Rename playlist
   - Playlist folders
 - [x] Playback queue
+- [x] Automatic update checking
 - [ ] React to audio output device events
   - Pause after disconnecting headphones
   - Transfer playback after connecting headphones

TODO.md → docs/TODO.md

@@ -6,5 +6,4 @@
 
 # TODO: Support custom themes with the given theme editor under the Appearance settings view and implement export/import functionality for sharing color palettes and typography by defining a theming schema, adding live preview tooling (including font pickers limited to installed fonts), wiring persistence, and wiring export/import buttons that export the theme config to a user-chosen location OR load from a user-selected file.
 
-# ✅ COMPLETED: Added comprehensive test suite with 70+ tests covering edge cases, error handling, unit tests, and integration tests. Tests can be run from ./scripts/run-tests.sh and are integrated into CI gating. See TESTING.md for details.
-
+# ✅ COMPLETED: Added comprehensive test suite with 70+ tests covering edge cases, error handling, unit tests, and integration tests. Tests can be w