# Balanced Breakfast Frontend Architecture

Vanilla JavaScript frontend for the Tauri 2 desktop feed aggregator. No framework, no build step, no bundler. 14 source files organized under the `BB` global namespace.

## Namespace

All code lives under `window.BB`. No other globals. Cross-module calls use `BB.moduleName.functionName()`.

```
BB
  .api          Tauri IPC abstraction (api.js)
  .state        Proxy-based reactive state with pub/sub (state.js)
  .ui           Toast, modal, form builder, progress bar, confirm dialog (components.js)
  .utils        HTML escaping, sanitization, debounce (utils.js)
  .sources      Sources sidebar, tag filtering, feed edit/delete (sources.js)
  .items        Items list, selection, read/star toggle, pagination (items.js)
  .detail       Detail panel, reader view, save-to-file (detail.js)
  .feeds        Add feed (plugin picker + schema form), refresh, OPML import/export (feeds.js)
  .queryFeeds   Query feed CRUD, condition builder modal (query-feeds.js)
  .themes       Theme loading, CSS variable derivation, selector UI (themes.js)
  .sync         SyncKit cloud sync settings UI (settings-sync.js)
  .updater      OTA update banner (updater.js)
  .app          Bootstrap, keyboard shortcuts, menu listeners, settings (app.js)
```

## Module Inventory

| Module | File | Purpose |
|--------|------|---------|
| Namespace | `bb.js` | Creates `window.BB` with empty sub-namespace slots |
| State | `state.js` | Proxy-wrapped reactive store with `subscribe()`, `set()`, `get()`, `resetPagination()` |
| API | `api.js` | Thin `invoke()` wrappers grouped by domain (sources, items, plugins, feeds, opml, queryFeeds, reader, actions, sync) |
| Utils | `utils.js` | `escapeHtml`, `escapeAttr`, `sanitizeHtml`, `debounce`, `getErrorMessage` |
| Components | `components.js` | `showToast`, `showProgress`, `openModal`, `closeModal`, `openFormModal`, `showErrorWithRetry`, `confirmAction` |
| Query Feeds | `query-feeds.js` | CRUD for saved filter rules, condition builder modal with field/operator/value rows |
| Sources | `sources.js` | Sidebar rendering, source selection, tag bar, feed popover (health/edit/delete), feed edit/tags forms |
| Items | `items.js` | Item list rendering, selection, star/read toggle with in-flight guards, pagination, saved-articles view |
| Detail | `detail.js` | Detail panel rendering, reader view extraction, save-to-file as HTML, plugin action buttons, saved-items localStorage |
| Feeds | `feeds.js` | Two-step add-feed flow (plugin picker then schema form), refresh with progress bar, OPML import/export, plugin warning |
| Settings/Sync | `settings-sync.js` | 4-state sync UI (connect, authenticating, encryption, ready), API key flow, sync event listener |
| Themes | `themes.js` | Load/apply themes via Tauri IPC, derive CSS variables from theme colors, theme selector `<select>` builder |
| Updater | `updater.js` | OTA update banner with consent (Install & Restart / Not Now), listens for `update-available` and `menu:check_updates` events |
| App | `app.js` | `init()` bootstrap, keyboard shortcuts (vim-style j/k), search debounce, sort select, native menu listeners, settings/help/welcome modals |

## Module Pattern

Every module is an IIFE that registers its public API on the namespace:

```javascript
(function() {
    'use strict';

    // Private constants and helpers
    const ITEMS_PER_PAGE = 50;
    function privateHelper() { ... }

    // Public functions
    async function load() { ... }
    function render(items) { ... }

    // Register on namespace
    BB.myModule = { load, render };
})();
```

Rules:
- All modules use `'use strict'`
- Private state stays inside the IIFE closure (e.g., `currentItem` in detail.js, `inFlight` set in items.js)
- Public API is the object assigned to `BB.moduleName`
- No `window.X` exports besides `window.BB`
- Prefer `async/await` over `.then()` chains

## State Management

`BB.state` is a `Proxy` over a plain data object. Property reads go through the proxy `get` trap; property writes trigger `set()` which notifies subscribers.

### Reading state

```javascript
const items = BB.state.items;
const source = BB.state.currentSource;
// or explicit:
const page = BB.state.get('currentPage');
```

### Writing state

```javascript
BB.state.set('items', updatedItems);      // Triggers subscribers
BB.state.currentSource = 'my-feed';       // Also triggers (via Proxy set trap)
```

### Subscribing to changes

```javascript
const unsub = BB.state.subscribe('items', (newItems, oldItems) => {
    render(newItems);
});
```

### State properties

