1## Ungabunga Browser
 2
 3A minimal web browser built with Qt6 WebEngine. All persistent data (history,
 4bookmarks, credentials) lives in one portable SQLite file. Website sessions
 5(cookies, localStorage, cache) are not stored between launches — semi-incognito
 6by default.
 7
 8### Build
 9
10```sh
11# Dependencies (Void Linux):
12sudo xbps-install -S qt6-base-devel qt6-webengine-devel sqlite-devel libsodium-devel
13sudo xbps-install -S hunspell hunspell-en
14
15cmake -B build
16cmake --build build
17```
18
19### Usage
20
21On first run, the browser prompts you to set a master password for the
22encrypted credential vault. Subsequent launches require the master password to
23unlock the vault.
24
25Binary: `build/browser`
26
27### Features
28
29- **Tabbed browsing** – open/close tabs (Ctrl+T, Ctrl+W), cycle with Ctrl+Tab /
30  Ctrl+Shift+Tab, close with middle-click. `target="_blank"` and
31  `window.open()` open new tabs.
32- **Address bar** – type a URL or search query (DuckDuckGo). History-based
33  autocomplete (last 1000 entries). Enter navigates; searches if input contains
34  spaces or lacks a domain pattern.
35- **Bookmarks** – toggle on/off per page with Ctrl+D. Stored in SQLite.
36- **History** – every page visit (URL, title, timestamp) is saved to SQLite.
37- **Dark mode** – toggle via toolbar button. Applies a dark QPalette and
38  reloads pages so `prefers-color-scheme` is re-evaluated.
39- **DevTools** – per-tab Chromium DevTools panel, toggled via toolbar button or
40  "Inspect Element" context menu.
41- **Downloads** – downloads go to `~/Downloads`. A collapsible download bar
42  shows progress per file; cancel during progress, dismiss when
43  complete/failed. Clears completed downloads in bulk.
44- **Fullscreen** – triggered by pages (F11). Exit with Escape. Toolbar/tab bar
45  hidden while fullscreen.
46- **Permissions** – prompts for camera, microphone, geolocation, and
47  notifications on a per-origin basis.
48- **Zoom** – Ctrl+/Ctrl- to zoom, Ctrl+0 to reset. Zoom level is persisted per
49  domain in SQLite and restored on navigation.
50- **Password vault** – encrypted with XChaCha20-Poly1305 AEAD. The data
51  encryption key (DEK) is wrapped with a key encryption key (KEK) derived from
52  the master password via Argon2id. The DEK exists only in memory while
53  unlocked.
54  - **Capture** – JavaScript injected via QWebChannel observes login forms. On
55    form submission, the origin, username, and password are forwarded to the
56    C++ backend.
57  - **Save/Update** – prompts to save new credentials or update existing ones
58    for the same origin+username. Skips if the password is unchanged.
59  - **Autofill** – on page load, if exactly one credential exists for the host,
60    it is filled automatically. Multiple credentials show a popup menu
61    (Ctrl+Shift+L or toolbar button) to pick which to fill.
62- **Spell check** – enabled for en_US. Requires hunspell BDIC files at
63  `~/.local/share/qtwebengine_dictionaries/`:
64  ```sh
65  sudo xbps-install -S hunspell-en
66  mkdir -p ~/.local/share/qtwebengine_dictionaries
67  cp /usr/share/hunspell-bdic/en_US.bdic ~/.local/share/qtwebengine_dictionaries/
68  ```
69
70### Database
71
72Everything is in one SQLite file — easy to backup, restore, or migrate. Located
73at `QStandardPaths::AppDataLocation/browser.db`:
74
75- `history` – URL, title, last visit time
76- `bookmarks` – URL, title, created time
77- `passwords` – origin, username, encrypted password (ciphertext + nonce), timestamps
78- `vault_meta` – key-value store for the encrypted DEK, Argon2 salt/cost parameters
79- `domain_settings` – key-value store per domain (used for zoom factor persistence)
80
81### Dependencies
82
83- Qt6 (Widgets, WebEngineWidgets, Sql, WebChannel)
84- libsodium (>= 1.0.18)
85- hunspell (runtime only, for spell check dictionaries)
86- CMake >= 3.21, C++17 compiler