# Balanced Breakfast

A desktop feed aggregator that unifies RSS, Hacker News, arXiv, and other sources into a single timeline. Built with Tauri 2, Rust, and a Rhai plugin system for extensible feed fetching.

## Prerequisites

- **Rust** (stable toolchain, 2021 edition)
- **Tauri 2 CLI** (`cargo install tauri-cli --version '^2'`)
- **Linux only:** system dependencies for WebKitGTK
  ```
  # Debian/Ubuntu
  sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file \
      libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev

  # Arch
  sudo pacman -S webkit2gtk-4.1 base-devel curl wget file openssl \
      appmenu-gtk-module libappindicator-gtk3 librsvg2-dev
  ```
- **macOS / Windows:** no extra system dependencies beyond Rust and the Tauri CLI.

## Build and Run

```sh
# Development (hot-reload frontend, debug backend)
cargo tauri dev

# Production build (macOS DMG, Windows installer, Linux AppImage)
cargo tauri build

# Run all workspace tests
cargo test --workspace
```

## Workspace Architecture

The project is a Cargo workspace with four library crates and one application crate:

| Crate | Path | Role |
|-------|------|------|
| `bb-interface` | `crates/bb-interface/` | Shared types for the plugin system: `FeedItem`, `FetchResult`, `ConfigSchema`, `ConfigField`, `BusserCapabilities`. Defines the contract between plugins and the host. |
| `bb-core` | `crates/bb-core/` | Orchestrator (feed refresh scheduling, lifecycle), Rhai plugin runtime (engine setup, script loading, host function registration), config encryption, URL tracker-stripping. |
| `bb-feed` | `crates/bb-feed/` | Feed aggregation and ordering. Merges items from all active sources and applies sort modes (newest, scored, unread-first, starred-first). |
| `bb-db` | `crates/bb-db/` | SQLite persistence via sqlx. Repositories for feeds, items, tags, and busser key-value state. FTS5 full-text search. |
| `src-tauri` | `src-tauri/` | Tauri 2 desktop shell. Tauri commands (thin wrappers over the library crates), app state, background auto-fetch, frontend (vanilla HTML/CSS/JS). |

Dependency flow: `bb-interface` is leaf (no internal deps) -> `bb-core` and `bb-feed` depend on `bb-interface` -> `bb-db` depends on `bb-interface` -> `src-tauri` depends on all four.

Shared libraries from `../MNW/shared/`: [theme-common](../MNW/shared/theme-common/) (theme loading), [tagtree](../MNW/shared/tagtree/) (tag validation), [synckit-client](../MNW/shared/synckit-client/) (cloud sync SDK).

## Features

- **Unified timeline** -- RSS, Atom, JSON Feed, Hacker News, arXiv, and custom sources merged into one feed
- **Plugin system** -- Rhai scripting for extensible feed fetching (write a plugin for any source)
- **Reader view** -- clean article rendering with HTML sanitization via DocEngine
- **Search** -- FTS5 full-text search across all items with sanitized indexing
- **Organization** -- tags, starred items, read/unread tracking, query feeds (saved dynamic filters)
- **Auto-fetch scheduling** -- configurable per-plugin fetch intervals, circuit breaker after consecutive failures
- **Feed health tracking** -- visual status indicators (green/yellow/red) per source
- **Cloud sync** -- SyncKit integration with E2E encryption (feeds, tags, read state, preferences)
- **OTA updates** -- background update checker with consent dialog (Tauri updater v2)
- **17 bundled themes** -- dark, light, and high-contrast variants in TOML format, system auto-detection
- **Platforms** -- macOS, Windows, Linux (native via Tauri 2)

## Plugin Authoring

Plugins ("bussers") are `.rhai` script files. Drop one into the plugins directory and it loads on next launch.

- **Dev:** `plugins/` at the project root
- **Prod:** `<app_config_dir>/plugins/` (e.g. `~/Library/Application Support/com.balancedbreakfast.app/plugins/` on macOS)

Every plugin defines four functions (`id`, `name`, `config_schema`, `fetch`) plus an optional `capabilities()`. Full authoring guide with field types, return shapes, host functions, and examples: [docs/plugin_authoring.md](docs/plugin_authoring.md).

## Bundled Plugins

Eleven plugins ship with the app:

| Plugin | Source |
|--------|--------|
| `rss.rhai` | RSS, Atom, and JSON Feed |
| `hackernews.rhai` | Hacker News stories |
| `arxiv.rhai` | arXiv papers |
| `reader.rhai` | Web page reader view |
| `github_trending.rhai` | GitHub trending repositories |
| `devto.rhai` | Dev.to articles |
| `lobsters.rhai` | Lobsters community |
| `xkcd.rhai` | XKCD comics |
| `nasa_apod.rhai` | NASA Astronomy Picture of the Day |
| `earthquakes.rhai` | USGS earthquake data |
| `nws_alerts.rhai` | National Weather Service alerts |

## Key Paths

| What | Where |
|------|-------|
| Plugin contract types | `crates/bb-interface/src/` |
| Plugin runtime + orchestrator | `crates/bb-core/src/` |
| Feed aggregation | `crates/bb-feed/src/` |
| Database layer | `crates/bb-db/src/` |
| Tauri commands | `src-tauri/src/commands/` |
| Frontend JS | `src-tauri/frontend/js/` |
| Styles | `src-tauri/frontend/css/styles.css` |
| Bundled plugins | `plugins/` |
| Plugin authoring guide | `docs/plugin_authoring.md` |
| Architecture | `docs/architecture.md` |

## License

PolyForm Noncommercial 1.0.0