| Property | Type | Domain |
|----------|------|--------|
| `sources` | Array | Data -- feed sources with counts |
| `items` | Array | Data -- feed items for current view |
| `queryFeeds` | Array | Data -- saved filter rules |
| `allTags` | Array | Data -- distinct tags across all feeds |
| `currentSource` | string | Filter -- busser_id or `''` for all, `'__saved__'` for saved |
| `currentOrder` | string | Filter -- `'chronological'`, `'score'`, `'unread'`, `'starred'` |
| `currentSearch` | string | Filter -- search query text |
| `currentTag` | string | Filter -- tag filter or `''` for all |
| `currentQueryFeed` | string/null | Filter -- active query feed ID |
| `currentPage` | number | Pagination -- zero-indexed page |
| `hasMore` | boolean | Pagination -- backend has more pages |
| `selectedItemId` | string/null | Selection -- active item in list |
| `selectedPluginId` | string/null | UI -- plugin chosen in add-feed flow |

`resetPagination(clearSelection?)` is a convenience method that sets `currentPage` to 0 and optionally clears `selectedItemId`.

## Three-Panel Layout Data Flow

The UI has three columns: sources sidebar (left), items list (center), detail panel (right).

```
User clicks source in sidebar
  -> BB.sources.select(sourceId)
  -> BB.state.set('currentSource', sourceId)
  -> BB.state.resetPagination(true)
  -> BB.items.load()
     -> BB.api.items.list(filter)          // IPC to Rust
     -> Rust filters + paginates + returns
     -> BB.state.set('items', data.items)  // triggers subscriber
     -> BB.items.render(items)             // subscriber re-renders list
```

```
User clicks item in list
  -> BB.items.selectItem(id)
  -> BB.state.set('selectedItemId', id)
  -> BB.detail.load(id)
     -> BB.api.items.get(id)               // IPC to Rust
     -> BB.detail.renderDetail(item)       // renders detail panel
  -> BB.api.items.markRead(id)             // background, then reload
```

### Reactive subscriptions

Two state subscriptions drive automatic re-rendering:
- `BB.state.subscribe('items', render)` in items.js -- re-renders item list on any items change
- `BB.state.subscribe('sources', render)` in sources.js -- re-renders sidebar on source list change
- `BB.state.subscribe('items', onItemsChanged)` in detail.js -- merges updated summary fields into the detail view

## API Layer

`BB.api` wraps every Tauri IPC command. The UI never calls `__TAURI__.core.invoke` directly (except themes.js and app.js which use `invoke` for config get/set).

```javascript
const sources = await BB.api.sources.list();
const data = await BB.api.items.list({ source: 'my-feed', page: 0 });
await BB.api.items.star(itemId);
await BB.api.feeds.create({ busserId: 'rss', name: 'My Feed', config: { url: '...' } });
```

API groups:

| Group | Commands |
|-------|----------|
| `sources` | `list` |
| `items` | `list`, `get`, `markRead`, `markUnread`, `star`, `unstar`, `unreadCount` |
| `plugins` | `list`, `schema` |
| `feeds` | `getByBusser`, `get`, `create`, `update`, `delete`, `deleteByBusser`, `fetchAll`, `setTags`, `listAllTags`, `resetCircuitBreaker` |
| `opml` | `export`, `import` |
| `queryFeeds` | `list`, `create`, `update`, `delete` |
| `reader` | `extract` |
| `actions` | `downloadAndOpen` |
| `sync` | `testApiKey`, `saveApiKey`, `status`, `startAuth`, `completeAuth`, `disconnect`, `now`, `setupEncryptionNew`, `setupEncryptionExisting`, `updateSettings` |

## Form Modal System

`BB.ui.openFormModal()` builds a form from a field specification array and handles submit/cancel:

```javascript
BB.ui.openFormModal({
    title: 'Add RSS Feed',
    fields: [
        { name: 'name', type: 'text', label: 'Feed Name', required: true },
        { name: 'url', type: 'text', label: 'URL', required: true, placeholder: 'https://...' },
    ],
    submitLabel: 'Add Feed',
    onSubmit: async (data) => {
        await BB.api.feeds.create({ busserId: 'rss', name: data.name, config: { url: data.url } });
        BB.ui.showToast('Feed created!');
    },
});
```

Supported field types: `text`, `textarea`, `select`, `secret` (renders as password), plus any HTML input type.

The two-step add-feed flow in feeds.js uses this system: step 1 shows a plugin picker list, step 2 calls `BB.api.plugins.schema(pluginId)` to get the plugin's config fields and passes them to `openFormModal()`.

## Load Order

Scripts load in order via `<script>` tags in `index.html`:

1. `bb.js` -- creates `window.BB` namespace with empty sub-objects
2. `themes.js` -- populates `BB.themes` (init, load, buildSelector)
3. `utils.js` -- populates `BB.utils` (escapeHtml, escapeAttr, sanitizeHtml, debounce, getErrorMessage)
4. `state.js` -- replaces `BB.state` with Proxy-wrapped reactive store
5. `api.js` -- replaces `BB.api` with invoke wrappers
6. `components.js` -- replaces `BB.ui` with toast/modal/form/confirm functions
7. `query-feeds.js` -- populates `BB.queryFeeds` (depends on utils, state, api, ui)
8. `sources.js` -- populates `BB.sources` (depends on utils, state, api, ui, queryFeeds)
9. `items.js` -- populates `BB.items` (depends on utils, state, api, ui, detail)
10. `detail.js` -- populates `BB.detail` (depends on utils, state, api, ui)
11. `feeds.js` -- populates `BB.feeds` (depends on utils, state, api, ui, sources, items)
12. `settings-sync.js` -- populates `BB.sync` (depends on api, ui)
13. `updater.js` -- populates `BB.updater` (depends on ui, utils)
14. `app.js` -- populates `BB.app`, auto-calls `init()` on DOMContentLoaded

Note: items.js (9) references `BB.detail` at call time (not load time), so the forward reference to detail.js (10) resolves by the time `init()` runs.

## Key Utility Functions

```javascript
BB.utils.escapeHtml(str)         // XSS prevention for innerHTML
BB.utils.escapeAttr(str)         // Attribute-safe escaping
BB.utils.sanitizeHtml(html)      // DOM-based sanitizer for rich content (strips script, iframe, on* attrs, javascript: URLs)
BB.utils.debounce(fn, delay)     // Delay execution until after last call
BB.utils.getErrorMessage(err)    // Extract string from Tauri ApiError or any error shape
```

`sanitizeHtml` is specific to BB (not present in GO). It uses a detached DOM element to parse HTML, then walks the tree removing dangerous elements (`script`, `iframe`, `object`, `embed`, `form`, `style`, `base`) and dangerous attributes (`on*` handlers, `javascript:`/`data:`/`vbscript:` URLs). Used by detail.js to render feed item bodies.

## Tauri Event Listeners

Several modules subscribe to Tauri events beyond IPC commands:

| Event | Listener | Purpose |
|-------|----------|---------|
| `fetch-progress` | feeds.js | Per-plugin progress during refresh |
| `auto-fetch-complete` | app.js | Background auto-fetch finished, reload sources+items |
| `auto-fetch-error` | app.js | Background fetch error, show toast |
| `feed-circuit-broken` | app.js | Feed disabled after repeated failures, show retry toast |
| `menu:refresh` | app.js | Native menu bar Refresh action |
| `menu:add_feed` | app.js | Native menu bar Add Feed |
| `menu:import_opml` | app.js | Native menu bar Import OPML |
| `menu:export_opml` | app.js | Native menu bar Export OPML |
| `menu:view_all` | app.js | Native menu bar View All |
| `menu:view_unread` | app.js | Native menu bar View Unread |
| `menu:view_starred` | app.js | Native menu bar View Starred |
| `menu:check_updates` | updater.js | Native menu bar Check for Updates |
| `update-available` | updater.js | OTA update detected by Rust backend |
| `sync:changes-applied` | settings-sync.js | SyncKit pulled remote changes, reload sources+items |

## CSS

Single stylesheet at `frontend/css/styles.css`. Uses CSS variables set by themes.js at runtime. Theme colors come from shared TOML files in `MNW/shared/themes/` loaded via `get_theme` Tauri command.

Theme-derived CSS variables:

| Variable | Source |
|----------|--------|
| `--bg-primary` | `background.primary` |
| `--bg-secondary` | `background.secondary` |
| `--bg-tertiary` | `background.tertiary` |
| `--text-primary` | `foreground.primary` |
| `--text-secondary` | `foreground.secondary` |
| `--text-muted` | `foreground.muted` |
| `--accent` | `accent.red` |
| `--accent-hover` | `accent.red` lightened 10% |
| `--yolk` | `accent.yellow` |
| `--yolk-light` | `accent.yellow` lightened 15% |
| `--border` | `border.default` |
| `--border-dark` | `border.default` darkened 10% |
| `--shadow` | `foreground.primary` at 8% opacity |
| `--shadow-hover` | `foreground.primary` at 12% opacity |
| `--success` | `accent.green` |

## Key Paths

| What | Where |
|------|-------|
| Namespace root | `src-tauri/frontend/js/bb.js` |
| State manager | `src-tauri/frontend/js/state.js` |
| API layer | `src-tauri/frontend/js/api.js` |
| UI components | `src-tauri/frontend/js/components.js` |
| Items list | `src-tauri/frontend/js/items.js` |
| Detail panel | `src-tauri/frontend/js/detail.js` |
| Sources sidebar | `src-tauri/frontend/js/sources.js` |
| Feed management | `src-tauri/frontend/js/feeds.js` |
| Query feeds | `src-tauri/frontend/js/query-feeds.js` |
| Theme system | `src-tauri/frontend/js/themes.js` |
| Sync settings | `src-tauri/frontend/js/settings-sync.js` |
| OTA updater | `src-tauri/frontend/js/updater.js` |
| App bootstrap | `src-tauri/frontend/js/app.js` |
| Styles | `src-tauri/frontend/css/styles.css` |
| Entry point | `src-tauri/frontend/index.html` |
| JS tests | `src-tauri/frontend/js/tests/` |